Multi account and multi region

Multi-Account & Multi-Region

SSM Explorer is designed for real-world AWS environments where parameters live across multiple accounts, regions, and environments.

---

Option 1 — CLI Flags (Ad-hoc)

Pass profile and region directly on any command:

ssm-explorer list /app/config --profile prod_account --region eu-west-1
ssm-explorer search /app/config --profile dev_account --region us-east-2 --filter-path DATABASE

Useful for one-off queries without touching your config file.

---

Option 2 — Config Profile Mapping (Recommended)

Map AWS profile names to regions in ~/.config/ssm-explorer/config.toml. Then you only need --profile and the region resolves automatically.

[aws]
profile = ""
region  = ""

[aws.profiles.prod_account]
region = "eu-west-1"

[aws.profiles.dev_account]
region = "us-east-2"

[aws.profiles.stage_account]
region = "us-west-2"

Now this just works — no --region needed:

ssm-explorer list /app/config --profile prod_account
# → automatically uses eu-west-1

ssm-explorer diff /app/config --profile-a dev_account --profile-b prod_account
# → dev uses us-east-2, prod uses eu-west-1

---

Option 3 — Auto-Resolve Profile from Environment Tags

If your runtime already exposes environment tags (e.g. on an EC2 instance or in a CI pipeline), SSM Explorer can pick the right profile automatically — no flag required.

[aws]
profile = ""
region  = "eu-west-1"
profile_from_env_tags = ["Environment", "APP_ENV", "ENVIRONMENT"]

[aws.profile_from_env_value_map]
myapp-prod    = "prod_account"
myapp-staging = "stage_account"

Resolution order:

1. --profile CLI flag
2. aws.profile in config
3. First non-empty env tag from aws.profile_from_env_tags, optionally remapped via aws.profile_from_env_value_map

---

Cross-Account diff Examples

The diff command is the most powerful multi-account feature. See the Commands page for the full flag reference.

# Dev vs Prod — mapped regions auto-resolved
ssm-explorer diff /app/config \
  --profile-a dev_account \
  --profile-b prod_account

# Stage vs Prod in different regions, only show differences
ssm-explorer diff /app/config \
  --profile-a stage_account \
  --region-a us-west-2 \
  --profile-b prod_account \
  --region-b eu-central-1 \
  --exc-identicals

# Filter diff to only DATABASE-related parameters
ssm-explorer diff /app/config \
  --profile-a dev_account \
  --profile-b prod_account \
  --filter-path DATABASE

---

Fetch Strategy & Rate Limits

When querying large parameter stores across accounts, the fetch strategy and rate limits matter:

[search]
fetch_strategy   = "auto"   # "auto" | "batch" | "path"
max_get_tps      = 20
max_describe_tps = 3

Strategy	When to use
auto	Default — uses batch mode and falls back gracefully if IAM restricts DescribeParameters
batch	Force batch mode for faster fetches when permissions allow
path	Force single-API mode (GetParametersByPath) for maximum compatibility

Default rate limits (max_get_tps = 20, max_describe_tps = 3) stay within standard AWS Parameter Store quotas.