CLI guide

paniolo secrets

Store project credentials in your operating system vault, check which names are present, and pass only the secrets a child command needs. Keep values out of the list file and command arguments. The CLI does not display stored values; the child controls its own output.

Availability

In the CLI source tree

The public command is implemented, but the published @paniolo/cli 0.5.63 package does not include it yet. The examples below apply when a release containing paniolo secrets is available.

Quick start

Names in the repo, values in the vault

Commit a plain-text list with one environment variable name per line. Blank lines and # comments are allowed. Keep values out of this file.

# config/env-secrets.dev.list
DATABASE_URL
API_TOKEN

Choose a service for this project and environment. The same name in myapp-dev and myapp-production refers to different vault entries.

paniolo secrets set DATABASE_URL --service myapp-dev
paniolo secrets set API_TOKEN --service myapp-dev
paniolo secrets status --service myapp-dev --list config/env-secrets.dev.list
paniolo secrets run --service myapp-dev --list config/env-secrets.dev.list -- npm run dev

set prompts without echoing the value. status prints names and set or missing state, never values. run starts the child only after local required names resolve. The -- separator keeps child flags with the child command.

Command reference

Store, check, run, delete

Action	Command	Result
Store	`secrets set NAME --service SERVICE`	Hidden prompt; replaces an existing value.
Pipe in	`secrets set NAME --service SERVICE --stdin`	Reads from stdin without putting the value in an argument.
Generate	`secrets set NAME --service SERVICE --generate`	Stores a random value without displaying it; refuses overwrite.
Check	`secrets status --service SERVICE --list FILE`	Reports vault presence; exits nonzero if a name is missing.
Run	`secrets run --service SERVICE --list FILE -- COMMAND`	Injects listed names and returns the child's exit status.
Delete	`secrets delete NAME --service SERVICE`	Removes one vault entry.

There is no command to print a stored value. A generated value cannot be recovered from CLI output. Confirm the service and name before deleting or rotating a credential, especially a signing key.

Runtime behavior

One child, a limited environment

For each listed name, run uses a nonempty parent environment value first. Locally it fills remaining names from the selected vault service. If a required name is still missing, the child does not start.

By default the child receives the listed secrets and essential operating system variables. Other credentials in your shell are removed. Use --inherit-env only when the child needs the full parent environment; it can pass unrelated credentials too.

CI

With a nonempty CI or GITHUB_ACTIONS marker, run skips the local vault. Supply the listed names through your CI secret mechanism and ensure the child reports missing required values. status checks the local vault, not CI readiness.

Windows and WSL

Windows and WSL use different credential stores. From WSL, call the Windows paniolo.exe to use Windows Credential Manager. Use --allow-linux-store only when you intentionally maintain a separate Linux vault.

For coding agents

Give your agent the secrets skill

The paniolo-secrets skill teaches agents the names-only workflow, service separation, safe child execution, CI behavior, and migration checks. It also tells agents never to request or print a value. Install it in a skill-capable agent when you want help using the command in a project:

npx skills add paniolo-ai/skills --skill paniolo-secrets

The skill is available now. For the rest of the catalog, see Paniolo skills.