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 → Base → Foundation → Project → Workload) and 50+ pre-configured AWS services.

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

What it does

Generate directory structure for Terraform/Terragrunt projects
Create config files (main.tf, metadata.tf, terragrunt.hcl, etc.)
Manage secrets in AWS SSM Parameter Store or SOPS
Configure AWS SSO and generate .aws/config
Validate YAML configuration before generating

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

Standard Platform & 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 repo: layers (organization, security, base, foundation, project, workload), usage examples, and module documentation
Terraform Registry: gocloudLa/standard-platform/aws — Published modules (e.g. gocloudLa/standard-platform/aws//modules/base)
GoCloud (gocloudLa) — Organization and other tools; gocloud.la for more info

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: gocloud version check. Update on macOS/Linux: gocloud version update.

Quick start

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

Commands

Version and update

`gocloud version [check|update]`

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

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.

gocloud config init my-project                     # Simple usage
gocloud config init my-project -o custom.yaml      # Custom output path
gocloud config init my-project --skip-environments # Skip environment prompts
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).

gocloud config validate                      # Simple usage
gocloud config validate --config custom.yaml # Validate specific file
gocloud config validate --strict             # Extra validation rules

Generate

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

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

gocloud generate                          # Simple usage
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 ({client}-{environment}).

gocloud sso setup

`gocloud sso list`

Lists configured AWS SSO profiles (numbered for selection).

gocloud sso list

`gocloud sso login`

Login to AWS SSO profiles.

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

