secret-cli

name	secret-cli
description	Use the global `secret` command for scoped Bitwarden access: auth status, alias listing, exact value reads, hidden vault writes, and project dotenv generation. Use for credentials, API keys, or `.env` files in any repository.

secret CLI

The global secret command wraps the official Bitwarden CLI (bw) with config-driven, scoped access. It never enumerates the vault, never prints values unless explicitly requested, and never stores BW_SESSION.

Commands

• secret status — auth state plus the exact next command; --check exits nonzero when not unlocked.
• secret unlock — unlock and print a session token; --store persists it (macOS login keychain, plaintext file fallback elsewhere); the shell function exports BW_SESSION for the current shell.
• secret lock — lock the vault and clear any stored session.
• secret list — configured aliases from merged configs; aligned table on a TTY with creation dates when unlocked, TSV when piped; never touches the vault when piped.
• secret search <term> — find aliases by alias, item, or env key across scopes; no values, no vault access.
• secret get <alias> — print one configured value (or --copy to the clipboard), only when a value is explicitly required.
• secret set <alias> — hidden prompt, then write the value; --generate creates a random password; --name, --source, --tags, --type, and --field set item metadata; confirm or --force before overwriting.
• secret edit <alias> — update the Bitwarden item name, value, field, source, notes, custom fields, or local alias tags; --tags '' clears tags and --force skips overwrite confirmation.
• secret source <alias> [url] — print or update the source URL attached to an item.
• secret id <alias> — print the resolved Bitwarden item id without the value; use ids in configs when names can collide.
• secret pin <alias> — replace the item name with the resolved id in the project/local/user config that owns it.
• secret rotate <alias> — generate a new password and overwrite the item; confirm unless --force/-f; delivers the new value (clipboard, stdout fallback).
• secret rm <alias> — delete the vault item; confirm unless --force/-f; the config entry stays.
• secret unset <alias> — remove an alias from the project/local/user config that owns it.
• secret mv <alias> <new> — rename an alias in the project/user config, base and env overrides.
• secret totp <alias> — current 2FA code (--copy to the clipboard).
• secret pull — refresh the local vault cache from the server explicitly; never automatic (sync/sy still work).
• secret init [alias...] — scaffold a project .secret.json (directory name + kebab alias as item prefix); pass aliases to prefill; refuses to overwrite without --force.
• secret print [project|global|nix] — show every alias in one scope (alias, env, item, field, dotenv key); --all merges scopes with a scope column; never values, no vault access.
• secret env --output .env — generate a project dotenv atomically with mode 0600; --export prints export KEY='value' lines, --diff dry-runs without writing.
• secret run -- <cmd> — inject project aliases into a command's environment and run it, propagating its exit code; strict by default (any unresolvable alias aborts), --optional A,B opts out.
• secret lint — validate configs offline (items, env keys, dotenv-key collisions); no vault access, works locked; --json supported.
• secret doctor — validate configs, Bitwarden state, and alias resolvability without printing values.
• secret doctor --json — emit value-free per-alias diagnostics and remote metadata for machine consumers such as SecretBar.
• secret recent / secret history — recently used aliases and recent commands from a value-free local log.
• secret prune [--dry-run] — list or remove configured aliases whose remote items no longer exist.

Every command has a short alias (st, ls, g, s, i, t, sy, p, r, in, e, pr, d, re, h); secret g github-token equals secret get github-token. secret list --json and secret print --json emit machine-readable rows on stdout for scripts.

secret lint runs before secret doctor in a workflow: lint is offline and CI-friendly, doctor needs an unlocked vault. Use secret lint --json in pre-commit checks.

Config

• ~/.config/secret/config.json — personal global aliases (optional).
• ./.secret.json — project aliases (discovered from the current directory upward); commit it because it is value-free.
• ./.secret.local.json — machine-local overrides, gitignored, merged last.
• "environments" in any config — per-env overrides selected with --env (default prod).

Precedence: user, then project, then local. The nixfiles repo itself declares its machine-wide aliases in its root .secret.json; a project adds aliases with its own .secret.json and local overrides with a gitignored .secret.local.json.

Common flows: secret env --env dev --output .env.dev for a per-env dotenv, and secret env --required A,B --output .env to fail fast when a required alias is missing from the project config.

For item modeling, use type: "login" for one-line credentials such as passwords, API keys, tokens, and usernames. Use type: "secure-note" with field: "notes" for multiline sensitive material such as SSH keys, recovery codes, certificates, or private documents. Login notes are optional item metadata; Secure Note notes are the encrypted secret value. custom:<name> is for a named Bitwarden custom field, not a replacement for the main value. Tags are value-free local labels used for filtering and organization; they are not Bitwarden item fields.

SecretBar is the native macOS menu-bar client. It hides aliases whose remote items are missing, copies through the CLI clipboard path, supports Login and Secure Note creation/editing, tag autocomplete, source/TOTP actions, expiry health, pinned/recent filters, and keyboard-first navigation. Copy is the default one-click action; rotation and destructive actions remain confirmed. Its UI must never print or retain secret values except for an explicit, hold-to-reveal interaction.

zsh and bash complete command words and then aliases for get/set/edit/source/id/totp/pin/rotate/rm lazily with a shared 60-second cache; neither runs at shell startup.

Safety

• Never print, log, or commit secret values or BW_SESSION.
• Treat the stored session (keychain or file) like a credential; secret lock clears it.
• Pass values to set only via the hidden prompt, stdin, or --generate; never as an argument.
• Overwriting an existing item always confirms first unless --force/-f is passed.
• Prefer Bitwarden item IDs over names in configs when names can collide.
• When a task needs an app's secrets, generate its .env with secret env --output .env and keep .env gitignored.