Appearance
pn 命令行参考
本文由
crates/passno-cli的 clap 定义自动生成,请勿手工修改。更新命令定义后请运行cargo run -p passno-cli --bin gen-pn-docs。
passno — open-source password manager for humans and AI agents
passno stores credentials locally in an encrypted, signed vault.
By default pn communicates with the local passnod daemon over a verified Unix socket so an unlocked session persists across commands. Pass --no-daemon to operate directly on $PASSNO_HOME in-process. Concealed secrets are hidden by default and only revealed on an interactive TTY.
全局选项
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
--json | 否 | — | Output machine-readable JSON with schema_version |
--password-stdin | 否 | — | Read master password from stdin (first line) for non-interactive use |
--vault-dir | 否 | — | Override $PASSNO_HOME directory path |
--no-daemon | 否 | — | Bypass passnod daemon and operate directly on local vault files |
固定退出码
| 退出码 | 含义 |
|---|---|
0 | 成功 |
1 | 一般错误 / 内部错误 |
2 | 用法或参数错误(含非终端缺少 --password-stdin) |
3 | 保险库已锁定 / 密码或 Secret Key 错误 / 缺少 Secret Key |
4 | 被拒绝 |
5 | 找不到条目/字段/设备,或同步完整性错误 |
6 | 审批超时或非交互待审批 |
7 | 守护进程或上游服务不可用 |
8 | 策略不允许(例如非交互终端执行 pn show --reveal 或审计完整性异常) |
子命令
pn init
Initialize a new encrypted vault and generate a Secret Key
text
Examples:
pn init
printf 'correct-horse-battery\n' | pn init --password-stdin --json
Output:
Displays the Secret Key (once) and Emergency Kit markdown.
Exit codes: 0 success, 1 weak/already initialized, 2 non-TTY without --password-stdin, 7 daemon unavailable.pn unlock
Unlock the vault session in passnod (master password or Touch ID / Apple Watch)
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
--secret-key | 否 | — | Explicit Secret Key (e.g. A3-...) instead of reading from SecretKeyStore; - reads it at a hidden prompt or from stdin (after the master password line) |
--biometrics | 否 | — | Unlock using platform biometrics (macOS Touch ID / Apple Watch) via passnod |
text
Examples:
pn unlock
pn unlock --biometrics
printf 'correct-horse-battery\n' | pn unlock --password-stdin --json
printf 'correct-horse-battery\n' | pn unlock --password-stdin --secret-key -
Owner access is per terminal session: unlocking (or Touch ID / the master password when the vault is already unlocked) authorizes this terminal only, for 10 idle minutes or 12 hours, until the vault locks. A session without a terminal (Claude Code's `!`, an AI agent's shell) asks the owner to confirm with Touch ID on the Mac; the prompt names the programs asking. Cancelling returns CliSessionRequired (exit 3).
Exit codes: 0 success, 2 usage error, 3 wrong credentials, master password required or session not authorized, 7 daemon unavailable.pn whoami
Show who this pn is acting as: the owner's session state, or the agent / service token identity
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
--agent | 否 | cli-agent | Enrolled agent name to verify together with PASSNO_AGENT_KEY |
text
Examples:
pn whoami
pn whoami --json
PASSNO_SERVICE_TOKEN=pnst_v1_... pn whoami --json
PASSNO_AGENT_KEY=... pn whoami --agent claude --json
Without PASSNO_SERVICE_TOKEN or PASSNO_AGENT_KEY it reports the owner side: whether the vault is initialized and locked, and whether this terminal session may run owner commands (checking counts as a use of that session). It never asks for a password or Touch ID. With a service token or agent key it reports that identity (verified by passnod), its accessible vaults and, for a token, its vault, read-only flag and expiry; the call is recorded in the agent audit log. No secrets are printed.
Exit codes: 0 success, 3 vault locked (agent key without a long grant), 4 unknown or revoked agent / token, 7 daemon unavailable.pn activity
Show and verify the background activity of every device (agents, service tokens, unlocks, locks)
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
--device | 否 | — | Only records of this device (name or id prefix) |
--agent | 否 | — | Only records about this agent (name, id, or service token id) |
--since | 否 | — | Only records newer than this duration (30m, 12h, 7d) |
--limit | 否 | 100 | Show at most this many records (newest first) |
pn activity verify
Verify every device's activity log (signatures, chains, gaps, rollback, removed devices)
text
Examples:
pn activity verify
pn activity verify --json
Exit codes: 0 every log verified, 3 vault locked or session not authorized, 7 daemon unavailable, 8 a device's log has a problem (listed per device).text
Examples:
pn activity
pn activity --since 7d --agent claude
pn activity --device 'MacBook Pro' --limit 20 --json
pn activity verify
pn activity verify --json
What is recorded: agent requests and where/how each was approved or denied (Mac app, Touch ID, iPhone Face ID, iPhone notification / Apple Watch, iPhone while the Mac was locked) with the chosen duration; grant use, revocation and expiry by disuse; service tokens issued, used and revoked; every device's unlocks (method), locks (reason), terminal-session grants, iPhone pairing and device enrollment or removal. Not recorded: you viewing, copying or editing items in the apps. Records are metadata only, never secret values.
Each device signs its own hash-chained log; logs travel encrypted with normal sync, so every device lists and verifies every device's records. `--since` takes a duration (30m, 12h, 7d). Records not yet synced are marked `local`.
Output (--json): {records: [...], verify: {ok, devices_checked, devices: [{device_id, device_name, ok, problems: [{kind, seq, detail}]}]}}.
Exit codes: 0 success (and, for `verify`, every device's log verified), 2 usage error, 3 vault locked or terminal session not authorized, 7 daemon unavailable, 8 `verify` found a problem (changed, missing, reordered or forged records, rollback, or records written by a removed device).pn activity verify
Verify every device's activity log (signatures, chains, gaps, rollback, removed devices)
text
Examples:
pn activity verify
pn activity verify --json
Exit codes: 0 every log verified, 3 vault locked or session not authorized, 7 daemon unavailable, 8 a device's log has a problem (listed per device).pn passwd
Change the master password (asks for the current one; owner only, never agents)
text
Examples:
pn passwd
printf 'current-master-password\nnew-master-password\n' | pn passwd --password-stdin --json
What changes: only the wrapping of your account keys. The Secret Key, the Emergency Kit, items, shares and agent setups stay the same. A signed record is added to the vault (nothing is overwritten), so other devices ask for the new password after they sync and refuse the old one; new devices join with the new one.
After the change: Touch ID keeps working (it is re-wrapped; if that fails it is turned off with a message). A paired iPhone must be paired again before it can unlock this Mac. Forgot the current password? Unlock with Touch ID in the passno app and change it there (Settings → Security), or see `pn reset --help`.
Input: on a terminal, hidden prompts (current, new, new again). Otherwise `--password-stdin` with two lines: current, then new. Refused when PASSNO_AGENT_KEY or PASSNO_SERVICE_TOKEN is set; not available over MCP.
Output (--json): { ok, changed, biometrics: refreshed|disabled|off, phone_needs_repair, other_devices }.
Exit codes: 0 changed, 1 new password too weak or storage error, 2 usage error (non-TTY without --password-stdin, new passwords differ, same as current), 3 wrong current password, changed on another device (PasswordChanged) or locked, 7 daemon unavailable, 8 refused for agents.pn reset
Forgot the master password: move this vault aside (nothing is deleted) to start over
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
--move-aside | 否 | — | Move the vault and this device's local state aside (the only mode; nothing is deleted) |
text
Examples:
pn reset --move-aside
pn reset --move-aside --json
passno has no server and cannot recover a master password. Before starting over: if Touch ID still unlocks passno on this Mac, or Face ID on your iPhone, unlock there and change the password instead (`pn passwd`, or Settings → Security in the app).
What it does: locks passno, ends all agent grants and moves the vault and this device's local state into $PASSNO_HOME/moved-aside/<time>/ (with a README). Nothing is deleted; other devices, iCloud and other storage locations are not touched. Then `pn init` creates a new vault. The moved vault opens again only with its master password and Secret Key.
Confirmation: needs an interactive terminal (type START OVER) and the owner's confirmation on this Mac (Touch ID, Apple Watch or login password). Refused for scripts, agents (PASSNO_AGENT_KEY / PASSNO_SERVICE_TOKEN) and MCP.
Output (--json): { ok, moved_to, old_vault_id, deleted: false }.
Exit codes: 0 moved, 1 nothing to move or storage error, 2 usage error (missing --move-aside, not confirmed), 3 owner confirmation cancelled, 7 daemon unavailable, 8 no terminal or refused for agents.pn lock
Lock the active vault session and zeroize in-memory keys in passnod
text
Examples:
pn lock
pn lock --json
Exit codes: 0 success, 7 daemon unavailable.pn status
Show vault initialization status and path without unlocking
text
Examples:
pn status
pn status --json
Exit codes: 0 success.pn list
List vault items sorted by last update time
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
--kind | 否 | — | Filter by item kind |
--tag | 否 | — | Filter by tag |
--vault | 否 | — | Filter by vault ID |
--include-archived | 否 | — | Include archived items |
--favorites-only | 否 | — | Only show favorite items |
--trashed | 否 | — | Show trashed items instead of active items |
text
Examples:
printf 'pw\n' | pn list --password-stdin
printf 'pw\n' | pn list --password-stdin --kind login --favorites-only --json
Exit codes: 0 success, 2 usage error, 3 wrong credentials.pn search
Search vault items by query string
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
<query> | 是 | — | Case-insensitive search query |
--kind | 否 | — | Filter by item kind |
--tag | 否 | — | Filter by tag |
--vault | 否 | — | Filter by vault ID |
--include-archived | 否 | — | Include archived items |
--favorites-only | 否 | — | Only show favorite items |
--trashed | 否 | — | Show trashed items instead of active items |
text
Examples:
printf 'pw\n' | pn search github --password-stdin
printf 'pw\n' | pn search work --password-stdin --tag ops --json
Exit codes: 0 success, 2 usage error, 3 wrong credentials.pn show
Show an item's details (concealed fields are hidden unless --reveal on an interactive TTY)
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
<id> | 是 | — | Item UUID, title, or pn://vault/item reference |
--reveal | 否 | — | Reveal concealed fields (interactive TTY only; rejected with exit code 8 otherwise) |
text
Examples:
printf 'pw\n' | pn show <item-id> --password-stdin --json
pn show <item-id> --reveal
Security:
--reveal requires an interactive TTY; non-TTY callers exit with code 8.
Exit codes: 0 success, 2 usage error, 3 wrong credentials, 5 not found, 8 policy denied.pn add
Add a new item to the vault
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
--title | 否 | — | Item title (required unless it comes from --from-json) |
--kind | 否 | — | Item category (default: login) |
--url | 否 | — | Primary or additional URL (repeatable) |
--username | 否 | — | Username field value |
--item-password | 否 | — | Password field value. Pass - to type it at a hidden prompt or pipe it on stdin, so it stays out of shell history and ps. On a terminal, pn add asks for it when omitted |
--generate | 否 | — | Generate a strong random password for this item |
--generate-ssh | 否 | — | Generate an SSH key inside the vault (kind ssh-key); only the public key is printed |
--field | 否 | — | Additional text field in LABEL=VALUE form (repeatable) |
--secret-field | 否 | — | Additional concealed secret field in LABEL=VALUE form (repeatable). LABEL=- reads the value at a hidden prompt or from stdin |
--secret-field-file | 否 | — | Concealed field read from a file, kept exactly (multi-line: SSH keys, certificates). Repeatable. Delete the file afterwards |
--totp | 否 | — | TOTP secret or otpauth:// URI; - reads it at a hidden prompt or from stdin |
--notes | 否 | — | Notes |
--tag | 否 | — | Tag (repeatable) |
--favorite | 否 | — | Mark item as favorite |
--vault | 否 | — | Target vault (default or a named sub-vault) |
--agent-enabled | 否 | — | Allow AI agents to see item metadata |
--allow-plaintext-exception | 否 | — | Allow explicit one-time plaintext exception reveal for this item |
--allow-host | 否 | — | Allowed target HTTP host[:port] for pn http requests using this item (repeatable; without it only the item's own websites) |
--allow-path | 否 | — | URL path prefix pn http may send this item to, e.g. /api/ (repeatable; without it any path on an allowed host) |
--confirm-each-use | 否 | — | Sensitive: every agent use asks the owner again (single use, Touch ID / Face ID) |
--confirm-window | 否 | — | With --confirm-each-use: how long one confirmation covers the same action (default 5m; only matters with --confirm-uses above 1) |
--confirm-uses | 否 | — | With --confirm-each-use: how many uses one confirmation covers, within --confirm-window (default 1: every use asks) |
--from-json | 否 | — | Read the item from a JSON document: a file path, or - for the rest of stdin (see --print-template) |
--print-template | 否 | — | Print an empty JSON document for KIND to fill in for --from-json, then exit (no unlock, no secrets) |
text
Examples:
pn add --title GitHub --url https://github.com --username alice --generate
printf 'pw\n' | pn add --password-stdin --title API --kind api-credential --field region=eu --json
printf 'pw\nsynthetic-token\n' | pn add --password-stdin --title API --kind api-credential --secret-field token=- --json
pn add --title 'Deploy key' --kind ssh-key --secret-field-file private_key=./id_ed25519
pn add --title 'CI deploy key' --kind ssh-key --generate-ssh ed25519 --vault Agent > deploy.pub
pn add --title 'Prod DB' --kind api-credential --agent-enabled --confirm-each-use --confirm-window 15m --confirm-uses 3
pn add --print-template api-credential > item.json # fill it in, then:
pn add --from-json item.json && rm item.json
printf 'pw\n{"title":"API","kind":"api-credential"}' | pn add --password-stdin --from-json - --json
Input:
Secret flags given as `-` are read at a hidden prompt, or one line each from stdin after the master password line (`--password-stdin`), in this order: item password, TOTP, each --secret-field. `--from-json -` reads the rest of stdin as one JSON document instead (it cannot be combined with `-` secret flags). Flags override the same keys from the JSON document; --field/--secret-field are added after its fields. Files given to --from-json or --secret-field-file hold secrets in plaintext: delete them afterwards.
SSH keys:
--generate-ssh ed25519 creates the key inside the vault (fields private_key, public_key, fingerprint) and prints only the public key in OpenSSH format on stdout (the item id goes to stderr; with --json both are in the JSON). The private key never leaves the vault; `pn ssh-agent` signs with it.
Confirmation limits:
A --confirm-each-use item asks the owner (Touch ID / Face ID) before agent use. With --confirm-uses above 1, one confirmation lets the agent repeat the same action until --confirm-window passes or the uses run out, whichever comes first, or the vault locks; then it asks again. Plaintext reveals always ask every time.
Exit codes: 0 success, 2 invalid input, 3 wrong credentials or vault locked, 5 sub-vault not found.pn edit
Edit an existing item in the vault
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
<id> | 是 | — | Item UUID, title, or pn://vault/item reference |
--title | 否 | — | New title |
--url | 否 | — | Replace URLs (repeatable) |
--username | 否 | — | Update username field |
--item-password | 否 | — | Update password field (old password moves to history). Pass - to type it at a hidden prompt or pipe it on stdin, so it stays out of shell history and ps |
--generate | 否 | — | Generate and set a new password (old password moves to history) |
--field | 否 | — | Set a text field LABEL=VALUE: updates the field with that label or adds it (repeatable) |
--secret-field | 否 | — | Set a concealed field LABEL=VALUE (a replaced password goes to history); LABEL=- reads it at a hidden prompt or from stdin (repeatable) |
--secret-field-file | 否 | — | Set a concealed field from a file, kept exactly (multi-line keys, certificates). Repeatable. Delete the file afterwards |
--totp | 否 | — | Set the TOTP secret or otpauth:// URI; - reads it at a hidden prompt or from stdin |
--remove-field | 否 | — | Remove every field with this label (repeatable) |
--notes | 否 | — | Update notes |
--tag | 否 | — | Replace tags (repeatable) |
--favorite | 否 | — | Set favorite flag |
--agent-enabled | 否 | — | Let AI agents use this item (false also ends their current grants on it) |
--allow-host | 否 | — | Hosts pn http may send this item to (repeatable; replaces the current list) |
--clear-allow-hosts | 否 | — | Remove every allowed host (pn http then sends it only to the item's own websites) |
--allow-path | 否 | — | URL path prefixes pn http may send this item to, e.g. /api/ (repeatable; replaces the current list) |
--clear-allow-paths | 否 | — | Remove every allowed path (any path on an allowed host) |
--confirm-each-use | 否 | — | Sensitive: every agent use asks the owner again (true also ends current grants) |
--confirm-window | 否 | — | Sensitive items: how long one confirmation covers the same action (only matters with --confirm-uses above 1; lowering it ends current grants) |
--confirm-uses | 否 | — | Sensitive items: how many uses one confirmation covers, within --confirm-window (1 = every use asks; lowering it ends current grants) |
--from-json | 否 | — | Read changes from a JSON document: a file path, or - for the rest of stdin (same keys as pn add --print-template; only the keys present change) |
text
Examples:
pn edit <id> --title 'GitHub Work' --favorite true
printf 'pw\n' | pn edit <id> --password-stdin --generate --json
pn edit <id> --secret-field token=- # rotate a leaked token (typed at a hidden prompt)
pn edit <id> --field region=us --remove-field legacy_id
pn edit <id> --totp -
pn edit <id> --agent-enabled true --allow-host api.example.com --confirm-each-use false
pn edit <id> --clear-allow-hosts
pn edit <id> --confirm-each-use true --confirm-window 5m --confirm-uses 3
pn edit <id> --from-json changes.json
Input:
Secret flags given as `-` are read at a hidden prompt, or one line each from stdin after the master password line (`--password-stdin`), in this order: item password, TOTP, each --secret-field. Fields are matched by label (case-insensitive): an existing field is updated, otherwise a new one is added. A replaced password moves to the password history; other fields are overwritten. A secret written over a plain field makes it concealed; a concealed field is never made plain. --remove-field runs before the other changes. `--allow-host` replaces the whole list. Turning agent access off, marking the item --confirm-each-use or lowering --confirm-window / --confirm-uses ends the agents' current grants on it.
Confirmation limits:
A --confirm-each-use item asks the owner (Touch ID / Face ID) before agent use. With --confirm-uses above 1, one confirmation lets the agent repeat the same action until --confirm-window passes or the uses run out, whichever comes first, or the vault locks; then it asks again. Plaintext reveals always ask every time.
Exit codes: 0 success, 2 invalid input, 3 wrong credentials or vault locked, 5 item or field not found.pn move
Move an item between the main vault and a named sub-vault (e.g. hand it to the Agent vault)
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
<item> | 是 | — | Item UUID, title, or pn://vault/item reference (the vault part names the source) |
--to-vault | 是 | — | Target vault: default for the main vault, or a sub-vault name such as Agent |
text
Examples:
pn move 'Deploy token' --to-vault Agent
pn move <item-id> --to-vault Agent --json
pn move pn://Agent/deploy-token --to-vault default
The item keeps its id, fields, password history and agent settings; it is copied into the target vault and then permanently removed from the source. In an agent-usable vault, agents (and that vault's service tokens) can use it. Agents' existing grants on it end. Items with attachments and shared-vault items cannot be moved.
Exit codes: 0 success, 2 invalid input (same vault, attachments, ambiguous title), 3 locked or session not authorized, 5 item or vault not found.pn rm
Soft-delete (move to trash) an item
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
<id> | 是 | — | Item UUID, title, or pn://vault/item reference |
text
Examples:
printf 'pw\n' | pn rm <item-id> --password-stdin --json
Exit codes: 0 success, 3 wrong credentials, 5 not found.pn restore
Restore a trashed item
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
<id> | 是 | — | Item UUID |
text
Examples:
printf 'pw\n' | pn restore <item-id> --password-stdin --json
Exit codes: 0 success, 3 wrong credentials, 5 not found.pn gen
Generate a password, passphrase, or PIN (does not require unlocking)
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
--kind | 否 | random | Generator mode |
--length | 否 | — | Length (characters for random/pin, words for passphrase) |
--no-uppercase | 否 | — | Exclude uppercase characters (random mode) |
--no-digits | 否 | — | Exclude digits (random mode) |
--no-symbols | 否 | — | Exclude symbols (random mode) |
--avoid-ambiguous | 否 | — | Avoid visually ambiguous characters (0, O, 1, l, I) |
--separator | 否 | — | Word separator (passphrase mode) |
--capitalize | 否 | — | Capitalize each word (passphrase mode) |
--for-domain | 否 | — | Apply site password rules for domain (Apple Password Manager Resources) |
text
Examples:
pn gen
pn gen --kind passphrase --length 5 --capitalize --json
pn gen --kind pin --length 6
Exit codes: 0 success, 2 invalid generator options.pn totp
Compute the current TOTP verification code for an item
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
<id> | 是 | — | Item UUID, title, or pn://vault/item reference |
text
Examples:
printf 'pw\n' | pn totp <item-id> --password-stdin --json
Exit codes: 0 success, 1 item has no TOTP, 3 wrong credentials, 5 not found.pn attach
Manage encrypted file attachments on an item (max 128 MiB per attachment)
pn attach add
Encrypt and attach a local file to an item
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
<id> | 是 | — | Item UUID, title, or pn://vault/item reference |
<file> | 是 | — | Path to the file to attach |
pn attach ls
List attachments belonging to an item
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
<id> | 是 | — | Item UUID, title, or pn://vault/item reference |
pn attach export
Decrypt and export an attachment to a destination path
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
<id> | 是 | — | Item UUID, title, or pn://vault/item reference |
<attachment> | 是 | — | Attachment ID or unique file name |
<dest> | 是 | — | Destination file path |
--force | 否 | — | Overwrite destination if it already exists |
pn attach rm
Remove an attachment from an item
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
<id> | 是 | — | Item UUID, title, or pn://vault/item reference |
<attachment> | 是 | — | Attachment ID or unique file name |
text
Subcommands:
add Encrypt and attach a local file to an item
ls List attachments stored on an item
export Decrypt and write an attachment to a destination path
rm Remove an attachment and garbage-collect unreferenced blobs
Examples:
printf 'pw\n' | pn attach add <item-id> ./recovery.txt --password-stdin --json
printf 'pw\n' | pn attach ls <item-id> --password-stdin --json
printf 'pw\n' | pn attach export <item-id> recovery.txt ./out.txt --password-stdin --json
printf 'pw\n' | pn attach rm <item-id> <attachment-id> --password-stdin --json
Exit codes: 0 success, 2 invalid input or overwrite blocked, 3 wrong credentials, 5 not found.pn attach add
Encrypt and attach a local file to an item
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
<id> | 是 | — | Item UUID, title, or pn://vault/item reference |
<file> | 是 | — | Path to the file to attach |
pn attach ls
List attachments belonging to an item
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
<id> | 是 | — | Item UUID, title, or pn://vault/item reference |
pn attach export
Decrypt and export an attachment to a destination path
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
<id> | 是 | — | Item UUID, title, or pn://vault/item reference |
<attachment> | 是 | — | Attachment ID or unique file name |
<dest> | 是 | — | Destination file path |
--force | 否 | — | Overwrite destination if it already exists |
pn attach rm
Remove an attachment from an item
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
<id> | 是 | — | Item UUID, title, or pn://vault/item reference |
<attachment> | 是 | — | Attachment ID or unique file name |
pn history
Inspect an item's password history metadata (or reveal on an interactive TTY)
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
<id> | 是 | — | Item UUID, title, or pn://vault/item reference |
--index | 否 | — | Inspect a single 0-based history revision index |
--reveal | 否 | — | Reveal previous plaintext password(s) (requires interactive TTY) |
text
Examples:
printf 'pw\n' | pn history <item-id> --password-stdin --json
pn history <item-id> --reveal
pn history <item-id> --index 0 --reveal
Security:
--reveal requires an interactive TTY; non-TTY callers exit with code 8.
Exit codes: 0 success, 2 usage error, 3 wrong credentials, 5 not found, 8 policy denied.pn trash
List, restore, or permanently purge trashed items
pn trash ls
List items currently in the trash
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
--kind | 否 | — | Filter by item kind |
--tag | 否 | — | Filter by tag |
--vault | 否 | — | Filter by vault ID |
--include-archived | 否 | — | Include archived items |
--favorites-only | 否 | — | Only show favorite items |
--trashed | 否 | — | Show trashed items instead of active items |
pn trash restore
Restore a trashed item
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
<id> | 是 | — | Item UUID |
pn trash purge
Permanently delete a trashed item (or all trashed items with --all)
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
<id> | 否 | — | Trashed item UUID to permanently purge |
--all | 否 | — | Permanently purge all items in the trash |
text
Subcommands:
ls List items in the trash
restore Restore a trashed item back to active state
purge Permanently delete a trashed item or empty the entire trash
Examples:
printf 'pw\n' | pn trash ls --password-stdin --json
printf 'pw\n' | pn trash restore <item-id> --password-stdin --json
printf 'pw\n' | pn trash purge <item-id> --password-stdin --json
printf 'pw\n' | pn trash purge --all --password-stdin --json
Exit codes: 0 success, 2 invalid input (e.g. purging an active item), 3 wrong credentials, 5 not found.pn trash ls
List items currently in the trash
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
--kind | 否 | — | Filter by item kind |
--tag | 否 | — | Filter by tag |
--vault | 否 | — | Filter by vault ID |
--include-archived | 否 | — | Include archived items |
--favorites-only | 否 | — | Only show favorite items |
--trashed | 否 | — | Show trashed items instead of active items |
pn trash restore
Restore a trashed item
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
<id> | 是 | — | Item UUID |
pn trash purge
Permanently delete a trashed item (or all trashed items with --all)
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
<id> | 否 | — | Trashed item UUID to permanently purge |
--all | 否 | — | Permanently purge all items in the trash |
pn import
Preview or commit an import from 1Password (.1pux / CSV) or Apple Passwords CSV
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
<path> | 是 | — | Path to export file (.1pux or .csv) |
--format | 否 | — | Source format (auto-detected from file extension/header if omitted) |
--preview | 否 | — | Read-only preview without modifying vault |
--duplicate | 否 | skip | Duplicate item policy |
text
Examples:
printf 'pw\n' | pn import ./export.1pux --preview --password-stdin --json
printf 'pw\n' | pn import ./passwords.csv --format apple-csv --password-stdin --json
Exit codes: 0 success, 2 invalid/unsupported format, 3 wrong credentials.pn doctor
Run diagnostics on CLI installation, vault directory, and Secret Key permissions
text
Examples:
pn doctor
pn doctor --json
Exit codes: 0 all checks healthy, 1 one or more checks warn/fail.pn crashes
List, show or delete local crash reports (never uploaded, no vault content)
pn crashes ls
List local crash reports, newest first
text
Examples:
pn crashes ls
pn crashes ls --json
Exit codes: 0 success, 1 storage error.pn crashes show
Print one report as plain text to paste into an issue or email
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
<id> | 是 | — | Report id from pn crashes ls, or latest |
text
Examples:
pn crashes show 1763280000000-1a2b3c4d
pn crashes show latest --json
Exit codes: 0 success, 1 storage error, 5 not found.pn crashes clear
Delete every local crash report
text
Examples:
pn crashes clear
pn crashes clear --json
Exit codes: 0 success, 1 storage error.text
Examples:
pn crashes ls --json
pn crashes show latest
pn crashes clear
Exit codes: 0 success, 1 storage error, 5 not found.pn crashes ls
List local crash reports, newest first
text
Examples:
pn crashes ls
pn crashes ls --json
Exit codes: 0 success, 1 storage error.pn crashes show
Print one report as plain text to paste into an issue or email
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
<id> | 是 | — | Report id from pn crashes ls, or latest |
text
Examples:
pn crashes show 1763280000000-1a2b3c4d
pn crashes show latest --json
Exit codes: 0 success, 1 storage error, 5 not found.pn crashes clear
Delete every local crash report
text
Examples:
pn crashes clear
pn crashes clear --json
Exit codes: 0 success, 1 storage error.pn agent-help
Print concise Markdown guidance for AI agents
text
Examples:
pn agent-help
Exit codes: 0 success.pn sync
Synchronize vault across devices via shared folder or Git remote
pn sync locations
List primary and backup storage references (no credentials)
text
Examples:
pn sync locations --json
pn sync locations
Exit codes: 0 success, 2 not configured.pn sync status
Show sync configuration, last sync status, and verified peer devices
text
Examples:
pn sync status
pn sync status --json
Daemon mode reuses the shared session; --no-daemon reads local state.
Exit codes: 0 success, 1 storage/sync error, 7 daemon unavailable.pn sync now
Synchronize local vault with remote replica (pull verified changes, then push local changes)
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
--locked-only | 否 | — | Local mode only: pull and push verified encrypted logs without unlocking vault items |
--secret-key | 否 | — | Local mode only: explicit Secret Key override when unlocking (A3-..., or - to read it at a hidden prompt or from stdin) |
text
Examples:
pn sync now
pn sync now --json
pn --no-daemon sync now --locked-only --json
Default: sync through passnod without another password prompt (ciphertext sync also works locked). Output: SyncStatusRecord; --no-daemon returns SyncReport.
Exit codes: 0 success, 1 storage error, 2 invalid configuration/security validation failed, 3 auth failed, 5 local-mode sync error, 7 daemon unavailable, 8 device revoked.pn sync setup
Configure primary or backup storage; store credentials in the recovery bundle
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
--folder | 否 | — | Local or cloud-synced folder path (iCloud Drive, Syncthing, Dropbox, USB) |
--icloud | 否 | — | Use iCloud Drive's passno/<vault-id> folder |
--s3 | 否 | — | S3-compatible endpoint; credentials from PASSNO_SYNC_ACCESS_KEY / PASSNO_SYNC_SECRET_KEY |
--bucket | 否 | — | |
--region | 否 | auto | |
--prefix | 否 | passno | |
--webdav | 否 | — | WebDAV root; credentials from PASSNO_SYNC_USERNAME / PASSNO_SYNC_PASSWORD |
--backup | 否 | — | Append an additional backup destination |
--name | 否 | Personal | Display name used when creating the public discovery header |
--no-recovery | 否 | — | Opt out of recovery bundle (folder only; keep your emergency kit offline) |
--git | 否 | — | Git remote URL or local bare repository path |
--branch | 否 | main | Git branch name when configuring --git |
--auto-sync | 否 | — | Mark automatic periodic sync enabled for daemon/scheduler hooks |
--interval | 否 | 60 | Periodic sync interval in seconds (minimum 5) |
text
Examples:
pn sync setup --icloud
pn sync setup --folder /Volumes/USB/passno --backup
pn sync setup --git ssh://git@host/vault.git
pn sync setup --s3 https://account.r2.cloudflarestorage.com --bucket passno --region auto
pn sync setup --webdav https://server.example/passno/
Credentials: S3 uses PASSNO_SYNC_ACCESS_KEY/PASSNO_SYNC_SECRET_KEY; WebDAV uses PASSNO_SYNC_USERNAME/PASSNO_SYNC_PASSWORD. Default setup requires the master password and a secure recovery store; --no-recovery opts out for folder storage.
Exit codes: 0 success, 1 storage unavailable, 2 invalid arguments, 3 auth failed.text
Examples:
pn sync setup --folder ~/iCloudVault
pn sync setup --git ssh://git@host/vault.git
pn sync now
pn sync status --json
Exit codes: 0 success, 2 usage error, 3 auth failed, 5 sync/tamper/fork/rollback error.pn sync locations
List primary and backup storage references (no credentials)
text
Examples:
pn sync locations --json
pn sync locations
Exit codes: 0 success, 2 not configured.pn sync status
Show sync configuration, last sync status, and verified peer devices
text
Examples:
pn sync status
pn sync status --json
Daemon mode reuses the shared session; --no-daemon reads local state.
Exit codes: 0 success, 1 storage/sync error, 7 daemon unavailable.pn sync now
Synchronize local vault with remote replica (pull verified changes, then push local changes)
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
--locked-only | 否 | — | Local mode only: pull and push verified encrypted logs without unlocking vault items |
--secret-key | 否 | — | Local mode only: explicit Secret Key override when unlocking (A3-..., or - to read it at a hidden prompt or from stdin) |
text
Examples:
pn sync now
pn sync now --json
pn --no-daemon sync now --locked-only --json
Default: sync through passnod without another password prompt (ciphertext sync also works locked). Output: SyncStatusRecord; --no-daemon returns SyncReport.
Exit codes: 0 success, 1 storage error, 2 invalid configuration/security validation failed, 3 auth failed, 5 local-mode sync error, 7 daemon unavailable, 8 device revoked.pn sync setup
Configure primary or backup storage; store credentials in the recovery bundle
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
--folder | 否 | — | Local or cloud-synced folder path (iCloud Drive, Syncthing, Dropbox, USB) |
--icloud | 否 | — | Use iCloud Drive's passno/<vault-id> folder |
--s3 | 否 | — | S3-compatible endpoint; credentials from PASSNO_SYNC_ACCESS_KEY / PASSNO_SYNC_SECRET_KEY |
--bucket | 否 | — | |
--region | 否 | auto | |
--prefix | 否 | passno | |
--webdav | 否 | — | WebDAV root; credentials from PASSNO_SYNC_USERNAME / PASSNO_SYNC_PASSWORD |
--backup | 否 | — | Append an additional backup destination |
--name | 否 | Personal | Display name used when creating the public discovery header |
--no-recovery | 否 | — | Opt out of recovery bundle (folder only; keep your emergency kit offline) |
--git | 否 | — | Git remote URL or local bare repository path |
--branch | 否 | main | Git branch name when configuring --git |
--auto-sync | 否 | — | Mark automatic periodic sync enabled for daemon/scheduler hooks |
--interval | 否 | 60 | Periodic sync interval in seconds (minimum 5) |
text
Examples:
pn sync setup --icloud
pn sync setup --folder /Volumes/USB/passno --backup
pn sync setup --git ssh://git@host/vault.git
pn sync setup --s3 https://account.r2.cloudflarestorage.com --bucket passno --region auto
pn sync setup --webdav https://server.example/passno/
Credentials: S3 uses PASSNO_SYNC_ACCESS_KEY/PASSNO_SYNC_SECRET_KEY; WebDAV uses PASSNO_SYNC_USERNAME/PASSNO_SYNC_PASSWORD. Default setup requires the master password and a secure recovery store; --no-recovery opts out for folder storage.
Exit codes: 0 success, 1 storage unavailable, 2 invalid arguments, 3 auth failed.pn share
Manage family/team shared vaults without exposing secret fields
pn share identity
Display your public identity and verification fingerprint (no private keys)
text
Example: pn share identity --json
Exit codes: 0 success, 3 locked, 7 daemon unavailable.pn share ls
List shared vaults, roles, epochs and synchronization status
text
Example: pn share ls --json
Exit codes: 0 success, 2 verification error, 3 locked.pn share create
Create an independent shared vault owned by this account
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
<name> | 是 | — |
text
Example: pn share create Family --json
Exit codes: 0 success, 2 invalid name, 3 locked.pn share members
List member identities and roles
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
<vault_id> | 是 | — |
text
Example: pn share members <vault-id> --json
Exit codes: 0 success, 2 invalid vault, 3 locked.pn share items
List shared item metadata; secret fields are never returned
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
<vault_id> | 是 | — |
text
Example: pn share items <vault-id> --json
Exit codes: 0 success, 2 revoked or invalid vault, 3 locked.pn share copy
Copy a personal item into a shared vault internally without returning its secrets
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
<vault_id> | 是 | — | |
<item_id> | 是 | — |
text
Example: pn share copy <vault-id> <item-id> --json
Exit codes: 0 success, 2 viewer denied/unsupported attachment, 3 locked, 5 item missing.pn share import
Copy a shared item into your personal vault for ordinary use/autofill
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
<vault_id> | 是 | — | |
<item_id> | 是 | — |
text
Example: pn share import <vault-id> <item-id> --json
Exit codes: 0 success, 2 revoked, 3 locked, 5 item missing.pn share invite
Issue a recipient-bound invitation after verifying their public fingerprint
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
<vault_id> | 是 | — | |
--identity-file | 是 | — | |
--fingerprint | 是 | — | |
--role | 否 | viewer |
text
Example: pn share invite <vault-id> --identity-file recipient.json --fingerprint XXXX --role viewer --json
Public identity files may be the output of pn share identity --json. Output contains no bearer secret.
Exit codes: 0 success, 2 fingerprint mismatch/role denied, 3 locked.pn share accept
Accept a one-time recipient-bound invitation and pin the owner's fingerprint
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
--code-file | 是 | — | |
--fingerprint | 是 | — | |
--folder | 否 | — | |
--location-file | 否 | — | JSON object containing location and optional credentials; never echoed |
text
Example: pn share accept --code-file invite.json --fingerprint XXXX --folder /tmp/family --json
Exit codes: 0 success, 2 invalid/replayed invitation or storage error, 3 locked.pn share configure
Set a location for this shared vault, encrypted locally to your account
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
<vault_id> | 是 | — | |
--folder | 否 | — | |
--location-file | 否 | — | JSON object containing location and optional credentials; never echoed |
text
Example: pn share configure <vault-id> --folder /tmp/family --json
Use --location-file for Git/S3/WebDAV JSON {location, credentials}.
Exit codes: 0 success, 2 invalid location, 3 locked.pn share sync
Pull verified changes, handle leave requests as owner, and push encrypted records
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
<vault_id> | 是 | — |
text
Example: pn share sync <vault-id> --json
Exit codes: 0 success, 2 sync/fork/rollback error, 3 locked.pn share remove
Remove a member, rotate the epoch, and list passwords that must be changed
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
<vault_id> | 是 | — | |
<member_id> | 是 | — | |
--confirm | 否 | — |
text
Example: pn share remove <vault-id> <member-id> --confirm --json
Already copied old data cannot be recalled. Run share sync afterwards.
Exit codes: 0 success, 2 not owner/confirmation missing, 3 locked.pn share role
Change an editor/viewer role with a fresh epoch
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
<vault_id> | 是 | — | |
<member_id> | 是 | — | |
<role> | 是 | — |
text
Example: pn share role <vault-id> <member-id> viewer --json
Exit codes: 0 success, 2 not owner/invalid role, 3 locked.pn share leave
Leave locally and send a signed request; owner rotates after receiving it
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
<vault_id> | 是 | — | |
--confirm | 否 | — |
text
Example: pn share leave <vault-id> --confirm --json
Then run share sync; owner must sync to complete cryptographic revocation.
Exit codes: 0 success, 2 owner cannot leave/confirmation missing, 3 locked.text
Examples:
pn share create Family --json
pn share identity --json
pn share ls --json
Exit codes: 0 success, 1 storage error, 2 invalid input/role/integrity, 3 locked, 5 not found, 7 daemon unavailable.pn share identity
Display your public identity and verification fingerprint (no private keys)
text
Example: pn share identity --json
Exit codes: 0 success, 3 locked, 7 daemon unavailable.pn share ls
List shared vaults, roles, epochs and synchronization status
text
Example: pn share ls --json
Exit codes: 0 success, 2 verification error, 3 locked.pn share create
Create an independent shared vault owned by this account
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
<name> | 是 | — |
text
Example: pn share create Family --json
Exit codes: 0 success, 2 invalid name, 3 locked.pn share members
List member identities and roles
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
<vault_id> | 是 | — |
text
Example: pn share members <vault-id> --json
Exit codes: 0 success, 2 invalid vault, 3 locked.pn share items
List shared item metadata; secret fields are never returned
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
<vault_id> | 是 | — |
text
Example: pn share items <vault-id> --json
Exit codes: 0 success, 2 revoked or invalid vault, 3 locked.pn share copy
Copy a personal item into a shared vault internally without returning its secrets
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
<vault_id> | 是 | — | |
<item_id> | 是 | — |
text
Example: pn share copy <vault-id> <item-id> --json
Exit codes: 0 success, 2 viewer denied/unsupported attachment, 3 locked, 5 item missing.pn share import
Copy a shared item into your personal vault for ordinary use/autofill
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
<vault_id> | 是 | — | |
<item_id> | 是 | — |
text
Example: pn share import <vault-id> <item-id> --json
Exit codes: 0 success, 2 revoked, 3 locked, 5 item missing.pn share invite
Issue a recipient-bound invitation after verifying their public fingerprint
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
<vault_id> | 是 | — | |
--identity-file | 是 | — | |
--fingerprint | 是 | — | |
--role | 否 | viewer |
text
Example: pn share invite <vault-id> --identity-file recipient.json --fingerprint XXXX --role viewer --json
Public identity files may be the output of pn share identity --json. Output contains no bearer secret.
Exit codes: 0 success, 2 fingerprint mismatch/role denied, 3 locked.pn share accept
Accept a one-time recipient-bound invitation and pin the owner's fingerprint
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
--code-file | 是 | — | |
--fingerprint | 是 | — | |
--folder | 否 | — | |
--location-file | 否 | — | JSON object containing location and optional credentials; never echoed |
text
Example: pn share accept --code-file invite.json --fingerprint XXXX --folder /tmp/family --json
Exit codes: 0 success, 2 invalid/replayed invitation or storage error, 3 locked.pn share configure
Set a location for this shared vault, encrypted locally to your account
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
<vault_id> | 是 | — | |
--folder | 否 | — | |
--location-file | 否 | — | JSON object containing location and optional credentials; never echoed |
text
Example: pn share configure <vault-id> --folder /tmp/family --json
Use --location-file for Git/S3/WebDAV JSON {location, credentials}.
Exit codes: 0 success, 2 invalid location, 3 locked.pn share sync
Pull verified changes, handle leave requests as owner, and push encrypted records
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
<vault_id> | 是 | — |
text
Example: pn share sync <vault-id> --json
Exit codes: 0 success, 2 sync/fork/rollback error, 3 locked.pn share remove
Remove a member, rotate the epoch, and list passwords that must be changed
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
<vault_id> | 是 | — | |
<member_id> | 是 | — | |
--confirm | 否 | — |
text
Example: pn share remove <vault-id> <member-id> --confirm --json
Already copied old data cannot be recalled. Run share sync afterwards.
Exit codes: 0 success, 2 not owner/confirmation missing, 3 locked.pn share role
Change an editor/viewer role with a fresh epoch
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
<vault_id> | 是 | — | |
<member_id> | 是 | — | |
<role> | 是 | — |
text
Example: pn share role <vault-id> <member-id> viewer --json
Exit codes: 0 success, 2 not owner/invalid role, 3 locked.pn share leave
Leave locally and send a signed request; owner rotates after receiving it
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
<vault_id> | 是 | — | |
--confirm | 否 | — |
text
Example: pn share leave <vault-id> --confirm --json
Then run share sync; owner must sync to complete cryptographic revocation.
Exit codes: 0 success, 2 owner cannot leave/confirmation missing, 3 locked.pn device
Manage enrolled devices, generate QR enrollment codes, or revoke devices
pn device revoke-lost
Fully replace account keys and Secret Key after a device is lost; invalidate all old devices
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
<device_id> | 是 | — | |
--new-password-file | 是 | — | Read the new master password from a protected file; never pass a password as an argument |
--confirm | 否 | — |
text
Example: pn device revoke-lost <device-id> --new-password-file /tmp/new-master --confirm --json
Requires an unlocked session and recovery store. Returns only metadata and an emergency-kit path. All other devices must reenroll.
Exit codes: 0 success, 1 storage error, 2 invalid/other shared owner needed, 3 locked, 7 daemon unavailable.pn device resume-revocation
Resume an interrupted account replacement without using the old session
text
Example: pn device resume-revocation --json
Exit codes: 0 success, 2 missing/invalid staging journal, 7 daemon unavailable.pn device ls
List enrolled and revoked devices from verified membership logs
text
Examples:
pn device ls
pn device ls --json
`display_name` (the name shown) is the name given in the passno app on this computer, else `device_name`, the name the device reported. Names given in the app stay on this computer.
Exit codes: 0 success, 5 vault not initialized or tampered.pn device add
Generate a QR code and enrollment URI for adding another device
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
--secret-key | 否 | — | Explicit Secret Key override (A3-..., or - to read it at a hidden prompt or from stdin) |
text
Examples:
pn device add
pn device add --json (human TTY only)
Exit codes: 0 success, 2 sync not configured, 3 auth failed, 5 vault error, 8 non-interactive secret output denied.pn device join
Enroll this device into an existing synced vault using a enrollment code
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
--code | 是 | — | Enrollment URI or base64url payload produced by pn device add |
--name | 否 | — | Optional human-readable label for this device |
--auto-sync | 否 | — | Mark automatic periodic sync enabled on the joined device |
--interval | 否 | 60 | Periodic sync interval in seconds (minimum 5) |
text
Examples:
pn device join --code 'passno://enroll?v=1&d=...' --name MacBook --password-stdin
Exit codes: 0 success, 2 invalid code or already initialized, 3 auth failed, 5 sync/tamper error.pn device rm
Revoke a device, rotate vault epoch keys, and sync revocation immediately
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
<device_id> | 是 | — | Device ID to revoke (see pn device ls) |
--secret-key | 否 | — | Explicit Secret Key override (A3-..., or - to read it at a hidden prompt or from stdin) |
text
Examples:
pn device rm <device-id> --password-stdin
Exit codes: 0 success, 3 auth failed, 5 device not found or sync/tamper error.text
Examples:
pn device ls --json
pn device add --password-stdin
pn device join --code 'passno://enroll?...' --password-stdin
pn device rm <device-id> --password-stdin
Exit codes: 0 success, 2 usage error, 3 auth failed, 5 device not found or sync/tamper error.pn device revoke-lost
Fully replace account keys and Secret Key after a device is lost; invalidate all old devices
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
<device_id> | 是 | — | |
--new-password-file | 是 | — | Read the new master password from a protected file; never pass a password as an argument |
--confirm | 否 | — |
text
Example: pn device revoke-lost <device-id> --new-password-file /tmp/new-master --confirm --json
Requires an unlocked session and recovery store. Returns only metadata and an emergency-kit path. All other devices must reenroll.
Exit codes: 0 success, 1 storage error, 2 invalid/other shared owner needed, 3 locked, 7 daemon unavailable.pn device resume-revocation
Resume an interrupted account replacement without using the old session
text
Example: pn device resume-revocation --json
Exit codes: 0 success, 2 missing/invalid staging journal, 7 daemon unavailable.pn device ls
List enrolled and revoked devices from verified membership logs
text
Examples:
pn device ls
pn device ls --json
`display_name` (the name shown) is the name given in the passno app on this computer, else `device_name`, the name the device reported. Names given in the app stay on this computer.
Exit codes: 0 success, 5 vault not initialized or tampered.pn device add
Generate a QR code and enrollment URI for adding another device
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
--secret-key | 否 | — | Explicit Secret Key override (A3-..., or - to read it at a hidden prompt or from stdin) |
text
Examples:
pn device add
pn device add --json (human TTY only)
Exit codes: 0 success, 2 sync not configured, 3 auth failed, 5 vault error, 8 non-interactive secret output denied.pn device join
Enroll this device into an existing synced vault using a enrollment code
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
--code | 是 | — | Enrollment URI or base64url payload produced by pn device add |
--name | 否 | — | Optional human-readable label for this device |
--auto-sync | 否 | — | Mark automatic periodic sync enabled on the joined device |
--interval | 否 | 60 | Periodic sync interval in seconds (minimum 5) |
text
Examples:
pn device join --code 'passno://enroll?v=1&d=...' --name MacBook --password-stdin
Exit codes: 0 success, 2 invalid code or already initialized, 3 auth failed, 5 sync/tamper error.pn device rm
Revoke a device, rotate vault epoch keys, and sync revocation immediately
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
<device_id> | 是 | — | Device ID to revoke (see pn device ls) |
--secret-key | 否 | — | Explicit Secret Key override (A3-..., or - to read it at a hidden prompt or from stdin) |
text
Examples:
pn device rm <device-id> --password-stdin
Exit codes: 0 success, 3 auth failed, 5 device not found or sync/tamper error.pn help
Show help for pn or a subcommand (supports --json for machine-readable schema)
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
<command> | 否 | — | Subcommand name to inspect (omit for top-level overview) |
text
Examples:
pn help --json
pn help show --json
pn help list
Exit codes: 0 success, 2 unknown command.pn vault
Manage isolated sub-vaults, discover replicas, or restore recovery bundles
pn vault create
Create an isolated named sub-vault
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
<name> | 是 | — | |
--agent-usable | 否 | — |
text
Examples:
pn vault create Agent --agent-usable --json
Exit codes: 0 success, 3 locked, 7 daemon unavailable.pn vault ls
List named sub-vaults (metadata only)
text
Examples:
pn vault ls --json
Exit codes: 0 success.pn vault discover
Discover recovery bundles and local sync folders; optional private GitHub repositories
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
--folder | 否 | — | |
--github | 否 | — |
text
Examples:
pn vault discover --json
pn vault discover --folder /tmp/replica --github --json
Exit codes: 0 discovery completed (inspect warnings), 1 storage failure.pn vault restore
Restore on a new device; bundle supplies Secret Key, user supplies master password
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
<vault_id> | 是 | — |
text
Examples:
pn vault restore <vault-id>
pn vault restore <vault-id> --password-stdin --json
Exit codes: 0 success, 1 storage failure, 2 missing bundle/already initialized, 3 wrong password, 5 integrity error.pn vault emergency-kit
Display a complete emergency kit (including storage credentials), human terminal only
text
Examples:
pn vault emergency-kit
pn vault emergency-kit --json
Exit codes: 0 success, 2 missing bundle, 3 auth failed, 8 non-TTY denied.pn vault import-kit
Import an emergency kit URI into the secure recovery store without printing it
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
--file | 是 | — |
text
Examples:
pn vault import-kit --file /media/offline/recovery.txt --json
Exit codes: 0 success, 1 secure store unavailable, 2 invalid kit.text
Examples:
printf 'pw\n' | pn vault create Agent --agent-usable --password-stdin --json
pn vault ls --json
pn vault discover --json
pn vault restore <vault-id>
pn vault emergency-kit
Exit codes: 0 success, 1 storage error, 2 invalid args, 3 wrong credentials, 5 integrity error, 7 daemon unavailable, 8 non-TTY secret output denied.pn vault create
Create an isolated named sub-vault
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
<name> | 是 | — | |
--agent-usable | 否 | — |
text
Examples:
pn vault create Agent --agent-usable --json
Exit codes: 0 success, 3 locked, 7 daemon unavailable.pn vault ls
List named sub-vaults (metadata only)
text
Examples:
pn vault ls --json
Exit codes: 0 success.pn vault discover
Discover recovery bundles and local sync folders; optional private GitHub repositories
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
--folder | 否 | — | |
--github | 否 | — |
text
Examples:
pn vault discover --json
pn vault discover --folder /tmp/replica --github --json
Exit codes: 0 discovery completed (inspect warnings), 1 storage failure.pn vault restore
Restore on a new device; bundle supplies Secret Key, user supplies master password
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
<vault_id> | 是 | — |
text
Examples:
pn vault restore <vault-id>
pn vault restore <vault-id> --password-stdin --json
Exit codes: 0 success, 1 storage failure, 2 missing bundle/already initialized, 3 wrong password, 5 integrity error.pn vault emergency-kit
Display a complete emergency kit (including storage credentials), human terminal only
text
Examples:
pn vault emergency-kit
pn vault emergency-kit --json
Exit codes: 0 success, 2 missing bundle, 3 auth failed, 8 non-TTY denied.pn vault import-kit
Import an emergency kit URI into the secure recovery store without printing it
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
--file | 是 | — |
text
Examples:
pn vault import-kit --file /media/offline/recovery.txt --json
Exit codes: 0 success, 1 secure store unavailable, 2 invalid kit.pn agent
Manage enrolled AI agent identities, service tokens, audit chain, and MCP setup
pn agent grants
List grants, or revoke one by ID
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
--revoke | 否 | — |
text
Examples:
pn agent grants --json
pn agent grants --revoke gr_... --json
Exit codes: 0 success, 5 unknown grant.pn agent lock
Invalidate owner broker sessions and all active grants
text
Examples:
pn agent lock --json
Exit codes: 0 success. Service tokens remain independently usable.pn agent enroll
Enroll a new named AI agent identity
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
<name> | 是 | — | Agent short name (e.g. claude, codex, ci-runner) |
text
Examples:
pn agent enroll claude --json
Save the enrollment key once, pass it as PASSNO_AGENT_KEY with --agent <name>. Exit codes: 0 success, 2 duplicate/invalid name.pn agent ls
List enrolled AI agent identities
text
Examples:
pn agent ls --json
Exit codes: 0 success.pn agent revoke
Revoke an active AI agent identity by name or ag_... ID
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
<target> | 是 | — | Agent name or ID |
text
Examples:
pn agent revoke claude --json
Exit codes: 0 success, 5 unknown agent.pn agent revoke-all
Revoke all active AI agent identities and kill active grants
text
Examples:
pn agent revoke-all --json
Exit codes: 0 success. Service tokens are revoked separately.pn agent audit
Inspect or cryptographically verify the hash-chained agent audit log
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
--verify | 否 | — | Verify hash chain linkage and detect tampering |
--limit | 否 | — | Show at most the latest N audit entries |
text
Examples:
pn agent audit --verify --json
pn agent audit --limit 20 --json
Exit codes: 0 valid, 8 tampered log.pn agent setup
Configure MCP server & SKILL.md for Claude Code, Codex, or Antigravity (agy)
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
<target> | 是 | — | Agent client target (claude, codex, agy) |
--agent | 否 | — | Enrolled owner identity (defaults to the target client name) |
--config-dir | 否 | — | Override target configuration directory (prevents modifying user globals) |
--dry-run | 否 | — | Preview planned changes without writing files |
--print | 否 | — | Print generated config and SKILL.md to stdout |
--passno-bin | 否 | — | Override pn binary path recorded in MCP config (defaults to current executable) |
text
Examples:
pn agent setup claude --config-dir /tmp/demo-claude --dry-run --json
pn agent setup codex --config-dir /tmp/demo-codex --json
pn agent setup agy --config-dir /tmp/demo-agy --json
Without --config-dir, Claude Code is registered at user scope via `claude mcp add`; with --config-dir an mcp.json is written for `claude --mcp-config`. Codex credential tools use passno approval, without a second client prompt. Exit codes: 0 success, 2 malformed existing config.pn agent token
Issue, list, or revoke unattended sub-vault service tokens (pnst_v1_...)
pn agent reveal
Tier 5 exception: one-time explicit reveal for items with allow_plaintext_exception = true
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
<pn_ref> | 是 | — | Credential reference (pn://vault/item/field) |
--reason | 是 | — | Human-readable audit reason |
--agent | 否 | cli-agent | Calling agent name |
text
Examples:
pn agent reveal pn://Agent/item/password --reason 'explicit exception' --agent claude --json
Requires per-item opt-in and fresh approval; simulated default never allows reveal. Exit codes: 0 revealed, 3 locked, 4 denied, 8 policy denied.text
Examples:
pn agent enroll claude --json
pn agent token create --vault Agent --read-only --ttl 30d --json
pn agent audit --verify --json
pn agent setup claude --dry-run
Exit codes: 0 success, 2 usage error, 4 denied, 6 pending approval, 8 tamper/policy denied.pn agent grants
List grants, or revoke one by ID
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
--revoke | 否 | — |
text
Examples:
pn agent grants --json
pn agent grants --revoke gr_... --json
Exit codes: 0 success, 5 unknown grant.pn agent lock
Invalidate owner broker sessions and all active grants
text
Examples:
pn agent lock --json
Exit codes: 0 success. Service tokens remain independently usable.pn agent enroll
Enroll a new named AI agent identity
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
<name> | 是 | — | Agent short name (e.g. claude, codex, ci-runner) |
text
Examples:
pn agent enroll claude --json
Save the enrollment key once, pass it as PASSNO_AGENT_KEY with --agent <name>. Exit codes: 0 success, 2 duplicate/invalid name.pn agent ls
List enrolled AI agent identities
text
Examples:
pn agent ls --json
Exit codes: 0 success.pn agent revoke
Revoke an active AI agent identity by name or ag_... ID
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
<target> | 是 | — | Agent name or ID |
text
Examples:
pn agent revoke claude --json
Exit codes: 0 success, 5 unknown agent.pn agent revoke-all
Revoke all active AI agent identities and kill active grants
text
Examples:
pn agent revoke-all --json
Exit codes: 0 success. Service tokens are revoked separately.pn agent audit
Inspect or cryptographically verify the hash-chained agent audit log
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
--verify | 否 | — | Verify hash chain linkage and detect tampering |
--limit | 否 | — | Show at most the latest N audit entries |
text
Examples:
pn agent audit --verify --json
pn agent audit --limit 20 --json
Exit codes: 0 valid, 8 tampered log.pn agent setup
Configure MCP server & SKILL.md for Claude Code, Codex, or Antigravity (agy)
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
<target> | 是 | — | Agent client target (claude, codex, agy) |
--agent | 否 | — | Enrolled owner identity (defaults to the target client name) |
--config-dir | 否 | — | Override target configuration directory (prevents modifying user globals) |
--dry-run | 否 | — | Preview planned changes without writing files |
--print | 否 | — | Print generated config and SKILL.md to stdout |
--passno-bin | 否 | — | Override pn binary path recorded in MCP config (defaults to current executable) |
text
Examples:
pn agent setup claude --config-dir /tmp/demo-claude --dry-run --json
pn agent setup codex --config-dir /tmp/demo-codex --json
pn agent setup agy --config-dir /tmp/demo-agy --json
Without --config-dir, Claude Code is registered at user scope via `claude mcp add`; with --config-dir an mcp.json is written for `claude --mcp-config`. Codex credential tools use passno approval, without a second client prompt. Exit codes: 0 success, 2 malformed existing config.pn agent token
Issue, list, or revoke unattended sub-vault service tokens (pnst_v1_...)
pn agent token create
Create a scoped service token wrapping only one sub-vault's current epoch key
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
--vault | 是 | — | Target sub-vault name |
--read-only | 否 | — | Restrict token to read-only operations (default: read-only unless --read-write) |
--read-write | 否 | — | Permit writing generated/new items into this sub-vault |
--ttl | 否 | 30d | Lifetime duration (30d, 12h, 15m, 600s; default 30d) |
--label | 否 | agent-service-token | Human label identifying this token |
text
Examples:
pn agent token create --vault Agent --read-only --ttl 30d --password-stdin --json
Returns the token once. Exit codes: 0 success, 2 invalid TTL, 3 owner locked, 5 unknown vault.pn agent token ls
List recorded service tokens (metadata only; secrets never stored or shown)
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
--vault | 否 | — | Filter by sub-vault name |
text
Examples:
pn agent token ls --vault Agent --json
Returns metadata only. Exit codes: 0 success.pn agent token revoke
Revoke a service token and immediately rotate that sub-vault's epoch key
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
<token_id> | 是 | — | Token ID (tok_... UUID) |
--vault | 是 | — | Sub-vault name owning the token |
text
Examples:
pn agent token revoke TOKEN_ID --vault Agent --password-stdin --json
Rotates the vault epoch and invalidates all old-epoch tokens. Exit codes: 0 success, 3 owner locked, 4 unknown/revoked token.pn agent reveal
Tier 5 exception: one-time explicit reveal for items with allow_plaintext_exception = true
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
<pn_ref> | 是 | — | Credential reference (pn://vault/item/field) |
--reason | 是 | — | Human-readable audit reason |
--agent | 否 | cli-agent | Calling agent name |
text
Examples:
pn agent reveal pn://Agent/item/password --reason 'explicit exception' --agent claude --json
Requires per-item opt-in and fresh approval; simulated default never allows reveal. Exit codes: 0 revealed, 3 locked, 4 denied, 8 policy denied.pn run
Execute a command with pn:// credentials injected into child environment variables only
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
--reason | 是 | — | Human-readable audit reason explaining why credentials are needed |
--env | 否 | — | Inject environment variable from credential reference: NAME=pn://vault/item/field (repeatable) |
--env-file | 否 | — | Read NAME=pn://... lines from a file (# comments; $VAR / ${VAR} in references come from your environment). Repeatable; --env entries win over the same name |
--stdin | 否 | — | Write one secret to the command's standard input (followed by a newline), never to argv or the environment, e.g. for docker login --password-stdin |
--file | 否 | — | Write a secret (a field, or an attachment by file name) to a private 0600 temporary file deleted when the command exits; NAME is set to its path (repeatable) |
--wait | 否 | — | Optional timeout in seconds before killing child process |
--agent | 否 | cli-agent | Calling agent identifier |
<command> | 是 | — | Command and arguments to execute (after --) |
text
Examples:
pn run --reason 'deploy staging' --env DB_PASSWORD=pn://Agent/staging-db/password -- ./deploy.sh
APP_ENV=staging pn run --reason 'deploy' --env-file deploy.env -- ./deploy.sh
pn run --reason 'registry login' --stdin pn://Agent/registry/password -- docker login --username ci --password-stdin registry.example.com
pn run --reason 'gh login' --stdin pn://Agent/github/token -- gh auth login --with-token
pn run --reason 'kubectl' --file KUBECONFIG=pn://Agent/cluster/kubeconfig.yaml -- kubectl get pods
Env file (deploy.env):
# one NAME=reference per line; $VAR / ${VAR} come from your environment
DB_PASSWORD=pn://Agent/db-$APP_ENV/password
How secrets reach the command:
--env and --env-file set environment variables; --stdin writes one value to its standard input; --file writes a private 0600 file (in a 0700 directory under $PASSNO_HOME/agent/run-files) and sets NAME to its path. Files are deleted when the command exits or fails; leftovers from a killed process are removed by the next run. Every reference is approved for this exact command (same tier as --env); output is redacted.
Exit codes: the command's exit code (124 on timeout); 2 invalid input, 3 locked, 4 denied, 5 item or field not found, 6 approval pending.pn http
Send an HTTP request or run the local HTTP injection proxy substituting {{pn://...}}
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
--reason | 否 | — | Human-readable audit reason (required for one-shot requests) |
--method | 否 | GET | HTTP method |
--url | 否 | — | Target http:// or https:// URL |
-H, --header | 否 | — | HTTP header in Key: Value form (may contain {{pn://...}} placeholders) |
--data | 否 | — | Optional HTTP request body (may contain {{pn://...}} placeholders) |
--agent | 否 | cli-agent | Calling agent identifier |
--serve | 否 | — | Run a local HTTP injection proxy server instead of a single request |
--listen | 否 | 127.0.0.1:18421 | Listen address for --serve |
text
Examples:
pn http --url http://127.0.0.1:9000/v1/items -H 'Authorization: Bearer {{pn://Agent/api/token}}' --reason 'fetch items' --json
pn http --serve --listen 127.0.0.1:18421
Exit codes: 0 success, 2 invalid input, 4 denied, 7 upstream error.pn fill
Fill (and optionally submit) a website's login form in the owner's Chrome, through the passno extension
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
--reason | 是 | — | Human-readable audit reason |
--item | 是 | — | The login: pn://vault/item, title or id |
--url | 是 | — | URL of the page to fill (open in Chrome) |
--submit | 否 | — | Also submit the form after filling |
--agent | 否 | cli-agent | Calling agent identifier |
text
Examples:
PASSNO_AGENT_KEY=... pn fill --agent claude --item pn://Agent/GitHub --url https://github.com/login --reason 'check CI' --json
pn fill --agent claude --item GitHub --url https://github.com/login --submit --reason 'sign in'
The owner approves it like any agent use (tier: fill a web page). The item's URL must match the page, which must be open in Chrome with the passno extension. The agent learns only {filled, submitted, detail} (detail: no_tab, no_form, refused, locked, timeout); the username and password go from passnod to the extension, never to the agent. An agent that can run script in that page could still read what was filled.
Exit codes: 0 filled, 1 not filled (see detail), 2 usage error, 3 locked or not authenticated, 4 denied, 7 daemon unavailable, 8 policy denied (wrong site).pn ssh-agent
Run an Ed25519 SSH agent Unix socket (sign-only, never exports private keys)
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
--socket | 否 | — | Unix socket path (Windows: named pipe such as \.\pipe\passno-ssh-agent-…) for SSH_AUTH_SOCK |
--reason | 否 | ssh authentication session | Audit reason recorded for SSH sign approvals |
--agent | 否 | cli-agent | Calling agent identifier |
text
Only unencrypted Ed25519 keys are advertised and signed. RSA, ECDSA and passphrase-encrypted keys stay in the vault but are skipped.
Examples:
pn ssh-agent --socket /tmp/passno-ssh.sock --reason 'git operations'
Exit codes: 0 success, 3 vault locked.pn mcp
Start the Model Context Protocol (MCP) stdio server for AI agents
| 参数 / 选项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
--agent | 否 | mcp-agent | Agent identity recorded in audit logs for MCP tool calls |
text
Examples:
PASSNO_SERVICE_TOKEN=pnst_v1_... pn mcp
Exit codes: 0 clean EOF, 3 vault locked.