From 794e044d04c2438f9590c685c7e3d4256182d12d Mon Sep 17 00:00:00 2001 From: Ari Mayer Date: Thu, 2 Jul 2026 00:17:41 -0400 Subject: [PATCH] docs: surface pass-cli's AI-agent integration across README and docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The AI-agent capabilities (env injection via exec/export/inject, the background agent, and the new `skills` command) were real but buried in docs/05-operations — the README never mentioned AI agents at all, and the docs landing page had no entry. A human or research-agent evaluating pass-cli as "a password manager my AI agent can use safely" couldn't tell it fit. Make it discoverable without rebranding — the command-line 1Password/Bitwarden identity stays primary; agent-readiness is surfaced as a differentiator: - New front-door guide docs/02-guides/ai-agents.md: the safety model plus exec/export/inject, the background agent (POSIX-only), and `skills`. - README: an "AI Agent Ready" feature bullet, a scannable "AI Agent Integration" section (research agents read the raw README directly), and a Documentation link. - Docs landing + Guides grid: Quick Links / Features / card entries. - Scripting Guide: a reciprocal pointer to the agent guide. All copy grounded in shipped behavior; cross-links use the existing ../section/page pattern (reference docs in 05-operations left in place). Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_014kVLjbUL4F4CkoA7RbMYy8 --- README.md | 26 ++++++ docs/02-guides/_index.md | 1 + docs/02-guides/ai-agents.md | 128 ++++++++++++++++++++++++++++++ docs/02-guides/scripting-guide.md | 2 + docs/_index.md | 2 + 5 files changed, 159 insertions(+) create mode 100644 docs/02-guides/ai-agents.md diff --git a/README.md b/README.md index fca9ce6a..31026616 100644 --- a/README.md +++ b/README.md @@ -24,6 +24,7 @@ Pass-CLI is a fast, secure password and API key manager that stores credentials - **Health Checks**: Built-in `doctor` command for vault verification and troubleshooting - **Cross-Platform**: Single binary for Windows, macOS (Intel/ARM), and Linux (amd64/arm64) - **Script-Friendly**: Clean output modes (`--quiet`, `--field`, `--masked`) for shell integration +- **AI Agent Ready**: Purpose-built for AI coding agents — inject secrets into a command's environment with `exec` so they never reach the chat transcript, logs, or files; plus a background agent for promptless access and self-served, version-matched agent skills (`pass-cli skills`) - **Usage Tracking**: Automatic tracking of where credentials are used across projects - **Local-First**: Works offline by default, optional cloud sync via rclone - **Cloud Sync**: Sync vault across devices with rclone (Google Drive, Dropbox, OneDrive, S3, etc.) @@ -161,6 +162,30 @@ pass-cli doctor For complete command reference, flags, and examples, see [docs/03-reference/command-reference.md](docs/03-reference/command-reference.md). +## AI Agent Integration + +Pass-CLI is built to be driven safely by **AI coding agents** (Claude Code, Cursor, Codex, and similar) — not just humans at a keyboard. An agent can use your real credentials to run real commands **without the secret ever landing in the chat transcript, a log, or a file the agent's harness watches** — the leak path that plagues copy-pasting or `echo`-ing secrets. + +```bash +# Hand a secret to a command — injected into the child's environment only, +# never on stdout, the clipboard, or shell history +pass-cli exec --set GITHUB_TOKEN=github -- gh repo list + +# Materialize a composite secret (a config file or connection string) +echo 'postgres://app:${pass:db/password}@localhost/app' | pass-cli inject + +# Unlock once, then resolve promptlessly for the rest of the session (POSIX) +pass-cli agent start + +# The CLI serves its own version-matched agent guide — agents read this first +pass-cli skills get core +pass-cli skills install # drop a discovery stub into ~/.claude/skills or ~/.agents/skills +``` + +The agent story combines **env injection** (`exec` / `export` / `inject`, with `base64`/`basicauth` value filters), an optional **background agent** that holds the unlocked vault for promptless access, and a **`skills`** command that ships the agent usage guide *inside the binary* so the guidance never drifts from the installed version. + +For the full workflow and the safety model, see the [AI Agent Integration guide](docs/02-guides/ai-agents.md). + ## Security **Encryption**: @@ -205,6 +230,7 @@ For complete security details, best practices, and migration guides, see [docs/0 **Essential Guides**: - [Getting Started](docs/01-getting-started/quick-start.md) - First-time setup and basic workflows - [Usage Guide](docs/03-reference/command-reference.md) - Complete command reference, TUI shortcuts, configuration +- [AI Agent Integration](docs/02-guides/ai-agents.md) - Let AI coding agents use your credentials safely (env injection, background agent, `skills`) - [Installation](docs/01-getting-started/quick-install.md) - All installation methods and package managers - [Recovery Phrase](docs/02-guides/recovery-phrase.md) - BIP39 recovery phrase setup and vault recovery - [Security](docs/03-reference/security-architecture.md) - Encryption details, best practices, migration guides diff --git a/docs/02-guides/_index.md b/docs/02-guides/_index.md index 44aa6c30..f47d75b7 100644 --- a/docs/02-guides/_index.md +++ b/docs/02-guides/_index.md @@ -7,6 +7,7 @@ Task-oriented guides for common pass-cli workflows and features. {{< cards >}} {{< card link="basic-workflows" title="Basic Workflows" icon="cursor-click" subtitle="Daily operations - list, update, delete, generate credentials" >}} + {{< card link="ai-agents" title="AI Agent Integration" icon="sparkles" subtitle="Let AI coding agents use your credentials without leaking them" >}} {{< card link="recovery-phrase" title="Recovery Phrase" icon="shield-check" subtitle="BIP39 recovery phrase setup and vault recovery" >}} {{< card link="keychain-setup" title="Keychain Setup" icon="key" subtitle="Configure OS keychain integration for password storage" >}} {{< card link="usage-tracking" title="Usage Tracking" icon="chart-bar" subtitle="Automatic credential usage tracking by working directory" >}} diff --git a/docs/02-guides/ai-agents.md b/docs/02-guides/ai-agents.md new file mode 100644 index 00000000..038b7f4e --- /dev/null +++ b/docs/02-guides/ai-agents.md @@ -0,0 +1,128 @@ +--- +title: "AI Agent Integration" +weight: 6 +toc: true +--- + +pass-cli is built to be driven safely by **AI coding agents** (Claude Code, +Cursor, Codex, Continue, and similar) — not just humans at a keyboard. An agent +can use your real credentials to run real commands **without the secret ever +landing in the chat transcript, a log, CI output, or a file the agent's harness +watches**. + +This is the differentiator: most ways of handing a secret to an agent — pasting +it, `echo`-ing it, capturing it into a shell variable — leak it into the +conversation log the moment they happen. pass-cli exists to move a secret from +your encrypted vault into the process that needs it through a channel the +transcript never sees. + +## The safety model + +> **Never let a secret value reach the transcript, a log, or a watched file.** +> Once a secret is in the conversation log on disk it is compromised and must be +> rotated. + +Everything below is a way to satisfy that rule. The default — `exec` — passes +the secret **only** through a child process's environment, so it never touches +stdout, the clipboard, or shell history. + +## Hand a secret to a command — `exec` + +The primary tool. Runs a command with credentials injected as environment +variables; pass-cli writes nothing of its own to stdout, and the child's exit +code is propagated unchanged. + +```bash +# Explicit mapping: ENV_NAME=service +pass-cli exec --set GITHUB_TOKEN=github -- gh repo list + +# Multiple credentials at once +pass-cli exec --set AWS_ACCESS_KEY_ID=aws-id --set AWS_SECRET_ACCESS_KEY=aws-secret -- aws s3 ls + +# Convenience form: derive the env name from the service (openai-api -> OPENAI_API) +pass-cli exec openai-api -- python train.py +``` + +`exec` is read-only: it records no usage and triggers no sync push, so it is safe +to call on a hot path. + +## Composite and derived secrets — `export` and `inject` + +- **`export`** prints shell statements to load credentials into the current + shell (`eval "$(pass-cli export --set GITHUB_TOKEN=github)"`). A weaker + boundary than `exec` — prefer `exec` when you only need to launch a command. +- **`inject`** renders a template, replacing `${pass:service/field}` references + with values — the tool for a config file or a connection string that *embeds* a + secret: + + ```bash + echo 'postgres://app:${pass:db/password}@localhost/app' | pass-cli inject + ``` + + References support value filters — `base64`, `base64url`, and `basicauth` + (`base64("user:pass")` for an HTTP `Authorization: Basic` header) — so an agent + never has to shell out to `base64` and risk the value on stdout: + + ```bash + echo 'Authorization: Basic ${pass:api | basicauth}' | pass-cli inject + ``` + +## Promptless access — the background agent + +For a session where an agent resolves many credentials, the optional background +agent unlocks the vault once and holds it in memory, so `exec`/`export`/`inject` +need **no master-password prompt and no key derivation** on each call: + +```bash +pass-cli agent start # unlock once, then background itself +pass-cli exec --set GITHUB_TOKEN=github -- gh repo list # resolves via the agent, no prompt +pass-cli agent stop # zero secrets and stop +``` + +It serves resolved field **values only** — the master password and derived key +never leave the agent process — and auto-locks after inactivity (`--idle`, +default 15m) and always after `--max-ttl` (default 8h). When no agent is running, +every command **transparently falls back** to opening the vault directly, so the +agent is a pure optimization, never a dependency. POSIX only for now; on Windows +commands fall back to direct-open. See the [Background Agent](../05-operations/agent) +reference for details. + +## Self-describing: `pass-cli skills` + +pass-cli ships an **agent usage guide inside the binary**, so an agent can load +version-matched guidance straight from the CLI — the instructions never drift +from the installed version: + +```bash +pass-cli skills get core # safe-usage guide: exec/export/inject/agent/list/get + leak traps +pass-cli skills get core --full # also include the full command reference +pass-cli skills list # list every skill shipped with this version +``` + +To make an agent discover pass-cli automatically, install a small discovery stub +into its skills directory: + +```bash +pass-cli skills install # auto-detects ~/.claude/skills or ~/.agents/skills +``` + +The stub is intentionally thin — it points the agent at `pass-cli skills get +core`, and the real, version-matched guidance stays in the binary. See +[AI Agent Skills](../05-operations/agent-skills) for the full command. + +## Quickstart for agents + +An agent working on a user's machine can bootstrap in three commands: + +```bash +pass-cli skills get core # learn the safe-usage rules +pass-cli list -q # discover available service names (no secrets) +pass-cli exec --set API_KEY=some-service -- # run a command with the secret injected +``` + +## Learn more + +- [Command Reference](../03-reference/command-reference) — every command and flag +- [Background Agent](../05-operations/agent) — the promptless daemon in depth +- [AI Agent Skills](../05-operations/agent-skills) — the `skills` command +- [Scripting Guide](scripting-guide) — non-agent automation and output modes diff --git a/docs/02-guides/scripting-guide.md b/docs/02-guides/scripting-guide.md index 54673f62..b3d4a60a 100644 --- a/docs/02-guides/scripting-guide.md +++ b/docs/02-guides/scripting-guide.md @@ -6,6 +6,8 @@ toc: true Automate pass-cli with scripts using quiet mode, JSON output, and environment variable integration. +> **Using an AI coding agent?** See the [AI Agent Integration](ai-agents) guide for the safe way to hand secrets to agents — injected into a command's environment, never through the chat transcript. + ## Output Modes Pass-CLI supports multiple output modes for different use cases. diff --git a/docs/_index.md b/docs/_index.md index 781f2b41..38b21e3e 100644 --- a/docs/_index.md +++ b/docs/_index.md @@ -17,6 +17,7 @@ Welcome to the **pass-cli** documentation. A secure, cross-platform, always-free - [Quick Start](01-getting-started/quick-start) - First-time setup and initialization (5 minutes) - [Quick Install](01-getting-started/quick-install) - Installation instructions for all platforms - [Command Reference](03-reference/command-reference) - Complete command reference +- [AI Agent Integration](02-guides/ai-agents) - Let AI coding agents use your credentials safely - [Recovery Phrase](02-guides/recovery-phrase) - BIP39 recovery phrase setup and usage - [Backup & Restore Guide](02-guides/backup-restore) - Manual vault backup management - [TOTP & 2FA Support](02-guides/totp-guide) - Store and generate 2FA codes @@ -30,6 +31,7 @@ Welcome to the **pass-cli** documentation. A secure, cross-platform, always-free - **Cross-Platform**: Works on Windows, macOS, and Linux - **Keychain Integration**: Optional OS keychain support for automatic unlocking - **Interactive TUI**: Beautiful terminal UI built with tview +- **AI Agent Ready**: Hand secrets to AI coding agents via env injection — never through the chat transcript - **Clipboard Support**: Secure clipboard integration with auto-clear - **Usage Tracking**: Per-credential usage statistics - **Audit Logging**: HMAC-signed audit logs for all operations