`ssmenv-cli`: Small CLIs for Big Order
A small CLI on top of AWS SSM shows how configuration gets from a named, access-controlled source into local processes and CI – including questions of versions and failures.
ssmenv-cli: Small CLIs for Big Order
Configuration isn’t a file format. It is a data set with access rights, versions and a history – the .env file is only a copy of it, and rarely the only one.
And copies multiply: one .env on the laptop, a second in CI, a third in the onboarding wiki, a fourth as a screenshot in a chat, a fifth “only on my machine”. At some point, nobody knows which value is authoritative anymore. That is where the bugs come from that can’t be reproduced, and the onboarding days you never get back. ssmenv-cli draws a consequence from this: the AWS Systems Manager Parameter Store holds the authoritative values, and the tool only translates them into the environment of a process.
The problem behind the tool#
The classic pattern is the shared .env note. It works on day one and slowly falls apart afterwards. I know the typical symptoms by heart: a secret accidentally ends up in the Git history. A new colleague gets an outdated copy and loses half a day to “it doesn’t run for me”. A value is changed in production but not documented anywhere traceable. And nobody can say offhand who actually has the right to read a production secret.
At its core, this isn’t a tooling problem but a boundary problem. There is no clear answer to three questions: Which data is authoritative? Who may read and change it? Where does a change become traceable? As long as these boundaries stay blurry, even the nicest script won’t help. So the three questions come before the tool.
The decision: SSM as the single source#
The load-bearing decision is: the AWS Systems Manager Parameter Store becomes the single source for configuration and secrets. Not Git, not the laptop, not the chat – a hierarchical namespace in AWS that is already there anyway if you deploy there.
That is a deliberate choice against a system of my own and against a large additional product. The Parameter Store brings exactly what I need for this boundary: a hierarchy via paths such as /myapp/prod/DATABASE_URL, encryption of sensitive values via KMS as SecureString, access control via IAM and a complete record via CloudTrail. That answers the three open questions from above without me operating a single line of infrastructure myself.
All that is missing now is the last mile: the way from the Parameter Store into the environment variables of a process. Exactly that – and nothing more – is the CLI’s job.
Architecture: a thin adapter, not a platform#
The most important architecture decision about ssmenv-cli is what the tool deliberately does not do. It stores nothing, it decides on no permissions, it holds no state. It is a thin adapter between an authoritative data source and the 12-factor principle “config in the environment”.
This separation is the actual boundary. The Parameter Store is the store of truth. IAM is the permission boundary. KMS is the confidentiality boundary. The CLI is pure translation: it reads a path prefix, resolves SecureString values and provides them to a process as its environment. Because the tool itself has no authority, I can swap it out at any time without anything changing in the security or data model. That is the value of a cleanly drawn boundary: it makes the tool replaceable.
A small example#
The practical core fits into a few lines. You set values once – ideally through automation, here by hand for illustration:
# Store a secret as an encrypted SecureString under a namespaced path
ssmenv set --path /myapp/prod DATABASE_URL "postgres://db.internal:5432/app"
# List everything under a prefix (values masked by default)
ssmenv list --path /myapp/prod
The real gain shows when loading. Instead of distributing a file, you resolve the environment at runtime:
# Run a process with the resolved environment, nothing written to disk
ssmenv exec --path /myapp/prod -- node server.js
# Or export into the current shell for a quick local session
eval "$(ssmenv export --path /myapp/staging)"
And because two environments are rarely identical, comparing them is a full-fledged command and not an afterthought:
# Show which keys differ between staging and prod
ssmenv diff --path /myapp/staging --path /myapp/prod
The example is deliberately small. It doesn’t simulate a complete platform; it shows the boundary: the CLI only touches the last mile between store and process. A good example isn’t the one with the most options but the one where you can discuss the decision after five minutes.
Sketch#
flowchart LR Store["SSM Parameter Store<br/>/myapp/prod/*"] --> CLI["ssmenv-cli<br/>thin adapter"] IAM["IAM<br/>permission boundary"] --> CLI KMS["KMS<br/>SecureString decrypt"] --> CLI CLI --> Env["process env"] Env --> App["node server.js"]
The sketch makes the responsibilities visible: the store holds the truth, IAM and KMS draw the boundaries, the CLI translates. No box in this picture depends on a tool name – that is intentional.
Trade-offs: why small, why not more#
The obvious counter-question is: why not go straight for a full-fledged secret management product? That is a trade-off, not dogma. A large system brings rotation, dynamic credentials and fine-grained policies – plus operations, a learning curve and another dependency. For many teams that deploy on AWS anyway, that is more machinery than the problem calls for.
I build the smallest solution that cleanly answers the three boundary questions and leave room for a switch. Because ssmenv-cli is only an adapter, that switch is cheap. If a team later needs rotation on a large scale, I swap the backend store, not the mental model. The expensive decision – configuration is central, access-controlled and auditable – stays the same. That is exactly what a trade-off should look like: start small without blocking the way to expand.
The second trade-off concerns network dependency. Resolving values from the store at runtime means that a process start requires AWS to be reachable. That is a deliberate choice: I trade a short network call at startup for the permanent danger of outdated local copies. For local offline work, there is still an explicit export – a visible exception that someone has to trigger deliberately.
Operational consequences#
The consequences of an architecture don’t show in the demo but in failures, load, rollback and review. Here the model holds, because the heavy tasks sit where they belong.
Access is an IAM question. Who may read /myapp/prod/* is written in a policy and not in a chat history – and can therefore be checked and revoked. Confidentiality is a KMS question: sensitive values are stored encrypted as SecureString, and the CLI only decrypts if the caller has the right to do so. Traceability is a CloudTrail question: every read and write access is recorded. When someone asks “who read this secret when?”, there is an answer instead of a shrug.
Reversibility is the strongest point. Because the Parameter Store keeps versions, a wrongly set value isn’t an emergency but a rollback to the previous version. That makes a change to configuration as manageable as a change to code.
Failure cases#
An idea is only robust once the failure path is described. Three cases belong to it.
Missing permission: if the caller isn’t allowed to read the path, the CLI must abort hard and clearly. An empty value that silently slips through as an empty string is the most dangerous bug – the application starts with half its configuration and only falls over deep in operation. An exec must therefore fail on missing or unreadable keys before the target process even starts.
A partially resolved environment: if only nine of ten expected keys are there, that isn’t “almost right” but wrong. I treat it as an error with a clear message about which key is missing.
Network and region errors: an unreachable store or a wrong region must not pass through a cryptic SDK exception but a message that names the path and the cause. The difference between demo and operations almost always lies in exactly these unexciting error messages.
The same boundary in CI#
The real test of a configuration boundary is the pipeline. In CI, it isn’t a human with personal permissions that runs but a role – and that is exactly what makes the model clean. Instead of duplicating secrets as CI variables, the build job gets an IAM role that may read exactly the path it needs, and no other. A staging deploy sees /myapp/staging/*, a production deploy /myapp/prod/*, and the separation isn’t a convention but a permission.
# In CI: the job's role grants read on /myapp/staging/* only
ssmenv exec --path /myapp/staging -- npm run deploy
That makes the whole class of “the secret now also lives in CI” copies disappear. There is no second source that can go stale, and the principle of least privilege applies to machines just as it does to people. If a CI token is compromised, the damage is limited to exactly the path this job was allowed to read – traceable in CloudTrail, revocable in a policy. That literally the same command runs locally, in CI and in production, just with a different path, is the core of reproducibility.
Business outcome: shorter cycles, less friction#
The benefit is measurable, even if the tool is small. Onboarding that used to mean “get the current .env from somebody” becomes a single command against a path – half a day of friction turns into minutes. The whole class of “works for me, not for you” bugs disappears, because dev, CI and production use the same authoritative source and differ only in the path prefix. And the risk of leaving a secret in the Git history drops structurally, because there is no longer any reason to put secrets in files that get versioned.
These are the three levers that count for technical decision-makers: shorter cycles when setting up and switching environments, less friction in everyday work and higher quality through reproducible configuration. The gain isn’t in the tool’s name but in the decision to treat configuration like a verifiable data system.
The pattern for small CLIs#
ssmenv-cli deliberately stays an adapter. Whether the Parameter Store can really be the authoritative source is decided by write permissions, the handling of versions and the behavior when it’s unreachable. The CLI solves none of these questions; it only makes the answer that was chosen usable for local processes and CI.
That’s why I prefer to build many small, sharply delimited CLIs rather than one large, blurry framework. Each does one job, has a visible boundary and at least one honest failure case. The same way of thinking is in ssmenv-cli: small in scope, clear in responsibility, replaceable in detail. Big order doesn’t come from big tools but from many small ones with clear responsibilities.
Closing#
More important than how ssmenv-cli works is where the boundary runs: configuration central and auditable, the tool deliberately thin and replaceable. This decision still holds when the tool has long been replaced by another one – and that is exactly why you can reuse it in the next team conversation.
Further reading#
- Repository ssmenv-cli: https://github.com/MikeBild/ssmenv-cli
The source helps you cross-check the concrete implementation.
Revised and translated from German with the help of AI.