Skip to content

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-agentEnrolled 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否100Show 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.

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否randomGenerator 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否skipDuplicate 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否PersonalDisplay 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否mainGit branch name when configuring --git
--auto-sync否—Mark automatic periodic sync enabled for daemon/scheduler hooks
--interval否60Periodic 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否PersonalDisplay 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否mainGit branch name when configuring --git
--auto-sync否—Mark automatic periodic sync enabled for daemon/scheduler hooks
--interval否60Periodic 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否60Periodic 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否60Periodic 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-agentCalling 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否30dLifetime duration (30d, 12h, 15m, 600s; default 30d)
--label否agent-service-tokenHuman 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-agentCalling 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-agentCalling 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否GETHTTP method
--url否—Target http:// or https:// URL
-H, --header否—HTTP header in Key: Value form (may contain &#123;&#123;pn://...}} placeholders)
--data否—Optional HTTP request body (may contain &#123;&#123;pn://...}} placeholders)
--agent否cli-agentCalling agent identifier
--serve否—Run a local HTTP injection proxy server instead of a single request
--listen否127.0.0.1:18421Listen 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-agentCalling 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 sessionAudit reason recorded for SSH sign approvals
--agent否cli-agentCalling 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-agentAgent 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.

文档对应提交 56d1c45 · 由仓库 docs/ 自动生成