`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) that Terraform reads in each layer. Available providers:

SSM (default): Stored in AWS. No extra tools; use your SSO profiles.
SOPS: Stored in encrypted files; requires the sops binary and KMS (details in Secrets control below).

`gocloud secrets check [layer-path]`

Checks if the secrets store exists for that 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: creates or ensures _secrets.yaml and KMS key).

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 that 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 for that layer.

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 from that layer.

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 as JSON (validated 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 controls:

gocloud health check --all --managed-days 180
gocloud health check --all --include-ended   # include events whose end time is already past

Output format:

gocloud health check --all --output list   # default
gocloud health check --all --output table

Modules

Generate READMEs for Terraform modules from a YAML config and optional template.

gocloud module readme generate         # From README.yml (default), output README.md
gocloud module readme generate-example # Same for example-style READMEs

Shell completion

Prints a script to source so that Tab completes commands, layer paths, and secret keys. Add to your shell profile (~/.zshrc, ~/.bashrc, etc.).

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

Override levels (where each option can be set):

Config	Infrastructure	Environment	Project	Workload
Backend	✓	✓	✓	✓
Providers	✓	✓	✓	✓
Secrets	✓	✓	✓	✓
Terragrunt	✓	✓	✓	✓
SSO	✓	✓	—	—
Region	✓	✓	—	—
Version	✓	✓	—	—
Source	✓	✓	—	—
Layers	✓	✓ (base, foundation only)	—	—
Metadata	✓	✓	—	—

General structure

Below, each key is explained in comments. For backend and providers, see Backend and Providers.

# CLI behaviour (all optional; uncomment to override)
cli:
  # working_dir: "."     # (default) project root
  # auto_backup: true    # (default) backup config before overwriting
  # backup_dir: ".bkp"   # (default)
  # verbose: false       # (default)
  # debug: false         # (default)

infrastructure:
  client: "my-client"     # Required. Client/project name (e.g. SSO profile names)
  company: "gcl"          # Required. Short prefix, 2–10 chars (bucket names, SSM paths)
  region: "us-east-1"     # Required. Default AWS region
  # version: "0.17.0"       # (default) module version in main.tf
  # enable_secrets: true    # (default: true) generate _secrets.tf and gocloud secrets commands
  # enable_sso: true        # (default: true) generate SSO profile
  # enable_terragrunt: true # (default: true) generate terragrunt.hcl files
  # enable_gitignore: true  # (default: true) generate root .gitignore

  # # Optional: use Git repo instead of Terraform registry for modules
  # source: "git@github.com:org/repo.git"
  # source_ref: "main"            # branch, tag, or commit

  # Backend: Terraform state (S3 + DynamoDB).
  backend:
    # pattern: "s3-backend"      # (default)
    # region: "us-east-1"        # (default: uses infrastructure.region)
    # account: "sha"             # (default) environment key where state bucket lives
    # encrypt: true              # (default)
    # type: "s3"                 # (default)
    # use_profile: true          # (default)
    # key_template: "..."        # (optional) Custom state path
    # role_template: "..."       # (optional) Custom assume_role name
    # bucket_name: "custom-bucket"        # Custom bucket (optional; default: {company}-{account}-{pattern})
    # dynamodb_table_name: "custom-table" # Custom lock table (optional; default: {company}-{account}-{pattern})

  # AWS SSO: required for gocloud sso setup. Generates .aws/config with profiles {client}-{environment}.
  aws_sso:
    # region: "us-east-1"         # (default: uses infrastructure.region)
    start_url: "https://my-client.awsapps.com/start#/"  # Required. IAM Identity Center URL
    role_name: "Admin"           # Required. Role name after SSO login

  # Layers (default: all true). organization/security only if respective aws_account set; see Layer control.
  layers:
  #   base: true                   # (default)
  #   foundation: true             # (default)
  #   organization: true           # (default)
  #   security: true               # (default)

  # Custom metadata (optional): injected into every metadata.tf.
  # Default/fallback for all layers unless a more specific metadata is set.
  # metadata:
  #   public_domain: "gocloud.la"
  #   private_domain: "gocloud.private"
  metadata:
    public_domain: "gocloud.la"  # (optional) add any key-value pairs
    private_domain: "gocloud.private"
    internal_domain: "gocloud.internal"

  # Secrets backend (optional, default: "ssm")
  # secrets:
  #   type: "ssm"                 # or "sops"

  # Providers: AWS providers in providers.tf. Uncomment to customize.
  # providers:
  #   use_profiles: true          # (default: true)
  #   default_providers:
  #     - name: "aws"
  #       region: "local.metadata.aws_region"
  #     - name: "aws"
  #       region: "us-east-1"
  #       alias: "use1"
  #     # (optional) assume_role for cross-account
  #     #   - name: "aws"
  #     #     assume_role:
  #     #       role_arn: "arn:aws:iam::123456789012:role/RoleName"
  #     #       session_name: "TerraformSession"

  # Optional: organization layer + SSO profile {client}-org (uncomment to enable)
  organization:
    aws_account: "123456789012"   # Required for SSO: creates profile {client}-org
  #   metadata: {}                # (optional) metadata override for organization layer
  #   enable_secrets: true        # (optional) secrets only for organization (overrides global enable_secrets)
  #   aws_sso:                    # (optional) override SSO for org profile
  #     start_url: "https://..."
  #     role_name: "Admin"
  #   backend: {}                 # (optional) override backend for organization layer
  #   providers: {}               # (optional) override providers for organization layer
  #  secrets:                     # (optional) override secrets type organization layer
  #    type: "sops"

  # 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)
  # security:
  #   aws_account: "123456789013"
  #   metadata: {}                # (optional) metadata override for security layer

  # Environments: each key is an environment (shared, dev, production, etc.). Required: aws_account per env.
  environments:
    shared:
      name: "Shared"              # (optional; default: key) display name
      # dir_name: "shared"        # (optional; default: key) directory name in generated tree
      aws_account: "123456789013" # Required. 12-digit AWS account ID
      # region: "us-east-1"       # (default: infrastructure.region)
      # version: "0.17.0"         # (default: infrastructure.version)
      # enable_secrets: true      # (default: inherit from global)
      # enable_sso: true          # (default: inherit from global)
      # enable_terragrunt: true   # (default: true)
      # layers:                   # (optional) disable layer for this environment
      #   base: true
      #   foundation: true
      # aws_sso:                  # (optional) override start_url / role_name for this env
      #   start_url: "https://..."
      #   role_name: "Admin"
      # metadata: {}              # (optional) metadata override for this environment
      # secrets: { type: "ssm" }  # (optional) backend for this env
      projects: ["core", "common"]   # Project subdirs (e.g. project/core/shared)
      workloads: ["webapp", "api"]   # Workload subdirs (e.g. workload/webapp/shared)

Environments

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/<env>, foundation/<env>, project/<name>/<env>, workload/<name>/<env>. Environments inherit global config; you can override per environment.

infrastructure:
  environments:
    dev:
      name: "Development"         # (optional; default: key) display name
      aws_account: "111111111111" # Required
      # dir_name: "dev"           # (default: key)
      # region: "us-east-1"       # (default: infrastructure.region)
      # version: "0.17.0"         # (default: infrastructure.version)
      # enable_secrets: true      # (default: inherit)
      # enable_sso: true          # (default)
      # enable_terragrunt: true   # (default)
      # layers: { base: true, foundation: true }  # (optional)
      # aws_sso: { start_url: "...", role_name: "..." }  # (optional) override for this env
      # secrets: { type: "ssm" } # (optional)
      projects: ["core", "common"]
      workloads: ["webapp", "api"]
    shared:
      name: "Shared"
      aws_account: "111111111111"
      # dir_name: "shared"       # (default: key)
      layers:                    # (optional) disable base only in this env
        base: true
        foundation: false
      projects: ["core", "common"]
      workloads: ["webapp", "api"]
    production:
      name: "Production"
      dir_name: "production"     # (optional) custom dir name
      aws_account: "222222222222"
      region: "eu-west-1"        # (optional) override region
      version: "0.14.0"          # (optional) override module version
      enable_secrets: false      # (optional) disable secrets for this env
      enable_sso: false          # (optional) no SSO profile for this env
      aws_sso:                   # (optional) different SSO for this env
        start_url: "https://prod.awsapps.com/start#/"
        role_name: "ProductionAdmin"
      projects: ["core", "common"]
      workloads: ["webapp", "api"]

Projects and workloads

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.

infrastructure:
  environments:
    production:
      projects:
        - core                                # (default) dir = key
        - common
        - dept:                               # key: dept
            name: "Deposits"                  # (optional) dir from name lowercased
        - wdwl:
            name: "Withdrawals"
            dir_name: "withdrawals"           # (optional) exact dir name
            # enable_terragrunt: true         # (default: true)
      workloads:
        - webapp
        - api
        - blockchain-service:
            depends_on: ["project/common", "project/core"]  # (optional) custom deps
        - legacy-app:
            enable_secrets: false             # (optional) disable secrets for this workload
        - dept:
            name: "Deposits"
            dir_name: "deposits"
            enable_secrets: false
            # depends_on: ["project/core"]    # (default: auto)

Layer control

GoCloud 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).

Example (global + override per env):

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

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

Secrets control

Secrets (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.

Example (global + overrides at env, project, workload):

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`

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

