@punks/secrets

The DP Secrets command line interface. The installed executable is secrets.

Install from npm

Supported runtimes are Node.js 22.22.2 through 22.x, 24.15.0 through 24.x, or 26.0.0 and newer. Node.js 23 and 25 are not supported.

npm install --global @punks/secrets

Prereleases use the next tag. Stable releases use latest, which npm selects when no tag is supplied.

Agent setup

Humans can continue directly to Quick start. Agents must install the agent skill globally, then activate it before their first CLI invocation:

npx skills add https://github.com/wearedevpunks/skills/tree/main/skills/misc/secrets-cli --skill secrets-cli --global --yes

Activate $secrets-cli before running this CLI.

The package only prints this guidance; it never installs the skill or changes agent configuration automatically. If package lifecycle scripts are disabled, run secrets --help to see the same command.

After agent setup, verify the global install:

secrets --help

Humans, or agents that already installed and activated the skill, can instead run the package without a global install:

npx @punks/secrets --help

Quick start

Authenticate and confirm the active identity:

secrets login
secrets whoami

The resource hierarchy is:

project
└── environment
    └── dotenv file
        └── values

Create one of each resource, send a value through stdin, then pull the rendered file:

secrets projects create payments
secrets envs create production --project payments
secrets files create .env.production --env production --project payments
printf '%s' "$API_TOKEN" | secrets values put .env.production API_TOKEN \
  --stdin --env production --project payments
secrets files pull .env.production --env production --project payments

Project and environment slugs default to kebab-case versions of their names. A file name defaults to the basename of its path.

Authentication

secrets login opens the device-approval flow and stores the resulting CLI token. Confirm that the browser code matches the terminal code before approving. If the stored token is already valid, login prints the current identity; run secrets logout first to switch accounts.

secrets login
secrets whoami
secrets logout

Expired or rejected credentials fail with guidance to log in again. Missing authentication is also a command failure and exits 1.

Selecting resources

• Projects accept an ID or slug. --project wins when supplied; otherwise the CLI infers a slug from the default Git remote repository name, then the current directory name.
• Environments accept an ID or slug within the selected project.
• File IDs work directly. File names and paths require --env; resolution prefers exact ID, exact path, then one unique exact name.
• Pass explicit selectors whenever repository or directory inference could identify the wrong project.

Command reference

The installed version's leaf help is authoritative: run secrets <group> <command> --help for flag descriptions.

Projects

secrets projects list
secrets projects create NAME [--slug SLUG]
secrets projects update [PROJECT] [--project PROJECT] [--name NAME] [--slug SLUG]
secrets projects delete [PROJECT] [--project PROJECT]

Create derives the slug when --slug is omitted. Update requires --name or --slug. Update and delete accept either positional PROJECT or --project, never both.

Project users

secrets projects users list [PROJECT] [--project PROJECT]
secrets projects users add EMAIL [--project PROJECT]
secrets projects users remove USER_ID_OR_EMAIL [--project PROJECT]

Membership is binary; there is no per-project role flag. The user behind EMAIL must sign in once before an admin can add them. Removal accepts a user ID or exact email.

Environments

secrets envs list [PROJECT] [--project PROJECT]
secrets envs create NAME [--slug SLUG] [--project PROJECT]
secrets envs update ENVIRONMENT [--name NAME] [--slug SLUG] [--project PROJECT]
secrets envs delete ENVIRONMENT [--project PROJECT]
secrets envs pull ENVIRONMENT [--project PROJECT]

Create derives the slug when --slug is omitted. Update requires --name or --slug.

Files

secrets files list ENVIRONMENT [--project PROJECT]
secrets files create PATH --env ENVIRONMENT [--name NAME] [--project PROJECT]
secrets files update FILE [--env ENVIRONMENT] [--name NAME] [--path PATH] [--project PROJECT]
secrets files delete FILE [--env ENVIRONMENT] [--project PROJECT]
secrets files pull FILE [--env ENVIRONMENT] [--project PROJECT]

Files are dotenv files. Create requires --env; update requires --name or --path. Human-readable file selectors require --env.

Values

