GoCloud CLI

A 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 — an enterprise-ready AWS infrastructure platform with a layered architecture (Organization → Security → Base → Foundation → Project → Workload) and 50+ pre-configured AWS services.

Beta. This software is in beta. Use it at your own responsibility.

Standard Platform and documentation

The structure and main.tf files generated by GoCloud CLI are designed to use the Standard Platform Terraform modules.

terraform-aws-standard-platform — Platform GitHub repo: layers (organization, security, base, foundation, project, workload), usage examples, and module docs
Terraform Registry (gocloudLa) — Published modules (gocloudLa/standard-platform/aws, e.g. gocloudLa/standard-platform/aws//modules/base)
GoCloud (gocloudLa) — Organization and related tools; see gocloud.la for company and platform context

What it does

Generate directory structure for Terraform/Terragrunt projects (organization, security, base, foundation, project, workload).
Create config files (main.tf, metadata.tf, terragrunt.hcl, backend.tf, providers.tf, _secrets.tf).
Manage secrets in AWS SSM Parameter Store or SOPS (KMS-backed encrypted files).
Configure AWS SSO profiles in .aws/config (one per environment plus org/sec when enabled).
Validate YAML configuration before generating, reporting errors and unknown fields as warnings.
Inspect AWS managed health events per environment via AWS User Notifications.
Lay down airules bundles (.cursor, .kiro) for Cursor/Kiro when infrastructure.enable_airules is not false (default on).
Check Terraform Registry pins (gocloud module deps check): scans *.tf for public registry modules (and required_providers in plain text only), compares to registry.terraform.io (and optional GitHub compare metadata for bump plans).

Note: GoCloud CLI does not run Terraform or Terragrunt — it only generates files and structure.

Install

Option 1: Download binary (recommended)

Binaries are published on GitHub Releases. Asset names: gocloud-<version>-<os>-<arch> (e.g. gocloud-v1.2.3-darwin-arm64 for Apple Silicon).

# Replace VERSION with the desired release (e.g. v1.2.3)
curl -sL -o gocloud "https://github.com/gocloudLa/gocloud-cli/releases/download/VERSION/gocloud-VERSION-darwin-arm64"
chmod +x gocloud
sudo mv gocloud /usr/local/bin/

Option 2: Build from source

git clone https://github.com/gocloudLa/gocloud-cli.git
cd gocloud-cli
make build
sudo cp bin/gocloud /usr/local/bin/

Check for updates with gocloud version check. Update on macOS/Linux with gocloud version update.

Quick start

gocloud config init my-project    # Interactive config wizard
cd my-project
gocloud config validate           # Validate gocloud.yaml
gocloud generate                  # Generate directory tree and files
gocloud sso setup                 # Write .aws/config with SSO profiles
gocloud sso login --all           # Login to all SSO profiles
# gocloud secrets init --all      # Optional: create empty secrets stores for all layers

Commands

Global persistent flags available on every command: --config <file> (overrides default gocloud.yaml), -v/--verbose, -d/--debug.

Version and update

`gocloud version [check|update]`

Shows current CLI version. Subcommands compare with GitHub Releases or replace the binary in place (macOS/Linux only, when a matching release asset exists). Installation steps for all platforms are documented on GitHub Releases.

gocloud version        # Current version (build time, commit)
gocloud version check  # Check if you're on the latest release
gocloud version update # Download and replace this binary (macOS/Linux only)

Config

`gocloud config init [project-name]`

Creates a new gocloud.yaml via interactive prompts. Flag values seed the corresponding prompts.

gocloud config init my-project                              # Interactive defaults
gocloud config init my-project -o custom.yaml               # Custom output path
gocloud config init my-project --working-dir ./infra        # Seed cli.working_dir
gocloud config init my-project --region eu-west-1           # Seed infrastructure.region
gocloud config init my-project --company gcl                # Seed infrastructure.company (skips prompt)
gocloud config init my-project --skip-environments          # CLI-only config, no environments
gocloud config init my-project --skip-aws-sso               # Skip AWS SSO prompts

`gocloud config validate [--config file.yaml]`

Validates the config file (required fields, types, unknown keys; reports errors and warnings). See Configuration file (gocloud.yaml).

gocloud config validate                       # Defaults to ./gocloud.yaml
gocloud config validate --config custom.yaml  # Validate specific file
gocloud config validate --strict              # Treat warnings as errors

Generate

`gocloud generate [--config file.yaml]`

Reads gocloud.yaml and generates the directory tree (organization, security, base, foundation, project, workload), config files (main.tf, metadata.tf, terragrunt.hcl, backend.tf, providers.tf, _secrets.tf where enabled), then the root .gitignore and optional .cursor / .kiro airules bundles (each logs start/finish lines via INFO: like SSO and README), followed by AWS SSO setup, secrets scaffolding, and a project README.md. Validation runs first; errors abort generation, warnings are reported and ignored. New directories/files are created without prompting; existing main.tf files are never overwritten (only the module version line is updated when the configured version changes); other generated files prompt for overwrite unless --force is passed.

gocloud generate                          # Defaults to ./gocloud.yaml
gocloud generate --dry-run                # Preview without writing files
gocloud generate --force                  # Overwrite existing files (except main.tf)
gocloud generate --working-dir custom-dir # Output to custom directory
gocloud generate --config custom.yaml     # Use specific config file

AWS SSO

`gocloud sso setup`

Writes .aws/config with one profile per environment that has enable_sso (default true), plus {client}-org when infrastructure.organization.aws_account is set and {client}-sec when infrastructure.security.aws_account is set. Also writes .aws/.gitignore (*) so the generated config is not committed.

gocloud sso setup

`gocloud sso list`

Lists configured AWS SSO profiles from the generated .aws/config.

gocloud sso list

`gocloud sso login`

Login to AWS SSO profiles. Without flags it prompts interactively for a profile.

gocloud sso login                    # Interactive: choose profile
gocloud sso login --all              # Login to all profiles
gocloud sso login --profiles prd,sha # Comma-separated profile list

`gocloud sso verify`

Checks credential and account ID status (OK / Expired or Invalid / Account Mismatch).

gocloud sso verify

Secrets

Manage secrets (e.g. DB URLs, API keys) consumed by Terraform via _secrets.tf. Backend is selected per scope; see Secrets control in Configuration file (gocloud.yaml):

SSM (default): Stored in AWS Systems Manager Parameter Store. No extra tools required; uses your SSO profile.
SOPS: Stored in encrypted _secrets.yaml files; requires the sops binary and a KMS key (gocloud secrets init provisions the key on first run).

All secrets subcommands accept --config/-c <file> (defaults to gocloud.yaml).

`gocloud secrets check [layer-path]`

Checks if the secrets store exists for a layer (SSM: parameter; SOPS: _secrets.yaml).

gocloud secrets check base/production    # One layer
gocloud secrets check --environment dev  # All layers in an environment
gocloud secrets check --all              # All layers

`gocloud secrets init [layer-path]`

Creates empty secrets for the layer (SSM: new parameter with {}; SOPS: ensures _secrets.yaml and the KMS key exist).

gocloud secrets init foundation/dev      # One layer
gocloud secrets init --environment dev   # All layers in an environment
gocloud secrets init --all               # All layers

`gocloud secrets list <layer-path>`

Lists all secret keys for a layer.

gocloud secrets list base/production
gocloud secrets list project/core/production

`gocloud secrets get <layer-path> <key>`

Gets the value of one secret key.

gocloud secrets get base/production database_url
gocloud secrets get project/core/production api_key

`gocloud secrets set <layer-path> <key> <value>`

Sets the value of one secret.

gocloud secrets set base/production database_url "postgresql://..."
gocloud secrets set project/core/production api_key "secret-key"

`gocloud secrets delete <layer-path> <key>`

Removes one secret key.

gocloud secrets delete base/production database_url
gocloud secrets delete project/core/production api_key

`gocloud secrets edit <layer-path>`

Opens your $EDITOR to edit the layer's secrets (SSM: pretty JSON; SOPS: YAML). Changes are validated and re-encrypted on save.

gocloud secrets edit base/production
gocloud secrets edit project/core/production

Health

Check 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.

`gocloud health check`

Lists managed notification events for one environment or all.

gocloud health check --environment prd
gocloud health check --environment org  # organization account ({client}-org) when configured
gocloud health check --environment sec  # security account ({client}-sec) when configured
gocloud health check --all

Filter and output controls:

gocloud health check --all --managed-days 180   # Lookback window (default 90)
gocloud health check --all --include-ended      # Include events whose end time is past
gocloud health check --all --output list        # Default
gocloud health check --all --output table       # Aligned columns
gocloud health check --all --debug-json         # Print raw JSON from AWS Notifications API to stderr

Modules

`gocloud module readme generate`

Generates a module README.md from a YAML config and a Go template. By default uses the embedded GoCloud template.

gocloud module readme generate                                    # README.yml -> README.md (embedded template)
gocloud module readme generate -y custom.yml -o CUSTOM.md         # Custom YAML and output
gocloud module readme generate -t ./local-template.md.gotmpl      # Local template file (overrides --template-url)
gocloud module readme generate --template-url https://...gotmpl   # Remote template URL
gocloud module readme generate --terraform-dir examples/complete  # Module discovery directory (default: examples/complete)

`gocloud module readme generate-example`

Generates example-style module documentation from the same YAML source format.

gocloud module readme generate-example                                  # README.yml -> README.md (embedded example template)
gocloud module readme generate-example -y examples/complete/README.yml  # Custom YAML
gocloud module readme generate-example -o README-new.md                 # Custom output
gocloud module readme generate-example -t ./local-template.md.gotmpl    # Local template file
gocloud module readme generate-example --template-url https://...gotmpl # Remote template URL

`gocloud module deps`

Inspects Terraform dependency pins under a directory tree (default: current working directory; use --dir to point elsewhere). Contacts the public Terraform Registry (and the GitHub API when building bump metadata; use GITHUB_TOKEN or GH_TOKEN for higher rate limits). Plain output lists modules and required_providers; --json lists only modules, matching the first section of the plain report.

gocloud module deps check                           # Plain text + colored status; exit 1 if any registry module is outdated
gocloud module deps check --json                    # Same module rows as plain output (JSON); no providers section
gocloud module deps check --bump-plan               # Bump plan JSON: one item per outdated pin per file (`path`, branch, pr_title, pr_body, …)
gocloud module deps update SRC CUR NEW path/to/file.tf   # Rewrite one double-quoted pin (source then version on next lines)

Shell completion

`gocloud completion [bash|zsh|fish|powershell]`

Prints a script to source so that Tab completes commands, layer paths, and secret keys. See Shell completion for shell-specific install steps.

gocloud completion bash       # Bash
gocloud completion zsh        # Zsh (e.g. macOS default)
gocloud completion fish       # Fish
gocloud completion powershell # PowerShell

Configuration file (gocloud.yaml)

GoCloud uses a single YAML file (default ./gocloud.yaml) to define your project: client name, AWS accounts and regions, layers to generate, backend (Terraform state), AWS SSO (login), providers, and secrets (SSM or SOPS). Every subsection below defines its own override scope; defaults are set at Infrastructure (global) and overridden in order Environment → Project → Workload (more specific wins). Special layers (organization, security) are global and have their own override slot.

Per-section override scope tables list each parameter individually with Y/N per scope.

General structure

What it controls: Top-level shape of the YAML file. The file has two top-level sections: cli (CLI runtime defaults; see CLI behavior) and infrastructure (project model and generation behavior). infrastructure is required; cli is optional.

Default behavior:

cli defaults to working_dir: ".", auto_backup: true, backup_dir: ".gocloud-backups", verbose: false, debug: false.
infrastructure.client, infrastructure.company, and infrastructure.region are required.
All other infrastructure.* keys are optional and inherit hierarchically.

cli:
  working_dir: "."
  auto_backup: true
  backup_dir: ".gocloud-backups"
  verbose: false
  debug: false

infrastructure:
  client: "my-client"     # Required. Client/project name (used in SSO profile names)
  company: "gcl"          # Required. Short prefix, 2-10 lowercase letters
  region: "us-east-1"     # Required. Default AWS region
  version: "0.17.0"       # Module version written in main.tf
  environments: {}        # Required map (may be empty for CLI-only configs)
  # Optional override slots: backend, providers, aws_sso, metadata, secrets,
  # organization, security, layers, environment_order, enable_secrets,
  # enable_terragrunt, enable_gitignore, enable_airules, source, source_ref.

Environments

What it controls: Defines each environment (for example shared, dev, production), its AWS account, and per-environment overrides. GoCloud generates one directory tree per environment under base/<env>, foundation/<env>, project/<name>/<env>, and workload/<name>/<env>.

Default behavior:

name defaults to the environment key.
dir_name defaults to name lowercased, otherwise to the environment key.
region, version, feature toggles, and nested config inherit from global values unless overridden.
Iteration order for --all flows is the YAML insertion order (preserved automatically). Set infrastructure.environment_order to enforce a specific order regardless of YAML layout.

infrastructure:
  environment_order: ["sha", "dev", "stg", "prd"]   # Optional explicit order
  environments:
    sha:
      name: "Shared"
      aws_account: "111111111111"   # Required. 12-digit AWS account ID
      projects: ["core", "common"]
      workloads: ["webapp", "api"]
    dev:
      name: "Development"
      aws_account: "222222222222"
      # dir_name: "dev"            # (default: lowercased name, else key)
      # region: "us-east-1"        # (default: infrastructure.region)
      # version: "0.17.0"          # (default: infrastructure.version)
      projects: ["core", "common"]
      workloads: ["webapp", "api"]
    prd:
      name: "Production"
      dir_name: "production"        # Custom directory name
      aws_account: "333333333333"
      region: "eu-west-1"
      enable_secrets: false
      enable_sso: false
      aws_sso:
        start_url: "https://prod.awsapps.com/start#/"
        role_name: "ProductionAdmin"
      projects: ["core", "common"]
      workloads: ["webapp", "api"]

Projects and workloads

What it controls: Defines project and workload entries inside each environment. Entries become directories like project/core/production and workload/webapp/production, and support per-item options such as name, dir_name, depends_on, enable_secrets, enable_terragrunt, secrets, backend, and providers.

Default behavior:

A plain string item (e.g. core) uses that key as the directory name.
An object item under a single key uses that key as identity; name and dir_name resolve the directory (see Directory names).
enable_secrets and enable_terragrunt inherit from environment/global values.
Workload depends_on is auto-generated when omitted (see Workload dependencies).

infrastructure:
  environments:
    production:
      projects:
        - core                                # Plain item: dir = "core"
        - common
        - dept:                               # Key: dept
            name: "Deposits"                  # Directory: "deposits" (lowercased name)
        - wdwl:
            name: "Withdrawals"
            dir_name: "withdrawals"           # Explicit directory
            # enable_terragrunt: true         # (default: true)
      workloads:
        - webapp
        - api
        - blockchain-service:
            depends_on: ["project/common", "project/core"]
        - legacy-app:
            enable_secrets: false             # Disable secrets for this workload only
        - dept:
            name: "Deposits"
            dir_name: "deposits"
            enable_secrets: false
            # depends_on: ["project/core"]    # (default: auto-resolved)

Organization layer

What it controls: Activates a global organization/ layer for org-level resources (no per-environment subdirectory). Generation triggers when infrastructure.organization.aws_account is set (and layers.organization is not explicitly false). When activated, gocloud sso setup adds a {client}-org profile and gocloud generate writes organization/{main.tf,metadata.tf,backend.tf,providers.tf,_secrets.tf,terragrunt.hcl} using the module gocloudLa/standard-platform/aws//modules/organization.

Default behavior:

Inactive unless aws_account is set.
Inherits global backend, providers, aws_sso, metadata, and secrets. Each can be overridden inside infrastructure.organization.
enable_secrets for this layer inherits from the global infrastructure.enable_secrets.

infrastructure:
  organization:
    aws_account: "123456789012"             # Required to activate the layer (SSO profile {client}-org)
    metadata:
      support_team: "platform-org"          # Override metadata only for organization/metadata.tf
    enable_secrets: true                    # Enable secrets specifically for this layer
    aws_sso:
      start_url: "https://org.awsapps.com/start#/"
      role_name: "Admin"
    backend:
      pattern: "org-backend"
      use_assume_role: false                # Same-account backend access
      key_template: "{{.Company}}/org/{{.Layer}}/terraform.tfstate"
    providers:
      default_providers:
        - name: "aws"
          region: "local.metadata.aws_region"
        - name: "aws"
          alias: "sha"
          region: "local.metadata.aws_region"
          assume_role:
            role_arn: "arn:aws:iam::111111111111:role/OrganizationAccountAccessRole"
            session_name: "TerraformSession"
    secrets:
      type: "sops"                          # Use SOPS only for the organization layer

Security layer

What it controls: Activates a global security/ layer for security-account resources (no per-environment subdirectory). Generation triggers when infrastructure.security.aws_account is set (and layers.security is not explicitly false). When activated, gocloud sso setup adds a {client}-sec profile and gocloud generate writes security/{main.tf,metadata.tf,backend.tf,providers.tf,_secrets.tf,terragrunt.hcl} using the module gocloudLa/standard-platform/aws//modules/security. The generated security/main.tf declares the providers block aws.org, aws.sec, aws.log, aws.kms — supply matching aliases via infrastructure.security.providers or edit main.tf to wire your own aliases.

Default behavior:

Inactive unless aws_account is set.
Inherits global backend, providers, aws_sso, metadata, and secrets. Each can be overridden inside infrastructure.security.
enable_secrets for this layer inherits from the global infrastructure.enable_secrets.

infrastructure:
  security:
    aws_account: "123456789013"             # Required to activate the layer (SSO profile {client}-sec)
    metadata:
      support_team: "platform-sec"
    backend:
      use_lock_table: false
      role_template: "security-{{.BackendAccount}}-{{.AccountID}}"
    providers:
      default_providers:
        - name: "aws"
          alias: "org"
          region: "local.metadata.aws_region"
          assume_role:
            role_arn: "arn:aws:iam::111111111111:role/OrganizationAccountAccessRole"
        - name: "aws"
          alias: "sec"
          region: "local.metadata.aws_region"
        - name: "aws"
          alias: "log"
          region: "local.metadata.aws_region"
        - name: "aws"
          alias: "kms"
          region: "local.metadata.aws_region"

CLI behavior

What it controls: CLI runtime defaults stored in gocloud.yaml. These mirror the cli section produced by gocloud config init. Global persistent CLI flags (--config, -v/--verbose, -d/--debug) override the YAML values for the current invocation.

Default behavior:

working_dir: "."
auto_backup: true (saves a copy of the previous file before overwriting)
backup_dir: ".gocloud-backups"
verbose: false
debug: false

cli:
  working_dir: "."
  auto_backup: true
  backup_dir: ".gocloud-backups"
  verbose: false
  debug: false

Layer control

What it controls: Enables or disables generation of top-level layers. GoCloud generates organization (when infrastructure.organization.aws_account is set), security (when infrastructure.security.aws_account is set), base, foundation, plus project/workload from each environment.

Default behavior:

base, foundation, organization, and security are enabled by default.
organization and security are only generated when their aws_account is configured.
Per-environment layers may toggle base and foundation only; organization and security are global.

Override scope:

Parameter	Global	Environment	Project	Workload
`layers.base`	Y	Y	N	N
`layers.foundation`	Y	Y	N	N
`layers.organization`	Y	N	N	N
`layers.security`	Y	N	N	N

infrastructure:
  layers:
    base: true
    foundation: true
    organization: true
    security: true

  environments:
    staging:
      layers:
        base: false
        foundation: true

Region

What it controls: Selects the AWS region used in generated metadata.tf and resolved by local.metadata.aws_region in providers.

Default behavior:

Global infrastructure.region is used by all environments by default.
Environment region overrides only that environment.

Override scope:

Parameter	Global	Environment	Project	Workload
`region`	Y	Y	N	N

infrastructure:
  region: "us-east-1"
  environments:
    dev:
      aws_account: "111111111111"
    prd:
      aws_account: "222222222222"
      region: "eu-west-1"

Module version

What it controls: Selects the module version written in generated main.tf (for example version = "0.17.0").

Default behavior:

Global infrastructure.version applies to all generated layers.
Environment version overrides only that environment's main.tf.

Override scope:

Parameter	Global	Environment	Project	Workload
`version`	Y	Y	N	N

infrastructure:
  version: "0.17.0"
  environments:
    sha:
      version: "latest"
    prd:
      version: "v2.14.0"

Custom source (Git)

What it controls: Switches module source generation from the Terraform Registry (version) to a Git source (source + source_ref). When set, main.tf emits source = "<git>//modules/<layer>?ref=<ref>" and omits version.

Default behavior:

Without source, registry source + version is generated.
With source + source_ref, Git source is generated and version is omitted.

Override scope:

Parameter	Global	Environment	Project	Workload
`source`	Y	Y	N	N
`source_ref`	Y	Y	N	N

infrastructure:
  version: "0.17.0"
  environments:
    dev:
      source: "git@github.com:org/terraform-module.git"
      source_ref: "feature/new-feature"
    prd:
      source: "git@github.com:org/terraform-module.git"
      source_ref: "v1.0.0"

Custom metadata

What it controls: Defines custom key-value metadata (for example domains or team ownership) injected into generated metadata.tf under locals.metadata.

Default behavior:

infrastructure.metadata acts as fallback for all layers.
More specific metadata (organization, security, environment) overrides global keys per layer.

Priority (more specific wins, by layer):

infrastructure.organization.metadata for the organization layer
infrastructure.security.metadata for the security layer
infrastructure.environments.<env>.metadata for env-based layers (base, foundation, project, workload)
infrastructure.metadata as global fallback

Override scope:

Parameter	Global	Environment	Project	Workload
`metadata`	Y	Y	N	N

infrastructure:
  metadata:
    public_domain: "gocloud.la"
    private_domain: "gocloud.private"
    internal_domain: "gocloud.internal"
    company_email: "devops@gocloud.la"
    support_team: "platform"

  organization:
    aws_account: "123456789012"
    metadata:
      support_team: "platform-org"

  security:
    aws_account: "123456789013"
    metadata:
      support_team: "platform-sec"

  environments:
    dev:
      aws_account: "111111111111"
      metadata:
        support_team: "platform-dev"

Backend

What it controls: Configures generation of backend.tf (Terraform state in S3 and state locking in DynamoDB). Resolved hierarchically at every scope (Global → Environment → Project / Workload). For special layers, see Organization layer and Security layer.

Default behavior:

type: "s3" (use "disabled" to skip backend.tf generation at that scope)
pattern: "s3-backend"
region: inherits infrastructure.region
account: "sha"
encrypt: true
use_profile: true (writes profile = "...")
use_assume_role: true (writes assume_role = { ... })
use_lock_table: true (writes dynamodb_table = "...")
bucket_name: defaults to {company}-{account}-{pattern}
dynamodb_table_name: defaults to {company}-{account}-{pattern}

Override scope:

Parameter	Global	Environment	Project	Workload
`backend.type`	Y	Y	Y	Y
`backend.pattern`	Y	Y	Y	Y
`backend.region`	Y	Y	Y	Y
`backend.account`	Y	Y	Y	Y
`backend.encrypt`	Y	Y	Y	Y
`backend.use_profile`	Y	Y	Y	Y
`backend.use_assume_role`	Y	Y	Y	Y
`backend.use_lock_table`	Y	Y	Y	Y
`backend.key_template`	Y	Y	Y	Y
`backend.role_template`	Y	Y	Y	Y
`backend.bucket_name`	Y	Y	Y	Y
`backend.dynamodb_table_name`	Y	Y	Y	Y

infrastructure:
  backend:
    use_assume_role: true
    use_lock_table: true
    use_profile: true
    key_template: "{{.AccountID}}/{{.Layer}}/terraform.tfstate"
    role_template: "{{.Company}}-{{.BackendAccount}}-{{.AccountID}}"

  environments:
    dev:
      backend:
        use_assume_role: false
        key_template: "{{.Company}}/{{.Environment}}/{{.Layer}}/terraform.tfstate"
      projects:
        - core:
            backend:
              use_profile: false
              key_template: "{{.Company}}/core/{{.Environment}}/terraform.tfstate"
              role_template: "project-{{.BackendAccount}}-{{.AccountID}}"
      workloads:
        - api:
            backend:
              use_lock_table: false
              role_template: "workload-{{.BackendAccount}}-{{.AccountID}}"

Variables available in key_template (state file path):

{{.AccountID}} — AWS account ID of the current environment
{{.Layer}} — Layer type (base, foundation, project, workload)
{{.Project}} — Project key (project/workload layers only)
{{.Environment}} — Environment key (e.g. prd, dev, stg)
{{.EnvironmentName}} — From environment name: lowercased, spaces replaced with underscores
{{.Company}} — Company prefix
{{.Region}} — AWS region
{{.Client}} — Client name

Variables available in role_template (assume_role role name):

{{.AccountID}} — AWS account ID of the current environment
{{.BackendAccountID}} — AWS account ID of the backend environment
{{.Company}} — Company prefix
{{.BackendAccount}} — Environment key of the backend (e.g. sha)
{{.BackendPattern}} — backend.pattern value
{{.Layer}} — Layer type
{{.Project}} — Project key (project/workload layers only)
{{.Environment}} — Environment key
{{.EnvironmentName}} — Same normalization as key_template
{{.Region}} — AWS region
{{.Client}} — Client name

Default role_template if not set: {{.Company}}-{{.BackendAccount}}-{{.BackendPattern}}-{{.AccountID}}.

Providers

What it controls: Configures generation of providers.tf (provider blocks, regions, aliases, optional assume_role, and automatic profile injection). Resolved hierarchically at every scope (Global → Environment → Project / Workload). For special layers, see Organization layer and Security layer.

Default behavior:

If providers is omitted, use_profiles: true is used.
Default provider list includes an aws provider with region = local.metadata.aws_region.
For default_providers[].region, known AWS regions are rendered quoted in HCL; expressions like local.*, var.*, and ${...} are passed through unchanged.
With use_profiles: true, profile names are auto-set only when a provider entry does not already define profile.
Generated main.tf for foundation and workload layers wires providers = { aws.use1 = aws.use1 }; declare an aws provider with alias: "use1" if you want this wiring active. The security layer's main.tf wires aws.org, aws.sec, aws.log, aws.kms — declare those aliases or edit main.tf.

Override scope:

Parameter	Global	Environment	Project	Workload
`providers.use_profiles`	Y	Y	Y	Y
`providers.default_providers`	Y	Y	Y	Y

infrastructure:
  providers:
    use_profiles: true
    default_providers:
      - name: "aws"
        region: "local.metadata.aws_region"
      - name: "aws"
        region: "us-east-1"
        alias: "use1"

  environments:
    prd:
      providers:
        use_profiles: false
        default_providers:
          - name: "aws"
            region: "us-west-2"
      projects:
        - core:
            providers:
              default_providers:
                - name: "aws"
                  region: "us-east-1"
                  alias: "primary"
      workloads:
        - api:
            providers:
              default_providers:
                - name: "aws"
                  region: "eu-west-1"
                  alias: "europe"

Secrets control

What it controls: Configures whether secrets are generated/used per scope and which backend is used. Secrets are consumed by Terraform via _secrets.tf, using SSM (default) or SOPS (encrypted files; requires sops and KMS).

Default behavior:

enable_secrets defaults to true.
secrets.type defaults to ssm.
When disabled at a lower scope, that scope stops generating/using _secrets.tf.

Override scope:

Parameter	Global	Environment	Project	Workload
`enable_secrets`	Y	Y	Y	Y
`secrets.type`	Y	Y	Y	Y

infrastructure:
  enable_secrets: true
  secrets:
    type: "ssm"

  environments:
    production:
      secrets:
        type: "sops"
      projects:
        - example:
            secrets:
              type: "sops"
      workloads:
        - legacy-app:
            enable_secrets: false

Root `.gitignore`

What it controls: Generation of the root .gitignore file by gocloud generate.

Default behavior:

enable_gitignore defaults to true.
File creation/update follows standard generated-file overwrite prompts (or --force).

Override scope:

Parameter	Global	Environment	Project	Workload
`enable_gitignore`	Y	N	N	N

infrastructure:
  enable_gitignore: false

Airules (`.cursor` / `.kiro`)

What it controls: Generation of the .cursor and .kiro directories at the generation root (rules, skills, steering, MCP JSON) by gocloud generate, using the airules bundle shipped with the CLI.

Default behavior:

enable_airules defaults to true.
Directory and file creation/update follow standard generated-file overwrite prompts (or --force).
To change the bundle shipped with the CLI, edit FILES_IN ROOT in the GoCloud CLI repo and run make sync-airules, then rebuild.

Override scope:

Parameter	Global	Environment	Project	Workload
`enable_airules`	Y	N	N	N

infrastructure:
  enable_airules: false

Terragrunt control

What it controls: Generation of terragrunt.hcl files at each scope.

Default behavior:

enable_terragrunt defaults to true.
Disabling it at a given scope removes generated terragrunt.hcl for that scope.

Override scope:

Parameter	Global	Environment	Project	Workload
`enable_terragrunt`	Y	Y	Y	Y

infrastructure:
  enable_terragrunt: true

  environments:
    staging:
      enable_terragrunt: false
    production:
      projects:
        - legacy-system:
            enable_terragrunt: false
      workloads:
        - legacy-app:
            enable_terragrunt: false

SSO control

What it controls: Generation of AWS SSO profiles in .aws/config (used by gocloud sso setup). Toggling and global URL/role defaults are configured here; per-environment overrides may set enable_sso, start_url, role_name, and region.

Default behavior:

Per-environment SSO is on by default; disable with enable_sso: false on that environment.
Environments inherit aws_sso.start_url, aws_sso.role_name, and aws_sso.region from global config.
The organization and security layers, when activated, get their own profiles and may set aws_sso overrides inside infrastructure.organization / infrastructure.security.

Override scope:

Parameter	Global	Environment	Project	Workload
`enable_sso`	N	Y	N	N
`aws_sso.region`	Y	Y	N	N
`aws_sso.start_url`	Y	Y	N	N
`aws_sso.role_name`	Y	Y	N	N

infrastructure:
  aws_sso:
    region: "us-east-1"
    start_url: "https://my-client.awsapps.com/start#/"
    role_name: "Admin"

  environments:
    dev:
      aws_account: "111111111111"
    stg:
      aws_account: "222222222222"
      enable_sso: false
    prd:
      aws_account: "333333333333"
      aws_sso:
        role_name: "ProductionAdmin"

Workload dependencies

What it controls: Dependency wiring between layers (used mainly by Terragrunt). depends_on overrides defaults at the project or workload entry.

Default behavior:

base: depends on nothing
foundation: depends on base/{env}
project/{name}: depends on foundation/{env}
workload/{name}: depends on project/{name}/{env} if that project exists for the environment, otherwise project/common/{env} (fallback)

depends_on accepts a list of layer paths (e.g. ["foundation"], ["project/common", "project/core"], or [] to clear dependencies).

Override scope:

Parameter	Global	Environment	Project	Workload
`depends_on`	N	N	Y	Y

infrastructure:
  environments:
    production:
      workloads:
        - blockchain-service:
            depends_on: ["project/common", "project/core"]
        - standalone-app:
            depends_on: []

Directory names

What it controls: How project/workload directory names are resolved (for example project/core/production vs project/deposits/production).

Default behavior:

Directory name defaults to the item key.
If name is set and dir_name is omitted, the directory uses lowercased name.
If dir_name is set, that exact value is used.

Priority (highest to lowest):

dir_name — exact directory name
name — display name converted to lowercase
key — the project/workload key (fallback)

Override scope:

Parameter	Global	Environment	Project	Workload
`name`	N	N	Y	Y
`dir_name`	N	N	Y	Y

infrastructure:
  environments:
    production:
      projects:
        - core                              # Directory: "core"
        - dept:                             # Key: "dept"
            name: "Deposits"                # Directory: "deposits"
        - wdwl:                             # Key: "wdwl"
            name: "Withdrawals"
            dir_name: "withdrawals"         # Directory: "withdrawals"
      workloads:
        - webapp
        - api

Shell completion

macOS (Zsh — recommended)

echo 'source <(gocloud completion zsh)' >> ~/.zshrc
source ~/.zshrc
gocloud <TAB><TAB>

macOS (Bash)

brew install bash-completion@2
echo '[[ -r "$(brew --prefix)/etc/profile.d/bash_completion.sh" ]] && . "$(brew --prefix)/etc/profile.d/bash_completion.sh"' >> ~/.bash_profile
echo 'source <(gocloud completion bash)' >> ~/.bash_profile
source ~/.bash_profile

Linux (Bash)

sudo apt install bash-completion       # Ubuntu/Debian
# sudo yum install bash-completion     # CentOS/RHEL
# sudo dnf install bash-completion     # Fedora
echo 'source <(gocloud completion bash)' >> ~/.bashrc
source ~/.bashrc

Troubleshooting

Error: "failed to get shared config profile, default"

.aws/config does not exist. Configure AWS SSO first:

gocloud sso setup
gocloud sso login --all

Completion not working on macOS (`command not found: compdef`)

Zsh's completion system is not initialized. Add the loader at the top of ~/.zshrc:

echo 'autoload -Uz compinit' | cat - ~/.zshrc > ~/.zshrc.tmp && mv ~/.zshrc.tmp ~/.zshrc
echo 'compinit' | cat - ~/.zshrc > ~/.zshrc.tmp && mv ~/.zshrc.tmp ~/.zshrc
source ~/.zshrc

AWS CLI not found

gocloud sso login shells out to the AWS CLI. Install it:

brew install awscli                                                           # macOS
# Linux:
# curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
# unzip awscliv2.zip
# sudo ./aws/install

`main.tf` files not updating

main.tf files are protected from overwriting to preserve custom logic. Only the module version line is updated automatically when the configured version changes.

Development

Prerequisites: Go 1.25.1, golangci-lint (for linting).

go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest   # Install linter
make build      # Build binary
make test       # Run tests
make lint       # Run linter
make fmt        # Format code
make pre-commit # fmt + lint + test

See make help for all targets (e.g. make quality, make deps-check, make test-coverage).

License

This project is under the MIT License. See the LICENSE file for details.

Name		Name	Last commit message	Last commit date
Latest commit History 40 Commits
.cursor/rules		.cursor/rules
.github/workflows		.github/workflows
cmd		cmd
example		example
internal		internal
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
go.mod		go.mod
go.sum		go.sum
main.go		main.go

Folders and files

Latest commit

History

Repository files navigation

GoCloud CLI

Standard Platform and documentation

What it does

Install

Option 1: Download binary (recommended)

Option 2: Build from source

Quick start

Commands

Version and update

gocloud version [check|update]

Config

gocloud config init [project-name]

gocloud config validate [--config file.yaml]

Generate

gocloud generate [--config file.yaml]

AWS SSO

gocloud sso setup

gocloud sso list

gocloud sso login

gocloud sso verify

Secrets

gocloud secrets check [layer-path]

gocloud secrets init [layer-path]

gocloud secrets list <layer-path>

gocloud secrets get <layer-path> <key>

gocloud secrets set <layer-path> <key> <value>

gocloud secrets delete <layer-path> <key>

gocloud secrets edit <layer-path>

Health

gocloud health check

Modules

gocloud module readme generate

gocloud module readme generate-example

gocloud module deps

Shell completion

gocloud completion [bash|zsh|fish|powershell]

Configuration file (gocloud.yaml)

General structure

Environments

Projects and workloads

Organization layer

Security layer

CLI behavior

Layer control

Region

Module version

Custom source (Git)

Custom metadata

Backend

Providers

Secrets control

Root .gitignore

Airules (.cursor / .kiro)

Terragrunt control

SSO control

Workload dependencies

Directory names

Shell completion

macOS (Zsh — recommended)

macOS (Bash)

Linux (Bash)

Troubleshooting

Error: "failed to get shared config profile, default"

Completion not working on macOS (command not found: compdef)

AWS CLI not found

main.tf files not updating

Related

Development

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

`gocloud version [check|update]`

`gocloud config init [project-name]`

`gocloud config validate [--config file.yaml]`

`gocloud generate [--config file.yaml]`

`gocloud sso setup`

`gocloud sso list`

`gocloud sso login`

`gocloud sso verify`

`gocloud secrets check [layer-path]`

`gocloud secrets init [layer-path]`

`gocloud secrets list <layer-path>`

`gocloud secrets get <layer-path> <key>`

`gocloud secrets set <layer-path> <key> <value>`

`gocloud secrets delete <layer-path> <key>`

`gocloud secrets edit <layer-path>`

`gocloud health check`

`gocloud module readme generate`

`gocloud module readme generate-example`

`gocloud module deps`

`gocloud completion [bash|zsh|fish|powershell]`

Root `.gitignore`

Airules (`.cursor` / `.kiro`)

Completion not working on macOS (`command not found: compdef`)

`main.tf` files not updating

Packages