CLI Configuration#

Atlantis's CLI configuration lives in the cmd/ package. The primary entry point is cmd/server.go, which defines all flags, their defaults, help descriptions, and the full startup sequence for the atlantis server subcommand.

Typed Flag Maps#

All flags are declared as typed maps at package level 1:

Each entry carries a description, defaultValue, and optional hidden field 2. These maps are the single source of truth for what flags exist — adding a new flag requires adding a constant, a UserConfig field with a matching mapstructure tag, and an entry in one of the maps 3.

All flag names are declared as const strings in alphabetical order 4, making them safe to reference from both the CLI layer and the server initialization code.

Viper Integration and YAML Config#

ServerCmd.Init() configures Viper to accept environment variables prefixed with ATLANTIS_ and to translate hyphens to underscores 5. Every flag is bound to Viper with BindPFlag, so flags, env vars, and YAML config files are resolved in a unified priority order (cobra flag > env var > config file > default).

The --config flag points to a YAML file that is loaded during preRun 6. The YAML keys are the flag names (e.g., gh-token: abc123) because UserConfig fields carry matching mapstructure tags 7.

GitHub App Authentication Flags#

GitHub App auth uses a dedicated int64Flags sub-map. The two relevant flags are 8:

• --gh-app-id (GithubAppID int64) — activates GitHub App credentials when non-zero.
• --gh-app-installation-id (GithubAppInstallationID int64) — pins a specific installation; required when one App has multiple installations.

Alongside these, the string flags --gh-app-key / --gh-app-key-file supply the private key 9, and --gh-app-slug provides the URL-friendly App name 10.

Validation enforces mutual exclusivity: if --gh-app-id is set, exactly one of --gh-app-key or --gh-app-key-file must be provided — not both and not neither 11.

Help Generation#

cmd/help_fmt.go defines usageTmpl, a custom Cobra usage template that replaces the default flag listing. It:

1. Collects all non-hidden flag names from stringFlags, boolFlags, and intFlags, then sorts them alphabetically 12.
2. Formats each entry as --name=<value> (or --name for booleans) followed by the description wrapped at 80 characters 13.
3. Embeds the result in a Cobra-compatible template string 14.

Note: int64Flags (i.e., --gh-app-id, --gh-app-installation-id) are not included in the usageTmpl call 15. These flags are registered with Cobra and Viper normally but won't appear in the custom --help output — a known gap.

Validation Logic#

After Viper unmarshals flags into server.UserConfig, ServerCmd.run() calls validate() 16. Key checks include:

• Log level — must be one of debug, info, warn, error 17.
• TF distribution — must be terraform or opentofu 18.
• Checkout strategy — must be branch or merge 19.
• VCS credentials — at least one VCS provider must be fully configured (user+token or App ID+key); partial pairs are rejected 20.
• --repo-allowlist — required; cannot contain :// 21.
• SSL — --ssl-cert-file and --ssl-key-file must both be set or both unset 22.
• Redis cluster mode — --redis-cluster-addresses cannot be combined with --redis-host, --redis-port, or --redis-db 23.
• Token newline detection — warns if any token value contains a \n 24.

Security warnings are emitted separately via securityWarnings() when webhook secrets are absent 25.

Kubernetes Environment Sanitization#

Kubernetes injects service-discovery environment variables for co-located services. For example, an atlantis Service in the same namespace produces ATLANTIS_REDIS_PORT=tcp://10.x.x.x:6379, which Viper picks up as the redis-port flag and then fails to parse as an integer.

sanitizeKubernetesServiceLinks() addresses this by iterating intFlags and resetting any value whose string form starts with tcp:// or udp:// back to its declared default. It is called at the top of run(), before Viper.Unmarshal 26.

Startup Sequence#

ServerCmd.run() executes in this order 27:

1. sanitizeKubernetesServiceLinks() — fix K8s env collisions
2. Viper.Unmarshal(&userConfig) — populate UserConfig
3. setDefaults() — fill zero-valued fields with their defaults 28
4. validate() — enforce all constraints
5. setAtlantisURL(), setDataDir(), setMarkdownTemplateOverridesDir() — expand ~ and resolve relative paths
6. setVarFileAllowlist() — default to data-dir if unset
7. deprecationWarnings() / securityWarnings() / trimAtSymbolFromUsers() — housekeeping
8. ServerCreator.NewServer() → server.Start()

Key Files#