Use the CLI-tools-only secret store correctly, with one source of truth for
reusable credentials used by CLI tools and CLI-tool agents.
The canonical helper is:
<cli-tools-root>/_repo/_secret-manager/secrets.sh
It is backed by the macOS Keychain service namespace cli-tools.
The default Keychain file is
~/.local/share/cli-tools/cli-tools.keychain-db, alongside the CLI-tools user
profile directories.
For full lifecycle policy, read
<cli-tools-root>/_repo/skills/cli-tool/references/secrets.md.
If the task is broader CLI creation, update, testing, or auth implementation,
also load the repo-owned cli-tool skill and follow its agent-routing rules.
</source_of_truth>
Use this store only for reusable human-supplied credentials that belong to CLI
tools under `` and must survive sessions:
API keys, usernames, passwords, client secrets, personal access tokens, and
other long-lived raw credentials.
Do not use it for CourseCraft, generic project automation, non-CLI
workflows, or service runtime state owned by a CLI's auth system.
1. Choose the CLI tool name and the secret type. The canonical naming schema is `-`, where both parts are lowercase hyphenated strings and `` is the CLI command name.
2. Check for an existing name before asking Adam for a credential:
```bash
/_repo/_secret-manager/secrets.sh list
/_repo/_secret-manager/secrets.sh has
```
When a missing secret is an expected diagnostic result, shape `has` so the
non-zero status is consumed and reported explicitly:
```bash
if output="$(/_repo/_secret-manager/secrets.sh has 2>&1)"; then
printf 'SECRET_PRESENT:%s\n' ''
else
rc=$?
if [ "$rc" -eq 1 ]; then
printf 'EXPECTED_MISSING_SECRET:%s\n' ''
exit 0
fi
printf '%s\n' "$output" >&2
exit "$rc"
fi
```
3. If the secret exists, retrieve it with `get ` and use it without
printing the value.
4. Ask Adam only for missing reusable credentials.
5. Store new values immediately through stdin or `SECRET_VALUE`, not inline in
command examples or `.env` files:
```bash
printf '%s' "$SECRET_VALUE" | /_repo/_secret-manager/secrets.sh set --tool --type
SECRET_VALUE="$SECRET_VALUE" /_repo/_secret-manager/secrets.sh set --tool --type
```
6. Verify storage with `has `. Do not verify by echoing the secret value.
</quick_start>
```bash
/_repo/_secret-manager/secrets.sh set --tool --type [value]
/_repo/_secret-manager/secrets.sh set [value]
/_repo/_secret-manager/secrets.sh rename --tool --type
/_repo/_secret-manager/secrets.sh get
/_repo/_secret-manager/secrets.sh has
/_repo/_secret-manager/secrets.sh delete
/_repo/_secret-manager/secrets.sh list
```
Remote host form:
<cli-tools-root>/_repo/_secret-manager/secrets.sh --remote-host <host> <command> [args]
For set, prefer stdin or SECRET_VALUE so the secret does not appear in shell
history. Remote set copies the value through a private temporary file on the
remote host.
- Secret manager: reusable raw credentials that an agent or script needs before
or during a CLI auth flow.
- CLI auth profiles: runtime tokens, browser session state, profile metadata,
and auth-tied cache under
`~/.local/share/cli-tools//authentication_profiles//`.
- Tool root `.env` files under `~/.local/share/cli-tools//`: non-secret
configuration only.
Never store or document reusable credentials in repo-local .env files,
profile .env files, .env.example, source files, final answers, screenshots,
logs, or general instructions.
- Reuse existing secret names. Run `list` before inventing a new name.
- The canonical naming schema is `-`.
- New human-entered secrets must be created with `set --tool --type
` so the helper constructs `-`.
- Use `rename --tool --type ` when moving old
names into the canonical schema.
- Never print secret values. If a command returns a value, pipe it directly into
the consuming command or store it in a local shell variable that is not echoed.
- If macOS prompts for Keychain access, ask Adam to click Allow. Do not route
around the Keychain prompt.
- A missing secret is not a reason to use LastPass or `.env`; ask Adam for that
specific missing value and store it here.
</operational_notes>
- The needed CLI-tool credential names were checked with `list` or `has`.
- Existing credentials were retrieved without exposing their values.
- Missing reusable credentials were stored with `set` through stdin or
`SECRET_VALUE`.
- CLI runtime state was left to the CLI's normal auth/profile system.
- No reusable CLI-tool credential was placed in `.env`, docs, source, logs, or
the final answer.
</success_criteria>