{"id":25853990,"url":"https://github.com/robot-wranglers/aws-ssm-tool","last_synced_at":"2026-05-05T18:36:25.329Z","repository":{"id":227235212,"uuid":"653991275","full_name":"Robot-Wranglers/aws-ssm-tool","owner":"Robot-Wranglers","description":"CLI tools for working with SSM","archived":false,"fork":false,"pushed_at":"2024-03-14T05:48:54.000Z","size":140,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-06-08T21:11:26.345Z","etag":null,"topics":["aws","aws-ssm-parameter-store","python3","secrets","secrets-management"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Robot-Wranglers.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-06-15T07:05:34.000Z","updated_at":"2024-08-20T00:35:26.000Z","dependencies_parsed_at":null,"dependency_job_id":"58a6535e-30d6-4c2f-9c9c-c96d2ba3cdcf","html_url":"https://github.com/Robot-Wranglers/aws-ssm-tool","commit_stats":null,"previous_names":["robot-wranglers/aws-ssm-tool"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Robot-Wranglers/aws-ssm-tool","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Robot-Wranglers%2Faws-ssm-tool","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Robot-Wranglers%2Faws-ssm-tool/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Robot-Wranglers%2Faws-ssm-tool/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Robot-Wranglers%2Faws-ssm-tool/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Robot-Wranglers","download_url":"https://codeload.github.com/Robot-Wranglers/aws-ssm-tool/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Robot-Wranglers%2Faws-ssm-tool/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263427299,"owners_count":23464840,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","aws-ssm-parameter-store","python3","secrets","secrets-management"],"created_at":"2025-03-01T15:27:29.600Z","updated_at":"2026-05-05T18:36:25.320Z","avatar_url":"https://github.com/Robot-Wranglers.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ctable width=100%\u003e\n  \u003ctr\u003e\n    \u003ctd colspan=2\u003e\u003cstrong\u003e\n    aws-ssm-tool\n      \u003c/strong\u003e\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd width=15%\u003e\u003cimg src=https://raw.githubusercontent.com/Robot-Wranglers/aws-ssm-tool/master/img/icon.png style=\"width:150px\"\u003e\u003c/td\u003e\n    \u003ctd\u003e\n    SSM tool is a small helper for interacting with Amazon Simple Systems Manager, focusing on secrets storage/retrieval.\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\u003ca href=https://pypi.python.org/pypi/aws-ssm-tool/\u003e\u003cimg src=\"https://img.shields.io/pypi/l/aws-ssm-tool.svg\"\u003e\u003c/a\u003e\n\u003ca href=https://pypi.python.org/pypi/aws-ssm-tool/\u003e\u003cimg src=\"https://badge.fury.io/py/aws-ssm-tool.svg\"\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/Robot-Wranglers/aws-ssm-tool/actions/workflows/python-test.yml\"\u003e\u003cimg src=\"https://github.com/Robot-Wranglers/aws-ssm-tool/actions/workflows/python-test.yml/badge.svg\"\u003e\u003c/a\u003e\n\u003ca href=\"https://hub.docker.com/r/robotwranglers/aws-ssm-tool/tags\"\u003e\u003cimg src=\"https://img.shields.io/badge/dockerhub--blue.svg?logo=Docker\"\u003e\u003c/a\u003e\n\n---------------------------------------------------------------------------------\n\n\u003cdiv class=\"toc\"\u003e\n\u003cul\u003e\n\u003cli\u003e\u003ca href=\"#overview\"\u003eOverview\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"#installation\"\u003eInstallation\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"#usage\"\u003eUsage\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"#advanced-features\"\u003eAdvanced Features\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"#shell-completion\"\u003eShell Completion\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"#environment-variables\"\u003eEnvironment Variables\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"#configuration-file\"\u003eConfiguration File\u003c/a\u003e\u003c/li\u003e\n\u003cli\u003e\u003ca href=\"#usage-from-docker\"\u003eUsage from Docker\u003c/a\u003e\u003c/li\u003e\n\u003c/ul\u003e\n\u003c/div\u003e\n\n\n---------------------------------------------------------------------------------\n\n## Overview\n\nThe [AWS SSM Parameter-Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html) is great, but can be awkward to work with via the `awscli` tool.  This project provides the `ssm` tool as an alternative interface with simple CRUD.  It also supports moving or copying trees of multiple parameters, and performing those operations across multiple AWS profiles.\n\nSee [setup.cfg](setup.cfg) to find the latest info about required versions of boto.  There are other dependencies, including the popular [click](https://click.palletsprojects.com/) library for CLI support and [rich](https://rich.readthedocs.io/) for pretty output.\n\nSee the [Usage section](#usage) for more details.\n\n---------------------------------------------------------------------------------\n\n## Installation\n\nSee [pypi](https://pypi.org/project/aws-ssm-tool) for available releases.\n\n```\npip install aws-ssm-tool\n```\n\n---------------------------------------------------------------------------------\n\n## Usage\n\nAfter installation, you can invoke this tool as either `ssm` or `python -m ssm`.\n\n### Available Commands\n\n#### Core CRUD Operations\n\n| Command | Aliases | Description |\n|---------|---------|-------------|\n| `list` | `ls` | List parameters below a path |\n| `list-dirs` | `ls-dirs` | List directories (non-leaf paths) only |\n| `read` | `get` | Read a single parameter value |\n| `update` | `put`, `set` | Create or update a parameter |\n| `delete` | `rm` | Delete a single parameter |\n| `delete-path` | `rm-path` | Delete all parameters under a path |\n| `get-many` | `get-path` | Get all parameters under a path |\n| `put-many` | `put-path` | Create multiple parameters from a file |\n\n#### Copy/Move Operations\n\n| Command | Aliases | Description |\n|---------|---------|-------------|\n| `copy` | `cp` | Copy a parameter to a new location |\n| `copy-many` | `cp-many`, `cp-path` | Copy all parameters under a path |\n| `move` | `mv` | Move a parameter to a new location |\n| `move-many` | `mv-many`, `mv-path` | Move all parameters under a path |\n| `rename` | `ren` | Rename a parameter (same profile) |\n\n#### Search/Query Operations\n\n| Command | Aliases | Description |\n|---------|---------|-------------|\n| `search` | `find` | Search parameters by name pattern |\n| `grep` | `grep-values` | Search parameters by value content |\n| `diff` | `compare` | Compare parameters between paths/profiles |\n| `count` | `cnt` | Count parameters under a path |\n| `tree` | - | Display parameters in tree format with metadata |\n| `stat` | `st` | Show account info and parameter stats |\n\n#### History/Versioning\n\n| Command | Aliases | Description |\n|---------|---------|-------------|\n| `history` | `hist` | View parameter version history |\n\n#### Tag Management\n\n| Command | Aliases | Description |\n|---------|---------|-------------|\n| `tags` | `show-tags` | Show tags for a parameter |\n| `add-tags` | - | Add tags to a parameter |\n| `remove-tags` | - | Remove tags from a parameter |\n\n#### GitOps/Sync Operations\n\n| Command | Aliases | Description |\n|---------|---------|-------------|\n| `sync-pull` | `pull` | Pull parameters from SSM to a local file |\n| `sync-push` | `push` | Push parameters from a local file to SSM |\n| `sync-diff` | `sync-status` | Show differences between local file and SSM |\n\n#### Backup/Restore\n\n| Command | Aliases | Description |\n|---------|---------|-------------|\n| `backup` | - | Create compressed backup with metadata |\n| `restore` | - | Restore parameters from backup archive |\n\n#### Environment/Export Operations\n\n| Command | Aliases | Description |\n|---------|---------|-------------|\n| `env-export` | `env`, `dotenv` | Export as environment variables (.env format) |\n| `export-terraform` | - | Export as Terraform resources |\n| `k8s-export` | - | Export as Kubernetes Secret manifest |\n\n#### Security Operations\n\n| Command | Aliases | Description |\n|---------|---------|-------------|\n| `rotate` | - | Rotate a secret with a new random value |\n| `generate-secret` | - | Generate a random secret value |\n| `rekey` | - | Re-encrypt parameters with a new KMS key |\n| `list-by-kms` | `ls-kms` | List parameters by KMS key |\n\n#### Policy Management\n\n| Command | Aliases | Description |\n|---------|---------|-------------|\n| `get-policy` | - | Get parameter policy (expiration, etc.) |\n| `set-policy` | - | Set parameter policy (requires Advanced tier) |\n\n#### Validation\n\n| Command | Aliases | Description |\n|---------|---------|-------------|\n| `validate` | - | Validate parameters against a schema |\n| `lint` | - | Lint a parameters file before pushing |\n\n#### Monitoring/Audit\n\n| Command | Aliases | Description |\n|---------|---------|-------------|\n| `watch` | - | Watch for changes to parameters |\n| `audit` | `audit-log` | Query CloudTrail for SSM access events |\n\n#### CI/CD Integration\n\n| Command | Aliases | Description |\n|---------|---------|-------------|\n| `inject` | - | Inject SSM values into template files |\n| `verify-access` | `check-access` | Verify access to parameters (for CI/CD checks) |\n| `put-template` | - | Create parameters from template with variables |\n\n### Common Options\n\nAll commands support these options:\n\n- `--profile`: AWS profile to use (default: `default`, or `AWS_PROFILE` env var)\n- `--debug`: Enable verbose debug output\n- `--quiet` / `-q`: Suppress non-essential output\n- `--format`: Output format (`json`, `yaml`, `stdout`, `tree`, `env`)\n\n### Basic Examples\n\n```bash\n# List all parameters\nssm ls /\n\n# Read a specific parameter\nssm get /prod/database/password\n\n# Read a specific version\nssm get /prod/database/password --version 3\n\n# Create/update a parameter\nssm put /dev/api/key \"my-secret-value\"\n\n# Create with specific type (String, SecureString, StringList)\nssm put /config/setting \"value\" --type String\n\n# Read value from file\nssm put /prod/cert --file ./certificate.pem\n\n# Read value from stdin\necho \"secret\" | ssm put /prod/secret --stdin\n\n# Copy a parameter\nssm cp /prod/config/key /staging/config/key\n\n# Copy between AWS profiles\nssm cp /prod/secret /staging/secret --src-profile prod --dst-profile staging\n\n# Copy an entire path hierarchy\nssm cp-many /prod/config /staging/config\n\n# Rename a parameter\nssm rename /old/path/key /new/path/key\n\n# Search for parameters by name pattern\nssm search \"/prod/*/password\"\nssm search \"*database*\"\n\n# Search for parameters by value content\nssm grep \"localhost\" --path /dev/\nssm grep --regex \"https?://.*\\.example\\.com\" --path /prod/\n\n# Count parameters\nssm count /prod/\nssm count / --by-type\n\n# Compare two paths\nssm diff /prod/config /staging/config\nssm diff /prod/config /staging/config --show-values\n\n# View parameter history\nssm history /prod/secret --max-results 20\n\n# Delete with preview (dry-run)\nssm rm /test/secret --dry-run\n\n# Delete an entire path (with confirmation)\nssm rm-path /test/old-config\n\n# Bulk create from YAML file\nssm put-many /prod/config --file secrets.yaml\n\n# View and manage tags\nssm tags /prod/secret\nssm add-tags /prod/secret --tag env=prod --tag team=backend\nssm remove-tags /prod/secret --key deprecated\n```\n\nSee [the integration tests](https://github.com/Robot-Wranglers/aws-ssm-tool/tree/master/tests/integration/test.sh) for more examples.\n\n---------------------------------------------------------------------------------\n\n## Advanced Features\n\n### GitOps/Sync Workflow\n\nManage parameters using a GitOps workflow with local YAML/JSON files:\n\n```bash\n# Pull current state from SSM to a local file\nssm sync-pull /prod/config ./config.yaml\n\n# Check what would change before pushing\nssm sync-diff /prod/config ./config.yaml\n\n# Push changes to SSM\nssm sync-push /prod/config ./config.yaml --dry-run\nssm sync-push /prod/config ./config.yaml\n\n# Push and delete parameters not in the file\nssm sync-push /prod/config ./config.yaml --delete-missing\n```\n\n### Backup and Restore\n\nCreate full backups with metadata and restore them:\n\n```bash\n# Create a compressed backup with metadata\nssm backup /prod/ ./backup.json.gz\n\n# Create backup without metadata\nssm backup /prod/ ./backup.json.gz --no-metadata\n\n# Restore from backup (dry-run)\nssm restore ./backup.json.gz --dry-run\n\n# Restore to the same location\nssm restore ./backup.json.gz\n\n# Restore to a different path\nssm restore ./backup.json.gz --target-prefix /staging/\n\n# Restore and overwrite existing parameters\nssm restore ./backup.json.gz --overwrite\n```\n\n### Environment Variable Export\n\nExport parameters as environment variables for different use cases:\n\n```bash\n# Export as .env file format\nssm env-export /prod/app/ \u003e .env\n\n# Export with a prefix\nssm env-export /prod/app/ --prefix APP_\n\n# Export as Docker --env flags\nssm env-export /prod/app/ --docker\n# Output: --env DB_HOST=localhost --env DB_PORT=5432\n\n# Don't quote special characters\nssm env-export /prod/app/ --no-quote\n```\n\n### Secret Rotation\n\nGenerate and rotate secrets automatically:\n\n```bash\n# Generate a random secret (32 chars, alphanumeric)\nssm generate-secret\n\n# Generate with specific options\nssm generate-secret --length 64 --chars all\nssm generate-secret --chars alphanumeric --exclude \"0O1l\"\n\n# Rotate a secret (generate new value and update)\nssm rotate /prod/api/key --dry-run\nssm rotate /prod/api/key\nssm rotate /prod/api/key --length 64 --chars all\n```\n\n### KMS Key Management\n\nManage encryption keys for your parameters:\n\n```bash\n# List parameters encrypted with a specific KMS key\nssm list-by-kms alias/my-key --path /prod/\n\n# Re-encrypt parameters with a new KMS key\nssm rekey /prod/ --from-key alias/old-key --to-key alias/new-key --dry-run\nssm rekey /prod/ --from-key alias/old-key --to-key alias/new-key\n```\n\n### Parameter Policies\n\nSet expiration and notification policies (requires Advanced tier):\n\n```bash\n# Get current policy\nssm get-policy /prod/temp-token\n\n# Set expiration policy (expires in 90 days)\nssm set-policy /prod/temp-token --expiration-days 90\n\n# Set notification before expiration\nssm set-policy /prod/cert --expiration-days 365 --notify-before-days 30\n\n# Set no-change notification (alert if not updated)\nssm set-policy /prod/rotating-key --no-change-days 7\n```\n\n### Watch for Changes\n\nMonitor parameters for changes in real-time:\n\n```bash\n# Watch all parameters under a path\nssm watch /prod/\n\n# Watch with custom interval\nssm watch /prod/ --interval 10\n```\n\n### Template Support\n\nCreate parameters from templates with variable substitution:\n\n```bash\n# template.yaml:\n# database_url: postgres://{{DB_USER}}:{{DB_PASS}}@{{DB_HOST}}/{{DB_NAME}}\n# api_endpoint: https://{{ENVIRONMENT}}.api.example.com\n\nssm put-template /prod/app/ template.yaml \\\n    --var DB_USER=admin \\\n    --var DB_PASS=secret123 \\\n    --var DB_HOST=db.example.com \\\n    --var DB_NAME=myapp \\\n    --var ENVIRONMENT=prod\n```\n\n### Validation\n\nValidate parameters against schemas:\n\n```bash\n# Check that parameters exist\nssm validate /prod/required-config/ --exists\n\n# Validate against a JSON schema\nssm validate /prod/config/ --schema ./schema.json\n\n# Lint a parameters file before pushing\nssm lint ./config.yaml\n```\n\nSchema file example:\n```json\n{\n  \"required\": [\"database_url\", \"api_key\"],\n  \"parameters\": {\n    \"database_url\": {\n      \"pattern\": \"^postgres://.*$\",\n      \"minLength\": 10\n    },\n    \"log_level\": {\n      \"enum\": [\"DEBUG\", \"INFO\", \"WARNING\", \"ERROR\"]\n    }\n  }\n}\n```\n\n### Audit Log\n\nQuery CloudTrail for SSM access events:\n\n```bash\n# View recent SSM events\nssm audit /\n\n# Filter by time period\nssm audit / --since 24h\nssm audit / --since 7d\nssm audit / --since 2w\n\n# Filter by user\nssm audit / --who admin@example.com\n\n# Filter by action\nssm audit / --action GetParameter\nssm audit / --action PutParameter\n```\n\n### CI/CD Integration\n\nIntegrate with CI/CD pipelines:\n\n```bash\n# Verify access to required parameters (exit 0 if accessible)\nssm verify-access /prod/app/\n\n# Inject SSM values into config files\n# config.template: \"database: {{SSM:/prod/db/url}}\"\nssm inject config.template -o config.yaml\n\n# Export for use in scripts\neval $(ssm env-export /prod/app/)\n```\n\n### Terraform Export\n\nExport parameters as Terraform resources:\n\n```bash\n# Export to stdout\nssm export-terraform /prod/app/\n\n# Export to a file\nssm export-terraform /prod/app/ -o ssm_parameters.tf\n```\n\n### Kubernetes Integration\n\nExport parameters as Kubernetes Secrets:\n\n```bash\n# Export as Kubernetes Secret manifest\nssm k8s-export /prod/app/\n\n# With custom name and namespace\nssm k8s-export /prod/app/ --secret-name my-app-secrets --namespace production\n\n# Export to a file\nssm k8s-export /prod/app/ -o k8s-secret.yaml\n\n# Apply directly to cluster\nssm k8s-export /prod/app/ | kubectl apply -f -\n```\n\n---------------------------------------------------------------------------------\n\n## Shell Completion\n\nEnable tab completion for your shell:\n\n### Bash\n\n```bash\n# Add to ~/.bashrc\neval \"$(_SSM_COMPLETE=bash_source ssm)\"\n\n# Or generate a completion script\n_SSM_COMPLETE=bash_source ssm \u003e ~/.ssm-complete.bash\necho \"source ~/.ssm-complete.bash\" \u003e\u003e ~/.bashrc\n```\n\n### Zsh\n\n```bash\n# Add to ~/.zshrc\neval \"$(_SSM_COMPLETE=zsh_source ssm)\"\n```\n\n### Fish\n\n```bash\n# Add to ~/.config/fish/completions/ssm.fish\n_SSM_COMPLETE=fish_source ssm \u003e ~/.config/fish/completions/ssm.fish\n```\n\n---------------------------------------------------------------------------------\n\n## Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `AWS_PROFILE` | AWS profile to use | `default` |\n| `SSM_LOG_LEVEL` | Log verbosity (DEBUG, INFO, WARNING, ERROR) | `WARNING` |\n\n---------------------------------------------------------------------------------\n\n## Configuration File\n\nYou can create a `.ssm.yaml` (or `.ssm.yml` or `.ssm.json`) file in your project directory for default settings:\n\n```yaml\n# .ssm.yaml\ndefault_profile: production\ndefault_path_prefix: /myapp/prod/\nvalidation:\n  required:\n    - database_url\n    - api_key\n```\n\n---------------------------------------------------------------------------------\n\n## Usage from Docker\n\nIf you want to build locally, see the [Dockerfile in this repo](Dockerfile) and use the [Makefile](Makefile):\n\n```bash\n$ make docker-build docker-test\n```\n\nIf you don't want to build the container yourself, you can pull it like this:\n\n```bash\n$ docker pull robotwranglers/aws-ssm-tool\nUsing default tag: latest\nlatest: Pulling from robotwranglers/aws-ssm-tool\ndocker.io/robotwranglers/aws-ssm-tool:latest\n```\n\nSee a typical invocation below.  The 1st volume is for authenticating with SSM.  The 2nd volume shares the working directory with the container so commands using files (like `ssm put --file ./path/to/file /path/to/key`) can still work.\n\n```bash\n$ docker run \\\n  -v ~/.aws:/root/.aws \\\n  -v `pwd`:/workspace \\\n  -w /workspace \\\n  docker.io/robotwranglers/aws-ssm-tool:latest \\\n    ssm ls /\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobot-wranglers%2Faws-ssm-tool","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frobot-wranglers%2Faws-ssm-tool","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobot-wranglers%2Faws-ssm-tool/lists"}