Example (opt out):

infrastructure:
  enable_gitignore: false

Terragrunt control

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

Example (global + overrides at env, project, workload):

infrastructure:
  enable_terragrunt: true

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

SSO control

GoCloud 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).

Example (global + overrides per env):

infrastructure:
  aws_sso:
    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: "222222222222"
      aws_sso:
        role_name: "ProductionAdmin"

Regions per environment

AWS 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).

Example (global + override per env):

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

Versions per environment

Module 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).

Example (global + overrides per env):

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

Custom source (Git)

By 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).

Example (global + overrides per env):

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

Optional key-value pairs (e.g. domain names, team) injected into every metadata.tf.

Priority (more specific wins):

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

Example:

infrastructure:
  metadata:
    public_domain: "gocloud.la"
    private_domain: "gocloud.private"
    internal_domain: "gocloud.internal"
    company_email: "devops@gocloud.la"
    support_team: "platform"
    # any_other_key: "value"   # add any key-value pairs you need

  organization:
    aws_account: "123456789012"
    metadata:
      support_team: "platform-org" # overrides global for organization layer only

  security:
    aws_account: "123456789013"
    metadata:
      support_team: "platform-sec" # overrides global for security layer only

  environments:
    dev:
      aws_account: "111111111111"
      metadata:
        support_team: "platform-dev" # overrides global for dev env layers

Backend

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

Template variables

Variables available in key_template (state file path):

{{.AccountID}} — AWS account ID (e.g. "123456789012")
{{.Layer}} — Layer type (e.g. "base", "foundation", "project", "workload")
{{.Project}} — Project key (only for project/workload layers; e.g. "core", "dept")
{{.Environment}} — Environment key (e.g. "prd", "dev", "stg")
{{.EnvironmentName}} — From environment name: lowercased, spaces → underscores.
{{.Company}} — Company prefix (e.g. "gcl")
{{.Region}} — AWS region (e.g. "us-east-1")
{{.Client}} — Client name (e.g. "test-client")

Variables available in role_template (assume_role role name):

