{"id":44664492,"url":"https://github.com/gocloudla/gocloud-cli","last_synced_at":"2026-04-19T01:16:09.320Z","repository":{"id":338514321,"uuid":"1056799769","full_name":"gocloudLa/gocloud-cli","owner":"gocloudLa","description":"GoCloud CLI - Command-line interface for managing Terraform and Standard Platform operations","archived":false,"fork":false,"pushed_at":"2026-04-02T18:16:54.000Z","size":250,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-03T05:22:56.680Z","etag":null,"topics":["automation","cli","devops","gocloud","golang","infrastructure","management","standard-platform","terraform","tool"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gocloudLa.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-14T20:31:59.000Z","updated_at":"2026-04-02T18:16:49.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/gocloudLa/gocloud-cli","commit_stats":null,"previous_names":["gocloudla/gocloud-cli"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/gocloudLa/gocloud-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gocloudLa%2Fgocloud-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gocloudLa%2Fgocloud-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gocloudLa%2Fgocloud-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gocloudLa%2Fgocloud-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gocloudLa","download_url":"https://codeload.github.com/gocloudLa/gocloud-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gocloudLa%2Fgocloud-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31381009,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-03T21:40:47.592Z","status":"ssl_error","status_checked_at":"2026-04-03T21:40:05.436Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","cli","devops","gocloud","golang","infrastructure","management","standard-platform","terraform","tool"],"created_at":"2026-02-15T00:16:21.354Z","updated_at":"2026-04-19T01:16:09.306Z","avatar_url":"https://github.com/gocloudLa.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GoCloud CLI\n\nA command-line tool to generate and manage infrastructure-as-code project structure using Terraform/Terragrunt. It is the companion CLI for the **[GoCloud Standard Platform](https://github.com/gocloudLa/terraform-aws-standard-platform)** — an enterprise-ready AWS infrastructure platform with a layered architecture (Organization → Base → Foundation → Project → Workload) and 50+ pre-configured AWS services.\n\n\u003e **Beta.** This software is in beta. Use it at your own responsibility.\n\n## What it does\n\n- **Generate directory structure** for Terraform/Terragrunt projects\n- **Create config files** (main.tf, metadata.tf, terragrunt.hcl, etc.)\n- **Manage secrets** in AWS SSM Parameter Store or SOPS\n- **Configure AWS SSO** and generate `.aws/config`\n- **Validate** YAML configuration before generating\n\n**Note:** GoCloud CLI **does not run Terraform** — it only generates files and structure.\n\n### Standard Platform \u0026 documentation\n\nThe structure and `main.tf` files generated by GoCloud CLI are designed to use the **[Standard Platform](https://github.com/gocloudLa/terraform-aws-standard-platform)** Terraform modules:\n\n- **[terraform-aws-standard-platform](https://github.com/gocloudLa/terraform-aws-standard-platform)** — Platform repo: layers (organization, security, base, foundation, project, workload), usage examples, and module documentation\n- **Terraform Registry:** [gocloudLa/standard-platform/aws](https://registry.terraform.io/namespaces/gocloudLa) — Published modules (e.g. `gocloudLa/standard-platform/aws//modules/base`)\n- **[GoCloud (gocloudLa)](https://github.com/gocloudLa)** — Organization and other tools; [gocloud.la](https://gocloud.la) for more info\n\n## Install\n\n### Option 1: Download binary (recommended)\nBinaries are published on [GitHub Releases](https://github.com/gocloudLa/gocloud-cli/releases). Asset names: `gocloud-\u003cversion\u003e-\u003cos\u003e-\u003carch\u003e` (e.g. `gocloud-v1.2.3-darwin-arm64` for Apple Silicon).\n\n```bash\n# Replace VERSION with the desired release (e.g. v1.2.3)\ncurl -sL -o gocloud \"https://github.com/gocloudLa/gocloud-cli/releases/download/VERSION/gocloud-VERSION-darwin-arm64\"\nchmod +x gocloud\nsudo mv gocloud /usr/local/bin/\n```\n\n### Option 2: Build from source\n```bash\ngit clone https://github.com/gocloudLa/gocloud-cli.git\ncd gocloud-cli\nmake build\nsudo cp bin/gocloud /usr/local/bin/\n```\n\nCheck for updates: `gocloud version check`. Update on macOS/Linux: `gocloud version update`.\n\n## Quick start\n\n```bash\ngocloud config init my-project    # Interactive config\ncd my-project\ngocloud config validate      # Validate gocloud.yaml\ngocloud generate             # Generate directory tree and files\ngocloud sso setup            # Write .aws/config with profiles\ngocloud sso login --all      # Login to all SSO profiles\n# gocloud secrets init --all # Optional: create empty secrets for all layers\n```\n\n## Commands\n\n### Version and update\n\n#### `gocloud version [check|update]`\nShows current CLI version; subcommands compare with GitHub Releases or replace the binary (macOS/Linux when a matching release asset exists). Installation steps for all platforms are documented on [GitHub Releases](https://github.com/gocloudLa/gocloud-cli/releases).\n\n```bash\ngocloud version        # Current version (build time, commit)\ngocloud version check  # Check if you're on the latest release\ngocloud version update # Download and replace this binary (macOS/Linux only)\n```\n\n### Config\n\n#### `gocloud config init [project-name]`\nCreates a new `gocloud.yaml` via interactive prompts.\n\n```bash\ngocloud config init my-project                     # Simple usage\ngocloud config init my-project -o custom.yaml      # Custom output path\ngocloud config init my-project --skip-environments # Skip environment prompts\ngocloud config init my-project --skip-aws-sso      # Skip AWS SSO prompts\n```\n\n#### `gocloud config validate [--config file.yaml]`\nValidates the config file (required fields, types, unknown keys; reports errors and warnings).\n\n```bash\ngocloud config validate                      # Simple usage\ngocloud config validate --config custom.yaml # Validate specific file\ngocloud config validate --strict             # Extra validation rules\n```\n\n### Generate\n\n#### `gocloud generate [--config file.yaml]`\nReads `gocloud.yaml` and generates the directory tree (base, foundation, project, workload), config files (main.tf, metadata.tf, terragrunt.hcl, backend.tf, providers.tf, _secrets.tf where enabled), optionally a root `.gitignore` when `infrastructure.enable_gitignore` is not `false` (default: true), and project README.md. Validation runs first. New dirs/files are created without prompting; existing `main.tf` are never overwritten (only the module version line is updated when you change version in config); other changed files (including `.gitignore` when enabled) prompt before overwrite.\n\n```bash\ngocloud generate                          # Simple usage\ngocloud generate --dry-run                # Preview without writing files\ngocloud generate --force                  # Overwrite existing files (except main.tf)\ngocloud generate --working-dir custom-dir # Output to custom directory\ngocloud generate --config custom.yaml     # Use specific config file\n```\n\n### AWS SSO\n\n#### `gocloud sso setup`\nWrites `.aws/config` with one profile per environment (`{client}-{environment}`).\n\n```bash\ngocloud sso setup\n```\n\n#### `gocloud sso list`\nLists configured AWS SSO profiles (numbered for selection).\n\n```bash\ngocloud sso list\n```\n\n#### `gocloud sso login`\nLogin to AWS SSO profiles.\n\n```bash\ngocloud sso login                    # Interactive: choose profile\ngocloud sso login --all              # Login to all profiles\ngocloud sso login --profiles prd,sha # Login to specific profiles\n```\n\n#### `gocloud sso verify`\nChecks credential and account ID status (OK / Expired or Invalid / Account Mismatch).\n\n```bash\ngocloud sso verify\n```\n\n### Secrets\n\nManage secrets (e.g. DB URLs, API keys) that Terraform reads in each layer. Available providers:\n\n- **SSM (default):** Stored in AWS. No extra tools; use your SSO profiles.\n- **SOPS:** Stored in encrypted files; requires the `sops` binary and KMS (details in **Secrets control** below).\n\n#### `gocloud secrets check [layer-path]`\nChecks if the secrets store exists for that layer (SSM: parameter; SOPS: `_secrets.yaml`).\n\n```bash\ngocloud secrets check base/production    # One layer\ngocloud secrets check --environment dev  # All layers in an environment\ngocloud secrets check --all              # All layers\n```\n\n#### `gocloud secrets init [layer-path]`\nCreates empty secrets for the layer (SSM: new parameter with `{}`; SOPS: creates or ensures `_secrets.yaml` and KMS key).\n\n```bash\ngocloud secrets init foundation/dev     # One layer\ngocloud secrets init --environment dev   # All layers in an environment\ngocloud secrets init --all               # All layers\n```\n\n#### `gocloud secrets list \u003clayer-path\u003e`\nLists all secret keys for that layer.\n\n```bash\ngocloud secrets list base/production\ngocloud secrets list project/core/production\n```\n\n#### `gocloud secrets get \u003clayer-path\u003e \u003ckey\u003e`\nGets the value of one secret key for that layer.\n\n```bash\ngocloud secrets get base/production database_url\ngocloud secrets get project/core/production api_key\n```\n\n#### `gocloud secrets set \u003clayer-path\u003e \u003ckey\u003e \u003cvalue\u003e`\nSets the value of one secret.\n\n```bash\ngocloud secrets set base/production database_url \"postgresql://...\"\ngocloud secrets set project/core/production api_key \"secret-key\"\n```\n\n#### `gocloud secrets delete \u003clayer-path\u003e \u003ckey\u003e`\nRemoves one secret key from that layer.\n\n```bash\ngocloud secrets delete base/production database_url\ngocloud secrets delete project/core/production api_key\n```\n\n#### `gocloud secrets edit \u003clayer-path\u003e`\nOpens your editor to edit the layer’s secrets as JSON (validated on save).\n\n```bash\ngocloud secrets edit base/production\ngocloud secrets edit project/core/production\n```\n\n### Health\n\nCheck AWS managed notification events per environment (AWS User Notifications / Notification Center → AWS managed). This helps reduce noise from emails/SNS by presenting events grouped by environment.\n\n#### `gocloud health check`\nLists managed notification events for one environment or all.\n\n```bash\ngocloud health check --environment prd\ngocloud health check --environment org  # organization account ({client}-org) when configured\ngocloud health check --environment sec  # security account ({client}-sec) when configured\ngocloud health check --all\n```\n\nFilter controls:\n\n```bash\ngocloud health check --all --managed-days 180\ngocloud health check --all --include-ended   # include events whose end time is already past\n```\n\nOutput format:\n\n```bash\ngocloud health check --all --output list   # default\ngocloud health check --all --output table\n```\n\n### Modules\n\nGenerate READMEs for Terraform modules from a YAML config and optional template.\n\n```bash\ngocloud module readme generate         # From README.yml (default), output README.md\ngocloud module readme generate-example # Same for example-style READMEs\n```\n\n### Shell completion\n\nPrints a script to source so that Tab completes commands, layer paths, and secret keys. Add to your shell profile (`~/.zshrc`, `~/.bashrc`, etc.).\n\n```bash\ngocloud completion bash       # Bash\ngocloud completion zsh        # Zsh (e.g. macOS default)\ngocloud completion fish       # Fish\ngocloud completion powershell # PowerShell\n```\n\n## Configuration file (`gocloud.yaml`)\n\nGoCloud uses a single YAML file to define your project: client name, AWS accounts and regions, layers to generate (see **Layer control**), backend (Terraform state), AWS SSO (login), and secrets (SSM or SOPS). Everything below is optional except the fields marked required. Default is set at **Infrastructure**; overrides apply in order: **Environment** → **Project** / **Workload** (more specific wins).\n\n**Override levels** (where each option can be set):\n\n| Config | Infrastructure | Environment | Project | Workload |\n|--------|:---:|:---:|:---:|:---:|\n| Backend | ✓ | ✓ | ✓ | ✓ |\n| Providers | ✓ | ✓ | ✓ | ✓ |\n| Secrets | ✓ | ✓ | ✓ | ✓ |\n| Terragrunt | ✓ | ✓ | ✓ | ✓ |\n| SSO | ✓ | ✓ | — | — |\n| Region | ✓ | ✓ | — | — |\n| Version | ✓ | ✓ | — | — |\n| Source | ✓ | ✓ | — | — |\n| Layers | ✓ | ✓ (base, foundation only) | — | — |\n| Metadata | ✓ | ✓ | — | — |\n\n### General structure\n\nBelow, each key is explained in comments. For backend and providers, see **Backend** and **Providers**.\n\n```yaml\n# CLI behaviour (all optional; uncomment to override)\ncli:\n  # working_dir: \".\"     # (default) project root\n  # auto_backup: true    # (default) backup config before overwriting\n  # backup_dir: \".bkp\"   # (default)\n  # verbose: false       # (default)\n  # debug: false         # (default)\n\ninfrastructure:\n  client: \"my-client\"     # Required. Client/project name (e.g. SSO profile names)\n  company: \"gcl\"          # Required. Short prefix, 2–10 chars (bucket names, SSM paths)\n  region: \"us-east-1\"     # Required. Default AWS region\n  # version: \"0.17.0\"       # (default) module version in main.tf\n  # enable_secrets: true    # (default: true) generate _secrets.tf and gocloud secrets commands\n  # enable_sso: true        # (default: true) generate SSO profile\n  # enable_terragrunt: true # (default: true) generate terragrunt.hcl files\n  # enable_gitignore: true  # (default: true) generate root .gitignore\n\n  # # Optional: use Git repo instead of Terraform registry for modules\n  # source: \"git@github.com:org/repo.git\"\n  # source_ref: \"main\"            # branch, tag, or commit\n\n  # Backend: Terraform state (S3 + DynamoDB).\n  backend:\n    # pattern: \"s3-backend\"      # (default)\n    # region: \"us-east-1\"        # (default: uses infrastructure.region)\n    # account: \"sha\"             # (default) environment key where state bucket lives\n    # encrypt: true              # (default)\n    # type: \"s3\"                 # (default)\n    # use_profile: true          # (default)\n    # key_template: \"...\"        # (optional) Custom state path\n    # role_template: \"...\"       # (optional) Custom assume_role name\n    # bucket_name: \"custom-bucket\"        # Custom bucket (optional; default: {company}-{account}-{pattern})\n    # dynamodb_table_name: \"custom-table\" # Custom lock table (optional; default: {company}-{account}-{pattern})\n\n  # AWS SSO: required for gocloud sso setup. Generates .aws/config with profiles {client}-{environment}.\n  aws_sso:\n    # region: \"us-east-1\"         # (default: uses infrastructure.region)\n    start_url: \"https://my-client.awsapps.com/start#/\"  # Required. IAM Identity Center URL\n    role_name: \"Admin\"           # Required. Role name after SSO login\n\n  # Layers (default: all true). organization/security only if respective aws_account set; see Layer control.\n  layers:\n  #   base: true                   # (default)\n  #   foundation: true             # (default)\n  #   organization: true           # (default)\n  #   security: true               # (default)\n\n  # Custom metadata (optional): injected into every metadata.tf.\n  # Default/fallback for all layers unless a more specific metadata is set.\n  # metadata:\n  #   public_domain: \"gocloud.la\"\n  #   private_domain: \"gocloud.private\"\n  metadata:\n    public_domain: \"gocloud.la\"  # (optional) add any key-value pairs\n    private_domain: \"gocloud.private\"\n    internal_domain: \"gocloud.internal\"\n\n  # Secrets backend (optional, default: \"ssm\")\n  # secrets:\n  #   type: \"ssm\"                 # or \"sops\"\n\n  # Providers: AWS providers in providers.tf. Uncomment to customize.\n  # providers:\n  #   use_profiles: true          # (default: true)\n  #   default_providers:\n  #     - name: \"aws\"\n  #       region: \"local.metadata.aws_region\"\n  #     - name: \"aws\"\n  #       region: \"us-east-1\"\n  #       alias: \"use1\"\n  #     # (optional) assume_role for cross-account\n  #     #   - name: \"aws\"\n  #     #     assume_role:\n  #     #       role_arn: \"arn:aws:iam::123456789012:role/RoleName\"\n  #     #       session_name: \"TerraformSession\"\n\n  # Optional: organization layer + SSO profile {client}-org (uncomment to enable)\n  organization:\n    aws_account: \"123456789012\"   # Required for SSO: creates profile {client}-org\n  #   metadata: {}                # (optional) metadata override for organization layer\n  #   enable_secrets: true        # (optional) secrets only for organization (overrides global enable_secrets)\n  #   aws_sso:                    # (optional) override SSO for org profile\n  #     start_url: \"https://...\"\n  #     role_name: \"Admin\"\n  #   backend: {}                 # (optional) override backend for organization layer\n  #   providers: {}               # (optional) override providers for organization layer\n  #  secrets:                     # (optional) override secrets type organization layer\n  #    type: \"sops\"\n\n  # Optional: security layer (global) + SSO profile {client}-sec — same fields as organization, dir security/, module //modules/security; generated main.tf wires aws.log and aws.kms into the module (override in main.tf if you use other aliases)\n  # security:\n  #   aws_account: \"123456789013\"\n  #   metadata: {}                # (optional) metadata override for security layer\n\n  # Environments: each key is an environment (shared, dev, production, etc.). Required: aws_account per env.\n  environments:\n    shared:\n      name: \"Shared\"              # (optional; default: key) display name\n      # dir_name: \"shared\"        # (optional; default: key) directory name in generated tree\n      aws_account: \"123456789013\" # Required. 12-digit AWS account ID\n      # region: \"us-east-1\"       # (default: infrastructure.region)\n      # version: \"0.17.0\"         # (default: infrastructure.version)\n      # enable_secrets: true      # (default: inherit from global)\n      # enable_sso: true          # (default: inherit from global)\n      # enable_terragrunt: true   # (default: true)\n      # layers:                   # (optional) disable layer for this environment\n      #   base: true\n      #   foundation: true\n      # aws_sso:                  # (optional) override start_url / role_name for this env\n      #   start_url: \"https://...\"\n      #   role_name: \"Admin\"\n      # metadata: {}              # (optional) metadata override for this environment\n      # secrets: { type: \"ssm\" }  # (optional) backend for this env\n      projects: [\"core\", \"common\"]   # Project subdirs (e.g. project/core/shared)\n      workloads: [\"webapp\", \"api\"]   # Workload subdirs (e.g. workload/webapp/shared)\n```\n\n---\n\n### Environments\n\n**What they are:** Each entry under `environments` is an environment (e.g. shared, dev, production) with its own AWS account (or shared). GoCloud generates one directory tree per environment under `base/\u003cenv\u003e`, `foundation/\u003cenv\u003e`, `project/\u003cname\u003e/\u003cenv\u003e`, `workload/\u003cname\u003e/\u003cenv\u003e`. Environments inherit global config; you can override per environment.\n\n```yaml\ninfrastructure:\n  environments:\n    dev:\n      name: \"Development\"         # (optional; default: key) display name\n      aws_account: \"111111111111\" # Required\n      # dir_name: \"dev\"           # (default: key)\n      # region: \"us-east-1\"       # (default: infrastructure.region)\n      # version: \"0.17.0\"         # (default: infrastructure.version)\n      # enable_secrets: true      # (default: inherit)\n      # enable_sso: true          # (default)\n      # enable_terragrunt: true   # (default)\n      # layers: { base: true, foundation: true }  # (optional)\n      # aws_sso: { start_url: \"...\", role_name: \"...\" }  # (optional) override for this env\n      # secrets: { type: \"ssm\" } # (optional)\n      projects: [\"core\", \"common\"]\n      workloads: [\"webapp\", \"api\"]\n    shared:\n      name: \"Shared\"\n      aws_account: \"111111111111\"\n      # dir_name: \"shared\"       # (default: key)\n      layers:                    # (optional) disable base only in this env\n        base: true\n        foundation: false\n      projects: [\"core\", \"common\"]\n      workloads: [\"webapp\", \"api\"]\n    production:\n      name: \"Production\"\n      dir_name: \"production\"     # (optional) custom dir name\n      aws_account: \"222222222222\"\n      region: \"eu-west-1\"        # (optional) override region\n      version: \"0.14.0\"          # (optional) override module version\n      enable_secrets: false      # (optional) disable secrets for this env\n      enable_sso: false          # (optional) no SSO profile for this env\n      aws_sso:                   # (optional) different SSO for this env\n        start_url: \"https://prod.awsapps.com/start#/\"\n        role_name: \"ProductionAdmin\"\n      projects: [\"core\", \"common\"]\n      workloads: [\"webapp\", \"api\"]\n```\n\n---\n\n### Projects and workloads\n\n**What they are:** For each environment you list *projects* (e.g. core, common) and *workloads* (e.g. webapp, api). They become directories like `project/core/production` and `workload/webapp/production`. The directory name is the key by default; you can set `name` (display + dir from lowercased name) or `dir_name` (exact directory name). Projects and workloads can have `depends_on` (e.g. project: `[\"foundation\"]` or `[]`; workload: which project layers they depend on) and per-item `enable_secrets` / `enable_terragrunt`.\n\n```yaml\ninfrastructure:\n  environments:\n    production:\n      projects:\n        - core                                # (default) dir = key\n        - common\n        - dept:                               # key: dept\n            name: \"Deposits\"                  # (optional) dir from name lowercased\n        - wdwl:\n            name: \"Withdrawals\"\n            dir_name: \"withdrawals\"           # (optional) exact dir name\n            # enable_terragrunt: true         # (default: true)\n      workloads:\n        - webapp\n        - api\n        - blockchain-service:\n            depends_on: [\"project/common\", \"project/core\"]  # (optional) custom deps\n        - legacy-app:\n            enable_secrets: false             # (optional) disable secrets for this workload\n        - dept:\n            name: \"Deposits\"\n            dir_name: \"deposits\"\n            enable_secrets: false\n            # depends_on: [\"project/core\"]    # (default: auto)\n```\n\n---\n\n### Layer control\n\nGoCloud generates: **organization** (if `infrastructure.organization.aws_account` set), **security** (if `infrastructure.security.aws_account` set), **base**, **foundation**, plus **project** / **workload** from each environment's lists. **Override levels:** see table above (Infrastructure + Environment only; per env only `base` and `foundation` can be disabled).\n\n**Example** (global + override per env):\n\n```yaml\ninfrastructure:\n  layers:\n    base: true\n    foundation: true\n    organization: true\n    security: true\n\n  environments:\n    staging:\n      layers:\n        base: false\n        foundation: true\n```\n\n---\n\n### Secrets control\n\nSecrets (e.g. DB URLs, API keys) are read by Terraform via `_secrets.tf`. GoCloud stores them in **SSM** (default) or **SOPS** (encrypted files; requires `sops` and KMS). Use `enable_secrets: false` to disable per layer, or `secrets.type: \"sops\"` to switch backend. **Override levels:** see table above.\n\n**Example** (global + overrides at env, project, workload):\n\n```yaml\ninfrastructure:\n  enable_secrets: true\n  secrets:\n    type: \"ssm\"\n\n  environments:\n    production:\n      secrets:\n        type: \"sops\"\n      projects:\n        - example:\n            secrets:\n              type: \"sops\"\n      workloads:\n        - legacy-app:\n            enable_secrets: false\n```\n\n---\n\n### Root `.gitignore`\n\nGoCloud generates a root `.gitignore` when `enable_gitignore: true` (default). It uses the same generated-file header and overwrite prompts as `providers.tf`. Set `false` if you manage `.gitignore` yourself—the CLI will not create or update it. **Override levels:** infrastructure only.\n\n**Example** (opt out):\n\n```yaml\ninfrastructure:\n  enable_gitignore: false\n```\n\n### Terragrunt control\n\nGoCloud generates `terragrunt.hcl` per layer when `enable_terragrunt: true` (default). If you set `false`, existing `terragrunt.hcl` in that scope is removed. **Override levels:** see table above.\n\n**Example** (global + overrides at env, project, workload):\n\n```yaml\ninfrastructure:\n  enable_terragrunt: true\n\n  environments:\n    staging:\n      enable_terragrunt: false\n    production:\n      projects:\n        - legacy-system:\n            enable_terragrunt: false\n      workloads:\n        - legacy-app:\n            enable_terragrunt: false\n```\n\n---\n\n### SSO control\n\nGoCloud generates `.aws/config` with one profile per environment (see **gocloud sso setup** in Commands). Default: `enable_sso: true`; each env gets a profile from global `aws_sso`. Set `enable_sso: false` per env to skip; set `aws_sso` per env to override `start_url` or `role_name`. **Override levels:** see table above (Infrastructure + Environment only).\n\n**Example** (global + overrides per env):\n\n```yaml\ninfrastructure:\n  aws_sso:\n    start_url: \"https://my-client.awsapps.com/start#/\"\n    role_name: \"Admin\"\n\n  environments:\n    dev:\n      aws_account: \"111111111111\"\n    stg:\n      aws_account: \"222222222222\"\n      enable_sso: false\n    prd:\n      aws_account: \"222222222222\"\n      aws_sso:\n        role_name: \"ProductionAdmin\"\n```\n\n---\n\n### Regions per environment\n\nAWS region used in `metadata.tf` and provider configs. Default: all environments use `infrastructure.region`. Set `region` per environment to override. **Override levels:** see table above (Infrastructure + Environment only).\n\n**Example** (global + override per env):\n\n```yaml\ninfrastructure:\n  region: \"us-east-1\"\n  environments:\n    dev:\n      aws_account: \"111111111111\"\n    production:\n      aws_account: \"222222222222\"\n      region: \"eu-west-1\"\n```\n\n---\n\n### Versions per environment\n\nModule version written in generated `main.tf` (e.g. `version = \"0.17.0\"`). Default: all environments use `infrastructure.version`. Set `version` per environment to override; only affected `main.tf` files are updated. **Override levels:** see table above (Infrastructure + Environment only).\n\n**Example** (global + overrides per env):\n\n```yaml\ninfrastructure:\n  version: \"0.17.0\"\n  environments:\n    sha:\n      version: \"latest\"\n    prd:\n      version: \"v2.14.0\"\n```\n\n---\n\n### Custom source (Git)\n\nBy default, `main.tf` uses the Terraform registry with `version`. Set `source` (repo URL) and `source_ref` (branch, tag, or commit) to use a Git repo instead; GoCloud then generates `source = \"git@...//path?ref=...\"` and omits `version`. **Override levels:** see table above (Infrastructure + Environment only).\n\n**Example** (global + overrides per env):\n\n```yaml\ninfrastructure:\n  version: \"0.17.0\"\n  environments:\n    dev:\n      source: \"git@github.com:org/terraform-module.git\"\n      source_ref: \"feature/new-feature\"\n    prd:\n      source: \"git@github.com:org/terraform-module.git\"\n      source_ref: \"v1.0.0\"\n```\n\n---\n\n### Custom metadata\n\nOptional key-value pairs (e.g. domain names, team) injected into every `metadata.tf`.\n\nPriority (more specific wins):\n- `infrastructure.organization.metadata` for the `organization` layer\n- `infrastructure.security.metadata` for the `security` layer\n- `infrastructure.environments.\u003cenv\u003e.metadata` for env-based layers (`base`, `foundation`, `project`, `workload`)\n- `infrastructure.metadata` as global fallback\n\n**Example:**\n\n```yaml\ninfrastructure:\n  metadata:\n    public_domain: \"gocloud.la\"\n    private_domain: \"gocloud.private\"\n    internal_domain: \"gocloud.internal\"\n    company_email: \"devops@gocloud.la\"\n    support_team: \"platform\"\n    # any_other_key: \"value\"   # add any key-value pairs you need\n\n  organization:\n    aws_account: \"123456789012\"\n    metadata:\n      support_team: \"platform-org\" # overrides global for organization layer only\n\n  security:\n    aws_account: \"123456789013\"\n    metadata:\n      support_team: \"platform-sec\" # overrides global for security layer only\n\n  environments:\n    dev:\n      aws_account: \"111111111111\"\n      metadata:\n        support_team: \"platform-dev\" # overrides global for dev env layers\n```\n\n---\n\n### Backend\n\nGoCloud generates `backend.tf` (Terraform state: S3 + DynamoDB). If you omit `backend:`, defaults are used: `pattern: \"s3-backend\"`, `region` from infrastructure, `account: \"sha\"`, `encrypt: true`, `type: \"s3\"`, `use_profile: true`. Bucket and table names default to `{company}-{account}-{pattern}`. **Override levels:** see table above.\n\n#### Template variables\n\n\n**Variables available in `key_template`** (state file path):\n- `{{.AccountID}}` — AWS account ID (e.g. `\"123456789012\"`)\n- `{{.Layer}}` — Layer type (e.g. `\"base\"`, `\"foundation\"`, `\"project\"`, `\"workload\"`)\n- `{{.Project}}` — Project key (only for project/workload layers; e.g. `\"core\"`, `\"dept\"`)\n- `{{.Environment}}` — Environment key (e.g. `\"prd\"`, `\"dev\"`, `\"stg\"`)\n- `{{.EnvironmentName}}` — From environment `name`: lowercased, spaces → underscores.\n- `{{.Company}}` — Company prefix (e.g. `\"gcl\"`)\n- `{{.Region}}` — AWS region (e.g. `\"us-east-1\"`)\n- `{{.Client}}` — Client name (e.g. `\"test-client\"`)\n\n**Variables available in `role_template`** (assume_role role name):\n- `{{.AccountID}}` — AWS account ID of the current environment (e.g. `\"123456789012\"`)\n- `{{.BackendAccountID}}` — AWS account ID of the backend environment (e.g. `\"123456789013\"`)\n- `{{.Company}}` — Company prefix (e.g. `\"gcl\"`)\n- `{{.BackendAccount}}` — Environment key of the backend (e.g. `\"sha\"`)\n- `{{.Layer}}` — Layer type (e.g. `\"base\"`, `\"foundation\"`, `\"project\"`, `\"workload\"`)\n- `{{.Project}}` — Project key (only for project/workload layers)\n- `{{.Environment}}` — Environment key (e.g. `\"prd\"`, `\"dev\"`, `\"stg\"`)\n- `{{.EnvironmentName}}` — From environment `name`: lowercased, spaces → underscores (same normalization as display-name→folder for projects/workloads).\n- `{{.Region}}` — AWS region (e.g. `\"us-east-1\"`)\n- `{{.Client}}` — Client name (e.g. `\"test-client\"`)\n\nDefault `role_template` if not set: `{{.Company}}-{{.BackendAccount}}-{{.BackendPattern}}-{{.AccountID}}`.\n\n**Example** (global + overrides at env, project, workload):\n\n```yaml\ninfrastructure:\n  backend:\n    pattern: \"s3-backend\"\n    region: \"us-east-1\"\n    account: \"sha\"\n    key_template: \"{{.AccountID}}/{{.Layer}}/terraform.tfstate\"\n    role_template: \"{{.Company}}-{{.BackendAccount}}-{{.AccountID}}\"\n\n  environments:\n    prd:\n      backend:\n        key_template: \"{{.Company}}/{{.Environment}}/{{.Layer}}/terraform.tfstate\"\n      projects:\n        - core:\n            backend:\n              key_template: \"{{.Company}}/core/{{.Environment}}/terraform.tfstate\"\n              role_template: \"project-{{.BackendAccount}}-{{.AccountID}}\"\n      workloads:\n        - api:\n            backend:\n              role_template: \"workload-{{.BackendAccount}}-{{.AccountID}}\"\n```\n\n---\n\n### Providers\n\nGoCloud generates `providers.tf` (AWS providers). If you omit `providers:`, defaults are used: `use_profiles: true` and one AWS provider with `region = local.metadata.aws_region` (reference to `locals` in `metadata.tf`) plus an optional second with `region = \"us-east-1\"`, `alias: \"use1\"`. For `default_providers[].region`, values that match the same built-in AWS region list used for `metadata.key.region` short codes are written quoted in HCL; anything else is copied unchanged (`local.*`, `var.*`, `${...}`, etc.). With `use_profiles: true`, the CLI sets `profile` on each `aws` entry to the SSO profile for that layer (`{client}-{environment}`, `{client}-org`, `{client}-sec`) **only when that entry has no `profile` in YAML**; if you set `profile` on a `default_providers` line, that value is left unchanged. **Override levels:** see table above.\n\n**Example** (global + overrides at env, project, workload):\n\n```yaml\ninfrastructure:\n  providers:\n    use_profiles: true\n    default_providers:\n      - name: \"aws\"\n        region: \"local.metadata.aws_region\"\n      - name: \"aws\"\n        region: \"us-east-1\"\n        alias: \"use1\"\n\n  environments:\n    prd:\n      providers:\n        use_profiles: false\n        default_providers:\n          - name: \"aws\"\n            region: \"us-west-2\"\n      projects:\n        - core:\n            providers:\n              default_providers:\n                - name: \"aws\"\n                  region: \"us-east-1\"\n                  alias: \"primary\"\n      workloads:\n        - api:\n            providers:\n              default_providers:\n                - name: \"aws\"\n                  region: \"eu-west-1\"\n                  alias: \"europe\"\n```\n\n---\n\n### Workload dependencies\n\n**What it is:** Terragrunt (and the generated structure) needs to know which layers a workload depends on. **By default, dependencies are assigned automatically.**\n\n**Default dependencies:**\n- `base`: depends on nothing\n- `foundation`: depends on `base/{env}`\n- `project/{name}`: depends on `foundation/{env}`\n- `workload/{name}`: depends on `project/{name}/{env}` if that project exists for the environment, otherwise `project/common/{env}` (fallback)\n\nUse `depends_on` on a **project** (e.g. `[\"foundation\"]`, `[\"base\", \"foundation\"]`, or `[]` for none) or on a **workload** (e.g. `[\"project/common\", \"project/core\"]`, or `[]` for no dependencies).\n\n**Behavior:**\n- **Default**: Automatic dependencies based on layer hierarchy\n- **Custom**: You can specify relative paths in `depends_on` (project: `foundation` / `base`; workload: `project/\u003ckey\u003e`, `foundation`, `base`)\n- **No dependencies**: Use `depends_on: []` to disable\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eSample configuration block\u003c/strong\u003e\u003c/summary\u003e\n\n```yaml\ninfrastructure:\n  environments:\n    production:\n      workloads:\n        - blockchain-service:\n            depends_on: [\"project/common\", \"project/core\"]   # (optional) custom deps\n        - standalone-app:\n            depends_on: []                                   # (optional) no dependencies\n        # - webapp:          # (default) auto: project/common or project/\u003cname\u003e; omit depends_on\n        #   depends_on: []\n```\n\n\u003c/details\u003e\n\n---\n\n### Directory names\n\n**What it is:** The folder name for a project or workload (e.g. `project/core/production` vs `project/deposits/production`). **By default, the directory name is the key** you use in YAML.\n\n**Priority** (highest to lowest):\n1. **`dir_name`** — Exact directory name you specify\n2. **`name`** — Display name converted to lowercase for the directory\n3. **`key`** — The project/workload key (fallback)\n\n**Behavior:**\n- **Default**: The key is used as the directory name (e.g. `core` → `core/`)\n- **With `name`**: Name is lowercased for the directory (e.g. `\"Deposits\"` → `deposits/`)\n- **With `dir_name`**: The exact value is used (e.g. `\"withdrawals\"` → `withdrawals/`)\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eSample configuration block\u003c/strong\u003e\u003c/summary\u003e\n\n```yaml\n# Default (key as directory)\nprojects:\n  - core        # Directory: \"core\"\n  - common      # Directory: \"common\"\n\n# Project with custom name → directory from name lowercased\n- dept:         # Key: \"dept\"\n    name: \"Deposits\"   # Directory: \"deposits\"\n\n# Project with custom directory name\n- wdwl:         # Key: \"wdwl\"\n    name: \"Withdrawals\"\n    dir_name: \"withdrawals\"   # Directory: \"withdrawals\"\n\nworkloads:\n  - webapp\n  - api\n```\n\n\u003c/details\u003e\n\n## Shell completion\n\n### macOS (Zsh — recommended)\n\n```bash\n# Add completion to ~/.zshrc\necho 'source \u003c(gocloud completion zsh)' \u003e\u003e ~/.zshrc\n\n# Reload config\nsource ~/.zshrc\n\n# Test completion\ngocloud \u003cTAB\u003e\u003cTAB\u003e\n```\n\n### macOS (Bash)\n\n```bash\n# Install bash-completion\nbrew install bash-completion@2\n\n# Add to ~/.bash_profile\necho '[[ -r \"$(brew --prefix)/etc/profile.d/bash_completion.sh\" ]] \u0026\u0026 . \"$(brew --prefix)/etc/profile.d/bash_completion.sh\"' \u003e\u003e ~/.bash_profile\necho 'source \u003c(gocloud completion bash)' \u003e\u003e ~/.bash_profile\nsource ~/.bash_profile\n```\n\n### Linux\n\n```bash\n# Ubuntu/Debian\nsudo apt install bash-completion\n\n# CentOS/RHEL/Fedora\nsudo yum install bash-completion\n# or\nsudo dnf install bash-completion\n\n# Configure completion\necho 'source \u003c(gocloud completion bash)' \u003e\u003e ~/.bashrc\nsource ~/.bashrc\n```\n\n## Troubleshooting\n\n### Error: \"failed to get shared config profile, default\"\n\n```bash\n# The issue is that .aws/config does not exist\n# Fix: Configure AWS SSO first\n\ngocloud sso setup\ngocloud sso login --all\n```\n\n### Completion not working on macOS\n\n```bash\n# If you get \"command not found: compdef\"\n# Add at the TOP of ~/.zshrc:\n\necho 'autoload -Uz compinit' | cat - ~/.zshrc \u003e ~/.zshrc.tmp \u0026\u0026 mv ~/.zshrc.tmp ~/.zshrc\necho 'compinit' | cat - ~/.zshrc \u003e ~/.zshrc.tmp \u0026\u0026 mv ~/.zshrc.tmp ~/.zshrc\n\n# Reload\nsource ~/.zshrc\n```\n\n### AWS CLI not found\n\n```bash\n# macOS\nbrew install awscli\n\n# Linux\ncurl \"https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip\" -o \"awscliv2.zip\"\nunzip awscliv2.zip\nsudo ./aws/install\n```\n\n### main.tf files not updating\n\n`main.tf` files are protected from overwriting to preserve your custom logic. They are only updated automatically when the module version changes.\n\n## Related\n\n- **[Standard Platform](https://github.com/gocloudLa/terraform-aws-standard-platform)** — Terraform modules and layer documentation\n- **[Terraform Registry](https://registry.terraform.io/namespaces/gocloudLa)** — `gocloudLa/standard-platform/aws` modules\n- **[GoCloud](https://github.com/gocloudLa)** — Organization · [gocloud.la](https://gocloud.la)\n\n## Development\n\n**Prerequisites:** Go 1.25.1, golangci-lint (for linting).\n\n```bash\ngo install github.com/golangci/golangci-lint/cmd/golangci-lint@latest   # Install linter\nmake build      # Build binary\nmake test       # Run tests\nmake lint       # Run linter\nmake fmt        # Format code\nmake pre-commit # fmt + lint + test\n```\n\nSee `make help` for all targets (e.g. `make quality`, `make deps-check`, `make test-coverage`).\n\n## License\n\nThis project is under the MIT License. See the `LICENSE` file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgocloudla%2Fgocloud-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgocloudla%2Fgocloud-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgocloudla%2Fgocloud-cli/lists"}