ssm-explorer

SSM Explorer 🔍

Part of the Douklar DevOps Tools series.

A professional, feature-rich CLI tool for searching, filtering, and inspecting AWS Systems Manager (SSM) Parameter Store parameters — with beautiful terminal output.

Features

🔍 Search parameters by path prefix (recursive or flat)
🎯 Filter by environment variable name pattern (key or value)
📋 List all parameters under a path with ENV_VAR → value display
🖥️ Interactive Browse dynamic TUI parameter viewer (browse)
🌐 Deep Search across multiple profiles and regions simultaneously (deepsearch)
⚙️ Config Management view and set configurations directly from CLI (config)
📤 Export parameters as .env file or JSON
🔐 SecureString decryption support
🗂️ Multi-profile AWS support via --profile
🌍 Multi-region support via --region
🖥️ Beautiful Rich terminal tables with pagination info
📦 JSON output mode for scripting and pipelines

Fetch Speed

SSM Explorer defaults to search.fetch_strategy = "auto":

batch mode gets parameter names with DescribeParameters in pages of 50, then fetches values with parallel GetParameters batches of 10.
If IAM denies the extra read APIs, auto falls back to the original GetParametersByPath flow.
Client-side rate limits default to max_get_tps = 20 and max_describe_tps = 3 to stay under standard AWS Parameter Store quotas.

Use search.fetch_strategy = "path" in config to force the original single-API behavior.

Installation

Requires Python 3.10+

Poetry-first install. Run once from this repository:

cd SSM
poetry install
poetry run ssm-explorer install

Then run ssm-explorer from any directory:

ssm-explorer --help
ssm-explorer check --profile my_profile_aws --region eu-west-1

If ~/.local/bin is not on your PATH, add it to your shell profile:

export PATH="$HOME/.local/bin:$PATH"

Uninstall the local wrapper:

ssm-explorer uninstall

This keeps the config file by default. To remove it too, run ssm-explorer uninstall --remove-config.

pipx install . also works, but it is optional.

Usage

ssm-explorer --help
ssm-explorer check
ssm-explorer config init

Commands

`check` — Verify install, config, profile, region, and commands

# Uses config defaults
ssm-explorer check

# Or validate explicit profile/region
ssm-explorer check --profile my_profile_aws --region eu-west-1

check is offline by default. It validates local config, registered CLI commands, local AWS profile names, and known SSM regions without calling AWS APIs.

`list` — List all parameters under a path

ssm-explorer list /my/path/to/var \
  --profile my_profile_aws \
  --region eu-west-1

# With decryption of SecureString values
ssm-explorer list /my/path/to/var \
  --profile my_profile_aws \
  --decrypt

# Output as JSON (for scripting)
ssm-explorer list /my/path/to/var \
  --profile my_profile_aws \
  --output json

`search` — Search/filter parameters by path or value pattern

# Search for parameters whose full path contains "DATABASE"
ssm-explorer search /my/path/to/var \
  --profile my_profile_aws \
  --filter-path DATABASE

# Search by value pattern
ssm-explorer search /my/path/to/var \
  --profile my_profile_aws \
  --filter-value "postgres://"

# Combine both
ssm-explorer search /my/path/to/var \
  --profile my_profile_aws \
  --filter-path DB \
  --filter-value "5432"

`get` — Get a single parameter value

ssm-explorer get /my/path/to/var/DATABASE_URL \
  --profile my_profile_aws \
  --decrypt

`diff` — Compare across paths, profiles, or regions

# Compare two different paths in the same account
ssm-explorer diff /app/dev /app/prod --profile my_profile_aws

# Compare same path across two AWS accounts (dev vs prod)
ssm-explorer diff /app/config \
  --profile-a my_dev_account \
  --profile-b my_prod_account

# Compare two AWS accounts in the same explicit region
ssm-explorer diff /app/config \
  --profile-a my_dev_account \
  --profile-b my_prod_account \
  --region eu-west-1

# Compare different paths across two AWS accounts
ssm-explorer diff /app/dev/config /app/prod/config \
  --profile-a my_dev_account \
  --profile-b my_prod_account

# Compare same account across regions
ssm-explorer diff /app/config \
  --profile-a default \
  --region-a us-east-1 \
  --region-b eu-west-1

# Compare two accounts and force explicit region per account
ssm-explorer diff /app/config \
  --profile-a stage_account \
  --region-a us-west-2 \
  --profile-b prod_account \
  --region-b eu-central-1

# Exclude identical values and show differences only
ssm-explorer diff /app/config \
  --profile-a stage_account \
  --profile-b prod_account \
  --region eu-west-1 \
  --exc-identicals

# Exclude parameters that exist only in Source B
ssm-explorer diff /app/config \
  --profile-a stage_account \
  --profile-b prod_account \
  --region eu-west-1 \
  --exc-missing-a

# Compare explicit source paths, then only diff parameters whose full path contains "browser"
ssm-explorer diff \
  --profile-a stage_account \
  --region-a us-west-2 \
  --path-a /app/config \
  --profile-b prod_account \
  --region-b eu-central-1 \
  --path-b /app/config \
  --filter-path browser

`export` — Export parameters to a .env or JSON file

# Export to .env file
ssm-explorer export /my/path/to/var \
  --profile my_profile_aws \
  --decrypt \
  --format env \
  --output-file .env

# Export to JSON
ssm-explorer export /my/path/to/var \
  --profile my_profile_aws \
  --format json \
  --output-file params.json

`browse` — Interactively browse and live-filter parameters