{{.AccountID}} — AWS account ID of the current environment (e.g. "123456789012")
{{.BackendAccountID}} — AWS account ID of the backend environment (e.g. "123456789013")
{{.Company}} — Company prefix (e.g. "gcl")
{{.BackendAccount}} — Environment key of the backend (e.g. "sha")
{{.Layer}} — Layer type (e.g. "base", "foundation", "project", "workload")
{{.Project}} — Project key (only for project/workload layers)
{{.Environment}} — Environment key (e.g. "prd", "dev", "stg")
{{.EnvironmentName}} — From environment name: lowercased, spaces → underscores (same normalization as display-name→folder for projects/workloads).
{{.Region}} — AWS region (e.g. "us-east-1")
{{.Client}} — Client name (e.g. "test-client")

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

Example (global + overrides at env, project, workload):

infrastructure:
  backend:
    pattern: "s3-backend"
    region: "us-east-1"
    account: "sha"
    key_template: "{{.AccountID}}/{{.Layer}}/terraform.tfstate"
    role_template: "{{.Company}}-{{.BackendAccount}}-{{.AccountID}}"

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

Providers

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

Example (global + overrides at env, project, workload):

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"

Workload dependencies

What it is: Terragrunt (and the generated structure) needs to know which layers a workload depends on. By default, dependencies are assigned automatically.

Default dependencies:

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)

Use 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).

Behavior:

Default: Automatic dependencies based on layer hierarchy
Custom: You can specify relative paths in depends_on (project: foundation / base; workload: project/<key>, foundation, base)
No dependencies: Use depends_on: [] to disable

Sample configuration block

infrastructure:
  environments:
    production:
      workloads:
        - blockchain-service:
            depends_on: ["project/common", "project/core"]   # (optional) custom deps
        - standalone-app:
            depends_on: []                                   # (optional) no dependencies
        # - webapp:          # (default) auto: project/common or project/<name>; omit depends_on
        #   depends_on: []

Directory names

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.

Priority (highest to lowest):

dir_name — Exact directory name you specify
name — Display name converted to lowercase for the directory
key — The project/workload key (fallback)

Behavior:

Default: The key is used as the directory name (e.g. core → core/)
With name: Name is lowercased for the directory (e.g. "Deposits" → deposits/)
With dir_name: The exact value is used (e.g. "withdrawals" → withdrawals/)

Sample configuration block

# Default (key as directory)
projects:
  - core        # Directory: "core"
  - common      # Directory: "common"

# Project with custom name → directory from name lowercased
- dept:         # Key: "dept"
    name: "Deposits"   # Directory: "deposits"

# Project with custom directory name
- wdwl:         # Key: "wdwl"
    name: "Withdrawals"
    dir_name: "withdrawals"   # Directory: "withdrawals"

workloads:
  - webapp
  - api

Shell completion

macOS (Zsh — recommended)

# Add completion to ~/.zshrc
echo 'source <(gocloud completion zsh)' >> ~/.zshrc

# Reload config
source ~/.zshrc

# Test completion
gocloud <TAB><TAB>

macOS (Bash)

# Install bash-completion
brew install bash-completion@2

# Add to ~/.bash_profile
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

# Ubuntu/Debian
sudo apt install bash-completion

# CentOS/RHEL/Fedora
sudo yum install bash-completion
# or
sudo dnf install bash-completion

# Configure completion
echo 'source <(gocloud completion bash)' >> ~/.bashrc
source ~/.bashrc

Troubleshooting

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

# The issue is that .aws/config does not exist
# Fix: Configure AWS SSO first

gocloud sso setup
gocloud sso login --all

Completion not working on macOS

# If you get "command not found: compdef"
# Add 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

# Reload
source ~/.zshrc

AWS CLI not found

# macOS
brew install awscli

# 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 your custom logic. They are only updated automatically when the module 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 33 Commits
.github/workflows		.github/workflows
cmd		cmd
example		example
internal		internal
.cursorrules		.cursorrules
.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

What it does

Standard Platform & documentation

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

Shell completion

Configuration file (gocloud.yaml)

General structure

Environments

Projects and workloads

Layer control

Secrets control

Root .gitignore

Terragrunt control

SSO control

Regions per environment

Versions per environment

Custom source (Git)

Custom metadata

Backend

Template variables

Providers

Workload dependencies

Directory names

Shell completion

macOS (Zsh — recommended)

macOS (Bash)

Linux

Troubleshooting

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

Completion not working on macOS

AWS CLI not found

main.tf files not updating

Related

Development

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 14

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

`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`

Configuration file (`gocloud.yaml`)

Root `.gitignore`

Packages