secrets values list FILE [--env ENVIRONMENT] [--project PROJECT]
secrets values get FILE KEY [--env ENVIRONMENT] [--project PROJECT]
secrets values put FILE KEY [VALUE] [--stdin] [--env ENVIRONMENT] [--project PROJECT]
secrets values set FILE KEY [VALUE] [--stdin] [--env ENVIRONMENT] [--project PROJECT]
secrets values update FILE KEY [VALUE] [--stdin] [--env ENVIRONMENT] [--project PROJECT]
secrets values delete FILE KEY [--env ENVIRONMENT] [--project PROJECT]
secrets values bulk-read FILE KEY... [--env ENVIRONMENT] [--project PROJECT]
secrets values bulk-upsert FILE [KEY=value...] [--stdin] [--env ENVIRONMENT] [--project PROJECT]
secrets values bulk-delete FILE KEY... [--env ENVIRONMENT] [--project PROJECT]

values is the preferred group. Every leaf is also available under secrets secrets for compatibility.

Single-value mutations accept exactly one source: positional VALUE or --stdin. Bulk upsert accepts KEY=value arguments or newline-delimited stdin, never both. Only the first = splits each bulk entry, so values may contain =.

Use stdin to keep values out of shell history:

printf '%s' "$API_TOKEN" | secrets values put .env.production API_TOKEN \
  --stdin --env production --project payments

secrets values bulk-upsert .env.production --stdin \
  --env production --project payments < values.env

Lists, bulk reads, mutation summaries, and pull summaries expose key names, not values. values get deliberately writes one raw value; redirect or capture it directly and never include it in logs, screenshots, diffs, or agent output.

secrets values get FILE_ID API_TOKEN > /secure/destination

Pull behavior

Pull overwrites; it does not merge. envs pull writes every file in an environment, while files pull writes one. Paths are relative to the current directory, missing parent directories are created, and existing files are replaced.

Interactive terminals show the path and key-name plan and default to approval. Declining writes nothing and exits successfully. Non-interactive execution auto-approves, so automation must validate paths and overwrite impact first. If a multi-file write fails, earlier files may already exist; verify every planned path without printing contents.

Authorization

• Global admins manage projects, membership, and every project resource.
• Project members operate environments, files, and values only inside their memberships.
• Forbidden is deterministic: verify secrets whoami, global role, membership, and selected scope; do not retry unchanged.

Destructive cleanup

Delete commands do not ask for confirmation. Inspect exact targets first and clean up leaf-to-root:

secrets values list FILE --env ENVIRONMENT --project PROJECT
secrets values bulk-delete FILE KEY... --env ENVIRONMENT --project PROJECT
secrets files delete FILE --env ENVIRONMENT --project PROJECT
secrets envs delete ENVIRONMENT --project PROJECT
secrets projects users list PROJECT
secrets projects users remove USER_ID_OR_EMAIL --project PROJECT
secrets projects delete PROJECT

Remove the operating identity last, if at all. The CLI has no restore command; do not promise CLI recovery after deletion.

Automation and shell integration

Exit statuses:

• 0: completed, including empty results, no-op mutations, and a declined pull.
• 1: input, selector, authentication, authorization, conflict, validation, rate-limit, unavailable-backend, or other command failure.
• 130: interactive pull interrupted with Ctrl-C.

Generate shell completions:

eval "$(secrets --completions zsh)"
secrets --completions bash > secrets.bash

Global utilities are --help/-h, --version/-v, --completions bash|zsh|fish|sh, and --log-level all|trace|debug|info|warn|warning|error|fatal|none. Put log level before the command:

secrets --log-level debug files list production

Failure recovery

• Project not found: pass the intended project ID or slug explicitly and check inference.
• Environment not found: list environments in the selected project.
• File not found: add --env for a name/path selector or use the file ID.
• Multiple files have that name: use an exact path or file ID.
• No account exists for that email: ask the person to run secrets login, then add them again.
• Conflict: relist the resource before retrying.
• Rate limited: wait, then retry once.
• Backend unavailable: preserve inputs and retry later.

Error reports should contain placeholders and fixed safe error text, never secret-bearing arguments, tokens, or backend payloads.

Standalone executables

GitHub Releases provide separate self-contained executables for supported macOS, Linux, and Windows targets. They embed Bun's runtime, so no separate Node.js or Bun installation is required. Verify the downloaded file against the release's SHA256SUMS before running it.

This package is currently distributed as UNLICENSED while the project owner selects its permanent license.