# Browse with interactive TUI under a path
ssm-explorer browse /my/path/to/var --profile my_profile_aws

# With decryption of SecureString values
ssm-explorer browse /my/path/to/var --profile my_profile_aws --decrypt

# Print raw value to stdout after selection
ssm-explorer browse /my/path --output value

Loads all parameters from the path, then opens a real-time TUI. Type to filter instantly. Press Tab to switch between filtering by ENV name or by value. Press Up/Down keys to navigate, and Enter to inspect the parameter. Press Esc or Ctrl+C to exit.

`deepsearch` — Search parameters across multiple profiles/regions

# Deep search root path across profile/region combinations
ssm-explorer deepsearch --profile dev,prod --region us-east-1,eu-west-1 --filter-path "DATABASE"

# Deep search with value filtering and decryption
ssm-explorer deepsearch --profile dev,stage --region us-east-1 --filter-value "postgres://" --decrypt

`config` — View and manage local configuration settings

# Print active config file path
ssm-explorer config path

# Initialise default config.toml file
ssm-explorer config init

# Display effective configuration settings
ssm-explorer config show

# Set a configuration parameter directly
ssm-explorer config set aws.profile my_dev_profile
ssm-explorer config set display.max_value_length 100

Multi-Account & Multi-Region Support

SSM Explorer naturally supports querying multiple AWS accounts and regions.

1. Using CLI Flags (Ad-hoc)

You can manually specify the profile and region for any command:

ssm-explorer list /app/config --profile prod_account --region eu-west-1

2. Using Config Mapping (Recommended)

You can map specific AWS regions to specific AWS profiles in your config.toml file (located at ~/.config/ssm-explorer/config.toml by default).

Once mapped, you only need to provide the --profile flag. The tool will automatically look up the correct region for that profile:

# config.toml
[aws]
profile = ""
region = ""

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

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

With the above config, running this command will automatically fetch from eu-west-1:

ssm-explorer list /app/config --profile prod_account

This is incredibly useful for the diff command, where --profile-a and --profile-b will automatically inherit their mapped regions:

ssm-explorer diff /app/config --profile-a dev_account --profile-b prod_account

3. Auto-Resolve Profile From Environment Tags

If your runtime already has environment tags like Environment=myapp-prod, you can auto-resolve AWS profile without passing --profile:

[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:

--profile CLI flag
aws.profile
First non-empty env key from aws.profile_from_env_tags (optionally remapped via aws.profile_from_env_value_map)

Terminal Output Example

┌─────────────────────────────────────────────────────────────────────┐
│              SSM Parameter Store — /my/path/to/var                  │
│                   Profile: my_profile_aws  •  Region: eu-west-1     │
└─────────────────────────────────────────────────────────────────────┘

 Parameter Store Results (5 parameters)

 ┌──────────────┬──────────────────────────────┬───────────────────┐
 │ ENV Variable │ Full Path                    │ Value             │
 ├──────────────┼──────────────────────────────┼───────────────────┤
 │ DATABASE_URL │ /my/path/to/var/DATABASE_URL │ postgres://db:... │
 │ REDIS_HOST   │ /my/path/to/var/REDIS_HOST   │ my-redis.cache... │
 │ API_KEY      │ /my/path/to/var/API_KEY      │ *** (encrypted)   │
 └──────────────┴──────────────────────────────┴───────────────────┘

Project Structure

SSM/
├── pyproject.toml              # Poetry config & dependencies
├── poetry.lock                 # Locked dependency versions
├── README.md                   # This file
├── src/
│   └── ssm_explorer/
│       ├── __init__.py         # Package init & version
│       ├── main.py             # CLI entry point (Typer app)
│       ├── config.py           # Settings & configuration (Pydantic)
│       ├── commands/
│       │   ├── __init__.py
│       │   ├── browse_cmd.py   # `browse` command (interactive TUI)
│       │   ├── check_cmd.py    # `check` command (diagnostics)
│       │   ├── config_cmd.py   # `config` command group
│       │   ├── deepsearch_cmd.py # `deepsearch` command
│       │   ├── diff_cmd.py     # `diff` command
│       │   ├── examples.py     # Command examples
│       │   ├── export_cmd.py   # `export` command
│       │   ├── get_cmd.py      # `get` command
│       │   ├── install_cmd.py  # `install` and `uninstall` wrapper commands
│       │   ├── list_cmd.py     # `list` command
│       │   └── search_cmd.py   # `search` command
│       ├── aws/
│       │   ├── __init__.py
│       │   └── ssm_client.py   # AWS SSM client wrapper
│       ├── models/
│       │   ├── __init__.py
│       │   └── parameter.py    # Pydantic data models
│       └── display/
│           ├── __init__.py
│           ├── interactive.py  # Prompt-toolkit interactive filter TUI
│           └── renderer.py     # Rich terminal rendering
└── tests/
    ├── __init__.py
    ├── conftest.py
    ├── test_check_cmd.py
    ├── test_config.py
    ├── test_deepsearch_cmd.py
    ├── test_diff_cmd.py
    ├── test_models.py
    ├── test_renderer.py
    ├── test_ssm_client.py
    └── test_table_column_cli.py

Development

# Install with dev dependencies
poetry install

# Run linter
poetry run ruff check src/

# Run type checker
poetry run mypy src/

# Run tests
poetry run pytest

# Run with coverage
poetry run pytest --cov=ssm_explorer

Contributing

See CONTRIBUTING.md for development setup, commit conventions, and PR workflow.

License

MIT — see LICENSE for details.

Built with ❤️ by Douklar DevOps Tools

This site is open source. Improve this page.