Skip to main content

Multi-Config Management: Switching Between Environments from CLI

Environment switching becomes dangerous long before it becomes complicated. The moment one engineer can point the CLI at staging while another is sure they are looking at production, the platform has a reliability problem. Keeptrusts gives you the basic pieces to keep that under control: explicit config files, profile-aware commands, clear configuration precedence, and gateway startup flags that make the selected runtime visible instead of implicit.

Use this page when​

  • You run separate development, staging, and production Keeptrusts environments.
  • You need operators to switch environments without editing files in place.
  • You want to keep environment choice explicit in scripts, CI jobs, and local shell workflows.

Primary audience​

  • Primary: Technical Engineers and platform operators
  • Secondary: Technical Leaders designing release and access boundaries

The problem​

Multi-environment governance looks simple until the first time a team deploys with the wrong inputs. The file path is correct, but the active profile points at the wrong API URL. The token is valid, but it belongs to the wrong environment. A local shell still has yesterday's KEEPTRUSTS_API_URL exported. A gateway starts successfully, but it is loading the wrong config file.

Those mistakes are common because configuration is rarely a single value. It is a combination of file contents, environment variables, command flags, and, in some workflows, stored CLI auth context. That makes implicit switching brittle.

The bigger risk is operational confidence. If an engineer cannot answer "which environment am I using right now?" from a single command, they are already one mistake away from a bad rollout.

The solution​

The Keeptrusts CLI helps when you treat environment choice as data instead of habit.

Three pieces matter most.

The first is explicit config inspection. kt config show --json tells you what the CLI actually resolved after flags, environment variables, config file values, and defaults were combined.

The second is explicit diagnostic validation. kt doctor supports --config and --profile, so you can confirm the selected environment is usable before you start a gateway or deploy a change.

The third is predictable runtime startup. kt gateway run accepts --policy-config, and managed mode accepts --profile, --config, and --gateway-id. That means environment selection can be declared in the command itself rather than hidden in shell history.

The underlying rule from the CLI docs is simple: configuration precedence is flags, then environment variables, then config file, then defaults. Once you work with that rule instead of fighting it, multi-environment workflows become much safer.

Implementation​

The most reliable pattern is to keep environment files separate and inspect them before use.

Start by checking the effective CLI state for the file you intend to use:

kt config show --json --file environments/staging/policy-config.yaml

Then validate that the same environment is actually healthy:

kt doctor \
  --config environments/staging/policy-config.yaml \
  --profile staging \
  --json

Those two commands do different jobs. kt config show tells you what resolved. kt doctor tells you whether the resolved state can work.

For local gateway startup, keep the selected file explicit:

kt gateway run \
  --listen 0.0.0.0:41002 \
  --policy-config environments/staging/policy-config.yaml

If you run managed mode, make the environment choice visible there too:

kt run \
  --gateway-id staging-gateway \
  --config environments/staging/policy-config.yaml \
  --profile staging

One strong shell pattern is to turn the environment choice into a single wrapper instead of expecting engineers to remember a long chain of exports.

case "$1" in
  dev)
    export KEEPTRUSTS_API_URL="https://api.keeptrusts.com"
    kt config show --json --file environments/dev/policy-config.yaml
    ;;
  staging)
    export KEEPTRUSTS_API_URL="https://api.keeptrusts.com"
    kt config show --json --file environments/staging/policy-config.yaml
    ;;
  prod)
    export KEEPTRUSTS_API_URL="https://api.keeptrusts.com"
    kt config show --json --file environments/prod/policy-config.yaml
    ;;
esac

The specific URL may stay the same in hosted deployments, but the profile, config file, and token scope still separate the environments operationally. What matters is that the operator can see the chosen environment before they take the next step.

A second practical pattern is to pair every environment switch with a diagnostic command. If a developer changes from staging to production, the workflow should be:

  1. inspect the resolved config;
  2. run kt doctor for that environment;
  3. only then run mutating or runtime commands.

That pattern prevents a common failure mode: assuming the switch happened because a shell variable changed, without verifying that the CLI now resolves the expected file, token presence, and profile.

When teams need even tighter discipline, they can keep environment-specific commands in scripts checked into the repo. That pushes environment choice out of memory and into versioned operational entry points, which is usually the right tradeoff for production workflows.

Results and impact​

When environment selection becomes explicit, rollout mistakes fall sharply. Engineers stop relying on shell state they cannot see, and support teams spend less time debugging self-inflicted misconfiguration.

It also improves confidence during incident work. If an operator can prove the active profile, config file, and gateway ID before touching anything, the team avoids a whole class of avoidable confusion.

The bigger gain is consistency. Development, staging, and production stop feeling like improvised variations of the same setup and start behaving like named, testable operating contexts.

Key takeaways​

  • Treat environment choice as an explicit CLI input, not an implicit shell assumption.
  • Use kt config show --json to inspect resolved values before you run or deploy anything.
  • Use kt doctor --config ... --profile ... to confirm the target environment is actually healthy.
  • Keep kt gateway run and kt run commands environment-specific and visible.
  • Standardize wrapper scripts or checked-in commands if multiple operators share the same environments.

Next steps​