/skills-keys

name: skills-keys
description: "Manage API keys for the runner's --execute layer. CRUD on ~/.skills.env (chmod 600): list / add / update / remove / verify / export. Covers OpenAI, Gemini, BFL, FAL, Replicate, Runway, Kling, Suno, Eleven, Ideogram, Anthropic, S3. Use when: 'add my OpenAI key', 'rotate the Suno key', 'which keys are set', 'verify my key works'."

license: MIT
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Grep
  - Glob

<objective> Provide a thin CLI on top of `~/.skills.env` (the runner's key store) so users can manage keys WITHOUT editing dotfiles by hand. Values are stored plaintext but chmod 600. Each runner reads the file at startup, merging entries into `os.environ` without overriding explicit shell exports.

This skill does NOT:

• Store keys in macOS Keychain / Linux Secret Service (cross-platform parity matters more than OS-native vault for v1).
• Encrypt the file at rest (chmod 600 is the v1 posture).
• Manage non-runner keys (database creds, SSH keys, etc.).
• Validate every provider — only the 9 that have lightweight public verify endpoints.

Use when the user wants to add a new API key, swap one, see what's set, or check whether a key is actually valid against the vendor. </objective>

ROLE

Read the user's intent (add/update/remove/list/verify/enable/disable/path/export) → call the matching `common/runners/cli/keys.py` subcommand → relay the result. Mask values when displaying. Prompt for value silently if not provided on the command line. Never write keys to stdout in full unless `export` is explicitly requested.

PIPELINE

1. **Parse intent**: which subcommand and which arg(s). 2. **Run** `python3 scripts/run.py <subcommand> [args]`. 3. **Relay the output** — already masked / colorized by the CLI. 4. **Optional follow-up**: if user added a new key, suggest running `skills-keys verify <KEY>` to confirm it works.

MODES

Inspection

• `skills-keys list` — show all keys with masked values + gate-flag indicator
• `skills-keys path` — print the keys-file path (default `~/.skills.env`; override via `SKILLS_KEYS_FILE` env var)
• `skills-keys verify` — ping every supported provider's endpoint, report valid/invalid/unknown/unsupported per key
• `skills-keys verify OPENAI_API_KEY GEMINI_API_KEY` — verify specific keys only

Mutation

• `skills-keys add OPENAI_API_KEY sk-proj-...` — add or update
• `skills-keys add OPENAI_API_KEY` — interactive (silent stdin read; not echoed)
• `skills-keys update OPENAI_API_KEY sk-new-...` — alias for `add`
• `skills-keys remove OPENAI_API_KEY` — delete the entry

Gate flags

Three keys are NOT API tokens but on/off gates for paid premium endpoints:

• `OPENAI_SORA_API_ENABLED` — required to call Sora 2 (anti-accidental-spend gate)
• `LYRIA_API_ENABLED` — required to call Lyria 3 Pro
• `SUNO_API_ENABLED` — required to call Suno

Shortcut commands:

• `skills-keys enable SUNO_API_ENABLED` — equivalent to `add SUNO_API_ENABLED 1`
• `skills-keys disable SUNO_API_ENABLED` — equivalent to `remove SUNO_API_ENABLED`

Export

• `skills-keys export` — print eval-ready lines:

  export OPENAI_API_KEY="sk-..."
  export GEMINI_API_KEY="..."

Use to apply file changes to the CURRENT shell: `eval "$(skills-keys export)"`. Plaintext output — only pipe to eval, don't share.

• `skills-keys export --mask` — same shape but values masked, for inspection.

REFERENCES (load on demand)

| File | When to load | |---|---| | [references/usage.md](references/usage.md) | Detailed UX reference — what each subcommand prints, exit codes, interactive prompts, file format, precedence rules |

EXAMPLES

See [examples/before-after.md](examples/before-after.md) — 4 example sessions covering: first-time setup of OpenAI + Gemini, rotating a leaked Suno key, verifying a freshly-pasted key, enabling Lyria gate.

CONSTRAINTS

• **Values are masked in every output EXCEPT `export` without `--mask`.** Logs / list / add confirmation print `sk-pr…WXYZ` style only.
• **The file is chmod 600.** Skill enforces after every write.
• **Explicit shell exports win.** If the user has `export OPENAI_API_KEY=...` in their `.zshrc`, the file entry is ignored — by design.
• **Interactive `add` reads via `getpass`** — value not echoed to terminal or shell history.
• **Don't print full key in error messages.** Errors reference env var NAMES, not values.
• **`verify` uses lightweight HTTP probes** — costs $0, no generation. Only 9 providers covered (OpenAI, Gemini, Anthropic, BFL, Ideogram, Replicate, FAL, Runway, ElevenLabs). Suno / Kling / Lyria gate flags / S3 / SKILLS_* don't have verify — they show `unsupported`.
• **Network errors in verify** show as `unknown` — not a key problem.
• **Don't auto-purge invalid keys.** If verify reports invalid, the skill flags it but doesn't delete — the user might have just rotated the key in the vendor dashboard.
• **gate flags are NOT API keys.** Use `enable / disable` for them, not `add / remove`. The skill warns when you try to misuse.
• **`~/.skills.env` location is overrideable** via `SKILLS_KEYS_FILE=/custom/path`. Useful for CI (where home dir might be ephemeral) or multi-profile setups.
• **Never commit `~/.skills.env` to git.** The home-dir location avoids accidental commits. If someone wants the file elsewhere (project root), they MUST add it to `.gitignore`.
• **For CI / GitHub Actions: don't use this skill.** Use the platform's native secret management (`secrets.OPENAI_API_KEY`) which propagates to env vars. This skill is for local dev.

INVOCATION HINTS

When the user says any of:

• "add my <provider> key", "store my OpenAI key", "save the Gemini key"
• "rotate the <provider> key", "update / change / swap the X key"
• "remove / delete the X key", "I leaked my Suno key, take it out"
• "list keys", "what keys do I have set", "which providers are configured"
• "verify my <provider> key", "test the OpenAI key", "is my key still valid"
• "enable Suno", "turn on Lyria", "disable Sora