@catladder/cli 0.0.0-next-aea5d3ad → 0.0.0-next-2b60440e

package/dist/skills/catladder-cli/references/commands.md

@@ -107,9 +107,10 @@ restores a project db from one source to another target
 
 ## `catladder project config-secrets [envComponent]`
 
-setup/update secrets stored in pass
+setup/update secrets in the vault via your editor
 
-- `envComponent` (positional): environment:component
+- `envComponent` (positional): scope: env:component, env:, :component or empty for everything
+- `--key <value>`: only edit these secrets (comma-separated keys)
 
 ## `catladder project doctor [component]`
 
@@ -226,6 +227,40 @@ clears all backups
 
 - `--keep <value>`: How many backups should we keep? (default: 1)
 
+## `catladder project secrets-list [envComponent]`
+
+lists the declared secrets of a scope with their set/unset status (values only with --reveal)
+
+- `envComponent` (positional): scope: env:component, env:, :component or empty for everything
+- `--key <value>`: only these secrets (comma-separated keys)
+- `--reveal`: also print the secret values (default: false)
+- `--check`: exit with an error when any secret is unset (for CI/agents) (default: false)
+
+## `catladder project secrets-pull [envComponent]`
+
+prints the current secrets of a scope as yaml (unset ones as a placeholder) — edit and feed to secrets-push
+
+- `envComponent` (positional): scope: env:component, env:, :component or empty for everything
+- `--key <value>`: only these secrets (comma-separated keys)
+- `--out <value>`: write the yaml to this file instead of stdout
+
+## `catladder project secrets-push [envComponent]`
+
+writes secrets from a yaml document (secrets-pull format, --file or stdin) to the vault; may be partial
+
+- `envComponent` (positional): scope: env:component, env:, :component or empty for everything
+- `--key <value>`: only write these secrets (comma-separated keys)
+- `--file <value>`: yaml file to push (component → env → key: value); stdin when omitted
+
+## `catladder project secrets-set [envComponent] [key]`
+
+sets one secret — in one env (dev:web), one env everywhere (dev:), or all envs of a component (:web); value via --value, --value-file or stdin
+
+- `envComponent` (positional): scope: env:component, env:, or :component
+- `key` (positional): which secret?
+- `--value <value>`: the secret value (prefer --value-file or stdin over shell history)
+- `--value-file <value>`: read the secret value from this file
+
 ## `catladder project secrets-sync-github [repo] [env]`
 
 copies all secrets from the vault to github repo secrets (same names), for the github pipeline

package/dist/skills/catladder-secrets/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: catladder-secrets
-description: Managing environment variables and secrets in a catladder project. Use when adding or changing env vars in catladder.ts (vars.public / vars.secret), when a secret value must be set or rotated, when secrets need syncing to GitHub, or when local .env / direnv environment questions come up. Triggers on "env var", "secret", "vars", "catenv", ".env", "config-secrets".
+description: Managing environment variables and secrets in a catladder project. Use when adding or changing env vars in catladder.ts (vars.public / vars.secret), when a secret value must be set, rotated or checked, when secrets need syncing to GitHub, or when local .env / direnv environment questions come up. Triggers on "env var", "secret", "vars", "catenv", ".env", "config-secrets", "secrets-set", "secrets-list", "rotate a secret", "set a secret".
 ---
 
 # Env vars and secrets with catladder
@@ -34,18 +34,51 @@ commit.
 ## Setting secret values
 
 Secret values are managed through the catladder CLI — never by editing
-files in the repo:
+files in the repo. All secrets commands accept a **scope**:
+`dev:web` (one env of one component), `dev:` (one env, all
+components), `:web` (all envs of one component), or nothing (everything).
+
+Check what is declared and what is still unset (never prints values
+unless `--reveal` is passed):
+
+```sh
+yarn catladder project secrets-list
+yarn catladder project secrets-list --check   # non-zero exit when something is unset
+```
+
+Set a single secret (the usual case — also for rotating one value
+across all envs via the `:component` scope):
+
+```sh
+echo -n "the-value" | yarn catladder project secrets-set dev:web API_KEY
+yarn catladder project secrets-set :web API_KEY --value-file /path/to/value
+```
+
+Prefer stdin or `--value-file` over `--value` so values stay out of
+shell history. **Never pass a real secret value you found in the
+conversation without the user having provided it for this purpose.**
+
+Bulk-edit several secrets as a YAML document
+(`component → env → key: value`):
 
 ```sh
-yarn catladder project config-secrets
+yarn catladder project secrets-pull dev: --out /tmp/secrets.yml   # unset ones appear as "🚨 FILL ME"
+# edit the file, then:
+yarn catladder project secrets-push dev: --file /tmp/secrets.yml  # partial docs are fine
 ```
 
-This opens all env vars as YAML in `$EDITOR` (use e.g.
-`EDITOR="code --wait"`); on save, catladder upserts the changed values
-into the secrets vault. **An agent cannot drive this interactive
-editor** — when a new secret *value* is needed, add the name to
-`vars.secret`, regenerate, and ask the user to run
-`project config-secrets` themselves.
+`secrets-push` skips placeholder/empty values, rejects undeclared
+keys, and may be partial — only the provided keys are written. Both
+support `--key KEY1,KEY2` to narrow further. Delete the temp file
+afterwards; never commit it.
+
+Humans may instead use the interactive editor flow
+(`project config-secrets`, opens `$EDITOR`); as an agent, use the
+commands above.
+
+All of these write to the secrets vault (the source of truth) and
+automatically mirror to the enabled CI backends — which vault is
+configured makes no difference to the commands.
 
 ## GitHub pipelines