Command reference

All command-line operations run through paw cli.

paw cli <COMMAND> [OPTIONS] [ARGUMENTS]

Item path syntax

Commands that manipulate items use a hierarchical path:

VAULT/TYPE/NAME

VAULT: The name of the vault (for example, Personal).
TYPE: One of four supported item types:
- login
- password
- note
- ssh_key
NAME: The title or identifier of the item (for example, github.com).

Commands that modify an unlocked vault accept the --session flag. If the PAW_SESSION environment variable is defined, Paw uses it automatically.

Vault operations

`init`

Initializes a new local vault. Paw prompts you to enter and confirm the master password.

paw cli init <VAULT>

`unlock`

Unlocks a vault and prints an active session ID. Requires the Paw agent to be running.

paw cli unlock [OPTIONS] <VAULT>

Option	Alias	Description
`--lifetime <DURATION>`	`-t`	Maximum session lifetime (for example, `1h`, `30m`). Defaults to `0` (no expiration).

`lock`

Locks an active vault session.

paw cli lock <VAULT>

Listing and inspecting items

`ls`

Lists vaults, categories, or items.

paw cli ls [PATH]

paw cli ls: Lists all local vaults.
paw cli ls Personal: Lists all items in the Personal vault.
paw cli ls Personal/login: Lists all logins in the Personal vault.

`show`

Displays the details of a specific item.

paw cli show [OPTIONS] <VAULT/TYPE/NAME>

Option	Alias	Description
`--clip`	`-c`	Copies the secret (password or private key) to the clipboard instead of printing it to standard output.
`--session <ID>`		Specifies the active session ID.

Modifying items

`add`

Adds a new item to the vault. Paw interactively prompts for the required fields.

paw cli add [OPTIONS] <VAULT/TYPE/NAME>

Option	Alias	Description
`--input <FILE>`	`-i`	Imports an SSH key directly from an OpenSSH or PEM key file (used with `ssh_key` type).
`--session <ID>`		Specifies the active session ID.

`edit`

Edits an existing item. Paw interactively prompts for updated values.

paw cli edit [OPTIONS] <VAULT/TYPE/NAME>

Option	Description
`--session <ID>`	Specifies the active session ID.

`rm`

Removes an item from the vault.

paw cli rm [OPTIONS] <VAULT/TYPE/NAME>

Option	Description
`--session <ID>`	Specifies the active session ID.

Item history

Paw saves up to 10 previous revisions of an item whenever changes are saved.

`history list`

Lists all recorded revisions for an item, showing the revision index, modification timestamp, and size. Index 0 is the most recent past revision.

paw cli history list <VAULT/TYPE/NAME>

(You can also run paw cli history <VAULT/TYPE/NAME> directly.)

`history show`

Displays the contents of a historical revision.

paw cli history show <VAULT/TYPE/NAME> <INDEX>

`history restore`

Restores an earlier revision as the current item value. The current version is preserved in history before replacing it.

paw cli history restore <VAULT/TYPE/NAME> <INDEX>

Attachments

`attachment add`

Attaches a local file to an item.

paw cli attachment add <VAULT/TYPE/NAME> <FILE_PATH>

`attachment list`

Lists all files attached to an item, including each attachment’s unique ID, filename, and decrypted size.

paw cli attachment list <VAULT/TYPE/NAME>

`attachment save`

Downloads and decrypts an attached file to the specified destination path.

paw cli attachment save <VAULT/TYPE/NAME> <FILE_ID> --output <DESTINATION_PATH>

`attachment remove`

Permanently removes an attachment from an item.

paw cli attachment remove <VAULT/TYPE/NAME> <FILE_ID>

Password generation

`pwgen`

Interactively generates a password, passphrase, or PIN without requiring an unlocked vault.

paw cli pwgen

Follow the prompts to choose the password style and options. Paw prints the generated password directly to standard output.

Backup and restore

`export`

Exports vault credentials to a file.

paw cli export [OPTIONS] <VAULT> <DESTINATION>

Option	Description
`--encrypted`	Exports credentials to a password-protected `.cxf.age` file (default). Attachments are not included.
`--paw`	Exports a complete `.paw` archive containing credentials, item history, and file attachments.
`--plaintext`	Exports unencrypted `.cxf` data. Paw requires explicit confirmation before exporting plaintext.
`--session <ID>`	Specifies the active session ID.

`restore`

Restores a .paw, .cxf.age, or .cxf backup file into a new vault. It does not overwrite an existing vault.

paw cli restore [OPTIONS] <BACKUP_FILE>

Option	Description
`--name <NAME>`	Specifies the name for the restored vault. If omitted, Paw prompts for a name.

Agent management

`agent start`

Starts the background Paw agent. Leave this command running in a dedicated terminal or service manager.

paw cli agent start

`agent sessions`

Lists all currently active vault sessions held by the agent.

paw cli agent sessions

General options

`version`

Prints the current version of the Paw binary.

paw cli version