# CLI reference

> Every probarion CLI command and option, with required flags, defaults, who signs each printed transaction, its gas and deposit, and the exit codes.

Every command and option of the probarion CLI, with who signs what each command prints. The CLI never signs: it prints a near-cli-rs command for the owner or an approver to sign.

Status: Live · Network: Testnet and Mainnet · Reviewed: 2026-11-11 · Built from: 4ab41ca1436589c22073fa842ee46f970415e3d5

Canonical page: https://probarion.xyz/docs/build/cli-reference

The `probarion` CLI dry-runs a spend, verifies a vault, exports the ledger, generates keys and prints the transactions that a vault's owner and approvers sign. It signs nothing itself: for each owner or approver call it checks your input against the contract's rules, writes the arguments to a file and prints the near-cli-rs command for that person to sign. The tables below list every command and option of the CLI, version 0.1.1, the release on npm, as `packages/cli/src/program.ts` builds it, and a test fails when the code gains or loses a command or an option that they do not list.

## How to read the tables

Each table holds one command group, and each row one command. A row's anchor is its command with `cli-` in front and hyphens for spaces: `vault create` is at [`#cli-vault-create`](#cli-vault-create).

- **Command** is what follows the program name. Only `help` takes a positional argument, the command whose help it prints: every other input is an option. In your own project folder, run a command as `npx probarion vault create ...`, or as `probarion vault create ...` after `npm install -g probarion`. In a clone of the repository, run the CLI the clone builds, as `node packages/cli/dist/bin.js vault create ...`. [Install the packages](https://probarion.xyz/docs/build/install.md) has both.
- **Options** lists every option of the command, spelled as the CLI's help spells it. "(required)" means the command stops with an error without that option. "(default `x`)" is the value the option takes when you leave it out. Every command but `help` also takes `--help`.
- **Who signs** names the account whose wallet signs the printed near-cli-rs command, with the prepaid gas and the deposit that command attaches. "Nothing" means the command prints no transaction.

The placeholders in the options mean:

- `<usdc>`: an amount in USDC with up to 6 decimals, so `--amount 25` is 25 USDC.
- `<near>`: an amount in NEAR with up to 24 decimals.
- `<id>`: after `--vault`, a NEAR account id. After `--mandate` or `--spend`, a whole number: ids start at 1.
- `<pk>`: an ed25519 public key, written `ed25519:...`.
- `<account>`: a NEAR account id. `<list>`: account ids separated by commas.

Three options recur. `--vault <id>` falls back to `PROBARION_VAULT_ID`, and every command that has the option needs one of the two, except `verify --offline`, which refuses it. `--sign-as <account>` writes the signer into the printed command. Without it, the command holds a placeholder such as `<owner-account-id>`, which the shell refuses as pasted. `--out-dir <dir>` is the folder for the arguments file. [Configure](https://probarion.xyz/docs/build/install.md#configure) lists every environment variable the CLI reads.

## Program options

These options belong to the program, not to one command, so each appears here and in no command row. They can come before the command words, as in `npx probarion --network testnet vault freeze --vault <vault>`, or after them. NEAR testnet is live today. On mainnet one small vault runs, `v0.probarion.near`, and no mainnet factory is deployed: see [Testnet and mainnet](https://probarion.xyz/docs/start/testnet-and-mainnet.md).

| Option | When not given | What it does |
| - | - | - |
| `--network <network>` | `NEAR_NETWORK`, else `testnet` | The network, `mainnet` or `testnet`. Any other value is an error. A printed call carries it as `network-config`. `agent keygen` and `ledger export` do not read it, and `verify --offline` refuses it. |
| `--rpc <urls>` | `NEAR_RPC_URLS`, else the network's default RPCs | Comma-separated NEAR RPC URLs. Only the commands that read the chain use them: `vault create`, `check` and `verify`. An empty list is an error, and `verify --offline` refuses it. |
| `-V`, `--version` | None | Prints the CLI's version, `0.1.1`, and exits 0. |
| `-h`, `--help` | None | Prints the help of the program, or of the command it follows, and exits 0. The help of `check` and `verify` also lists their exit codes. |

## What a signing command prints

> **Owner signs**
>
> The command in this section prints a call for the owner to sign. Review the arguments file and its sha256 first, then sign with your own wallet, keychain or Ledger.
>
> _The owner signs this transaction. Probarion never signs it._

Run in your own project folder, this command prints the `revoke_mandate` call for mandate 1 of an illustrative testnet vault. It reads nothing from the chain, and it writes the arguments file into the folder:

```bash
npx probarion --network testnet mandate revoke --vault acme.vaults.probarion.testnet --mandate 1
```

```text
OWNER SIGNS: probarion never signs owner or approver transactions. Review the arguments, then sign with your own wallet or near-cli-rs:

near contract call-function as-transaction acme.vaults.probarion.testnet revoke_mandate file-args ./revoke_mandate.0a38f6055d2b.args.json prepaid-gas '30.0 Tgas' attached-deposit '1 yoctoNEAR' sign-as <owner-account-id> network-config testnet sign-with-keychain send
sha256 of the args file: 0a38f6055d2b1a7cf20555fde86bb075f5aee4957da14266e1982f4ed8200069  (check: sha256sum ./revoke_mandate.0a38f6055d2b.args.json, or Get-FileHash -Algorithm SHA256 ./revoke_mandate.0a38f6055d2b.args.json in PowerShell)
Run it in bash, zsh or PowerShell (not cmd.exe).

revoke_mandate arguments (./revoke_mandate.0a38f6055d2b.args.json):
{
  "mandate_id": 1
}

Pending spends keep their reservation until they settle or fail; approve then refuses with MandateInactive.

With a Ledger hardware wallet, replace `sign-with-keychain send` with `sign-with-ledger usb send`.
```

Every command that prints a call prints these parts:

- **Who signs.** The first line starts with `OWNER SIGNS` or, for `spend approve` and `spend reject`, `APPROVER SIGNS`.
- **The arguments file**, named `<method>.<the first 12 hex of its sha256>.args.json`. The name follows the content, so a command you printed earlier keeps pointing at the arguments you reviewed. The CLI refuses to print over a file of that name whose content differs.
- **The sha256 of that file**, to check before you sign, with `sha256sum` or, in PowerShell, `Get-FileHash`.
- **The near-cli-rs command.** It ends with `sign-with-keychain send`, and runs in bash, zsh or PowerShell, not in cmd.exe.
- **A note** on what the call does once signed, from the same rules as the table's "What it does".

Before it prints, the CLI checks your input against the contract's rules. An input it refuses stops it with `error:` on stderr and exit code 1, and it writes no file.

## Vault commands

> **Owner signs**
>
> Every vault command prints a call the owner signs. [Vaults, roles and keys](https://probarion.xyz/docs/concepts/vaults-roles-and-keys.md) explains the owner's role.
>
> _The owner signs this transaction. Probarion never signs it._

| Command | Options | What it does | Who signs |
| - | - | - | - |
| `vault create` | `--name <name>` (required), `--approvers <list>` (required), `--daily-backstop <usdc>` (default `500`), `--held-ttl-hours <hours>` (default `72`), `--deposit <near>`, `--sign-as <account>`, `--out-dir <dir>` (default `.`) | Reads the factory's current version and `min_deposit`, then prints the factory's `create_vault` call for the vault `<name>.<factory>`. The name is 2 to 31 characters of `a-z`, `0-9`, `_` and `-`, starts with a letter or digit, and must make `<name>.<factory>` a valid NEAR account id: at most 64 characters in all, no `-` or `_` at the end of the name, and never two of them in a row. It takes 1 to 10 distinct approvers. The daily backstop is the most the vault reserves or pays in one UTC day, and a hold lasts 1 to 720 hours. `--deposit` is required when the factory's current version is embedded. The factory is `PROBARION_FACTORY_ID`, else the network's. | The owner: the account that signs becomes the vault's owner. `300.0 Tgas`, and a deposit of `--deposit` NEAR, else the factory's `min_deposit`, which stays in the vault for storage and gas. |
| `vault freeze` | `--vault <id>`, `--sign-as <account>`, `--out-dir <dir>` (default `.`) | Prints the vault's `freeze` call. Until `unfreeze`, the vault refuses every new spend and every approve. `reject` and `expire_held` still work. | The owner. `30.0 Tgas` and no deposit, so a full-access key, or a function-call key of the owner's account that may call this vault, can sign it. |
| `vault unfreeze` | `--vault <id>`, `--sign-as <account>`, `--out-dir <dir>` (default `.`) | Prints the vault's `unfreeze` call, which lets spends and approvals run again. | The owner. `30.0 Tgas` and `1 yoctoNEAR`, so only a full-access key, through a wallet prompt, can sign it. |
| `vault withdraw` | `--vault <id>`, `--amount <usdc>` (required), `--sign-as <account>`, `--out-dir <dir>` (default `.`) | Prints the vault's `withdraw` call, which sends native USDC from the vault to the vault owner's account and nowhere else. | The owner. `100.0 Tgas` and `1 yoctoNEAR`. |
| `vault withdraw-intents` | `--vault <id>`, `--token <token>` (required), `--amount <usdc>` (required), `--sign-as <account>`, `--out-dir <dir>` (default `.`) | Prints the vault's `withdraw_intents` call: the intents contract sends the vault's USDC balance inside NEAR Intents to the owner's account and nowhere else. `--token` is `base`, `solana` or one of the network's two allowed USDC asset ids. | The owner. `150.0 Tgas` and `1 yoctoNEAR`. |

## Mandate commands

> **Owner signs**
>
> Both mandate commands print a call the owner signs. A mandate has no edit call: to change one, revoke it and create a new one. [Mandates](https://probarion.xyz/docs/concepts/mandates.md) explains each limit.
>
> _The owner signs this transaction. Probarion never signs it._

| Command | Options | What it does | Who signs |
| - | - | - | - |
| `mandate create` | `--vault <id>`, `--payee <payee>` (required), `--max-per <usdc>` (required), `--max-total <usdc>` (required), `--uses <n>` (required), `--expires <date>` (required), `--approval-above <usdc>` (required), `--agent-pk <pk>` (required), `--purpose <file\|hex>` (required), `--label <label>` (required), `--deposit <near>` (default `0.05`), `--sign-as <account>`, `--out-dir <dir>` (default `.`) | Prints the vault's `create_mandate` call. The payee is `near:<account>`, `base:<0x address>` or `solana:<address>`, never the vault itself, and it never changes. `--max-per` is above 0 and at most `--max-total`, and `--uses` is 1 to 4294967295. `--expires` is a future `YYYY-MM-DD`, meaning the end of that UTC day, or an ISO-8601 time with its zone. Spends above `--approval-above` are held for an approver. `--purpose` is a file the CLI hashes with sha256, or the 64-hex hash. `--label` is at most 64 bytes. Only the `--agent-pk` key may spend against the mandate. | The owner. `100.0 Tgas`, and a deposit of `--deposit` NEAR, of which the vault refunds the excess. |
| `mandate revoke` | `--vault <id>`, `--mandate <id>` (required), `--sign-as <account>`, `--out-dir <dir>` (default `.`) | Prints the vault's `revoke_mandate` call. Pending spends keep their reservation until they settle or fail, and `approve` then refuses them with `MandateInactive`. | The owner. `30.0 Tgas` and `1 yoctoNEAR`. |

## Agent commands

> **Owner signs**
>
> `agent add` and `agent remove` print a call the owner signs. [Vaults, roles and keys](https://probarion.xyz/docs/concepts/vaults-roles-and-keys.md) explains the agent key.
>
> _The owner signs this transaction. Probarion never signs it._

| Command | Options | What it does | Who signs |
| - | - | - | - |
| `agent keygen` | `--json`, `--out <file>`, `--print-secret` | Generates an ed25519 key pair on this machine. It needs `--out` or `--print-secret`, not both. `--out` saves the pair to a new file, owner-only where the system enforces file modes, and prints only the public key. It warns on Windows, and when the file is inside a git repository. `--print-secret` prints the secret key to the terminal. `--json` prints JSON. | Nothing: no transaction. Give the public key to the owner for `agent add` or `ledger set-key`. |
| `agent add` | `--vault <id>`, `--pk <pk>` (required), `--allowance <near>` (default `1`), `--label <label>` (default `agent`), `--sign-as <account>`, `--out-dir <dir>` (default `.`) | Prints the vault's `add_agent` call: the vault adds a function-call key to itself that may call only `spend` and never attaches a deposit. The allowance is the key's gas allowance, above 0, and the label is at most 64 bytes. A vault holds at most 16 agent keys, and a key cannot be both an agent key and the ledger key. | The owner. `30.0 Tgas` and `1 yoctoNEAR`. |
| `agent remove` | `--vault <id>`, `--pk <pk>` (required), `--sign-as <account>`, `--out-dir <dir>` (default `.`) | Prints the vault's `remove_agent` call: the vault deletes the agent's key, so it can sign no further spends. Spends already held still wait for an approver. | The owner. `30.0 Tgas` and `1 yoctoNEAR`. |

## Ledger commands

> **Owner signs**
>
> `ledger set-key` prints a call the owner signs. [The ledger and anchors](https://probarion.xyz/docs/concepts/ledger-and-anchors.md) explains what the ledger key signs.
>
> _The owner signs this transaction. Probarion never signs it._

| Command | Options | What it does | Who signs |
| - | - | - | - |
| `ledger set-key` | `--vault <id>`, `--pk <pk>` (required), `--allowance <near>` (default `0.25`), `--sign-as <account>`, `--out-dir <dir>` (default `.`) | Prints the vault's `set_ledger_key` call: a function-call key that may call only `anchor`. It replaces the previous ledger key, so anchor the ledger before you rotate. The key must not already be an agent key, and the allowance is above 0. | The owner. `30.0 Tgas` and `1 yoctoNEAR`. |
| `ledger export` | `--out <file>` (required), `--ledger <path>` | Copies the ledger to a new file as JSONL, one entry per line, and prints how many entries it wrote. It refuses an `--out` file that exists or is the ledger itself, and a ledger file that does not exist. `--ledger` falls back to `PROBARION_LEDGER_PATH`, else `.probarion/ledger.jsonl`. | Nothing: read-only. It writes only the new file. |

## Spend commands

> **Approver signs**
>
> `spend approve` and `spend reject` print a call for an account in the vault's approver list to sign. The list decides, not the owner role: the owner can approve only when the list names it. One approver's call is enough. [Find the held spend](https://probarion.xyz/docs/concepts/holds-and-approvals.md#find-the-held-spend) shows how to get the id that `--spend` takes.
>
> _An approver signs this transaction. Probarion never signs it._

| Command | Options | What it does | Who signs |
| - | - | - | - |
| `spend approve` | `--vault <id>`, `--spend <id>` (required), `--sign-as <account>`, `--out-dir <dir>` (default `.`) | Prints the vault's `approve` call for a held spend, which pays the mandate's payee. It works until the hold expires, and the vault refuses it while frozen. | An approver. `150.0 Tgas` and `1 yoctoNEAR`. |
| `spend reject` | `--vault <id>`, `--spend <id>` (required), `--sign-as <account>`, `--out-dir <dir>` (default `.`) | Prints the vault's `reject` call for a held spend, which releases its reservation and its invoice hash. The ref stays used. | An approver. `30.0 Tgas` and `1 yoctoNEAR`. |

## The check command

`check` is the dry run of a spend: it asks the vault whether its own spend checks would pass. [How a payment is checked](https://probarion.xyz/docs/concepts/payment-checks.md) lists the checks, and [Errors](https://probarion.xyz/docs/build/errors.md) explains each `PROBARION:<Code>` it can print.

| Command | Options | What it does | Who signs |
| - | - | - | - |
| `check` | `--vault <id>`, `--mandate <id>` (required), `--amount <usdc>` (required), `--invoice <file>` (required), `--ref <ref>` (required), `--agent-pk <pk>`, `--json` | Asks the vault's free `check_spend` view whether it would accept this spend. It prints `OK: the vault would accept this spend`, with `and hold it for an approver` when the vault would hold it, or `REFUSED: PROBARION:<Code>`. The invoice is the extracted invoice text, a UTF-8 file, hashed the way the SDK hashes it. The ref is 1 to 64 bytes. It checks as `--agent-pk`, else as the public key of `PROBARION_AGENT_KEY`, else as the mandate's agent. `--json` prints the request, the signer and the verdict. | Nothing: read-only. A free view call: nothing is signed or sent. |

## The verify command

`verify` runs the verifier's nine checks against the chain, or against a saved snapshot. [Verifier checks a to i](https://probarion.xyz/docs/trust/verifier-checks.md) says what each check proves, and [Verify a vault yourself](https://probarion.xyz/docs/trust/verify-a-vault.md) walks through a run on a live vault.

| Command | Options | What it does | Who signs |
| - | - | - | - |
| `verify` | `--vault <id>`, `--online`, `--snapshot <out>`, `--offline <file>`, `--json`, `--ledger <path>`, `--evidence <dir>` (default `docs/evidence`), `--archival-rpc <urls>`, `--burn-tx <spend_id=hash[@signer]>` (repeatable), `--proof <file>`, `--invoice <file>` (repeatable), `--invoices <dir>` (repeatable), `--system-prompt <file>` (repeatable) | Runs checks a to i on the vault's chain state and its ledger file, and prints one row per check, the counts and a `RESULT` line, or the report as JSON with `--json`. `--offline` verifies a saved snapshot with no network, and refuses every option that would shape one. `--snapshot` saves the snapshot it verified to a new file. `--online` adds O1 and O2 and FastNEAR's tx index. `--burn-tx`, `--proof` and `--archival-rpc` help check h find a burn. `--evidence` is read for `v0.probarion.near` on mainnet only. `--invoice` and `--invoices` (every `.txt` file of a folder) add A8 to check e, live or with `--offline`: invoice texts you hold, read on your machine and matched to the ledger by sha256. A8 accepts the standard system prompt; `--system-prompt` adds another one, the prompt's exact text, for a decision made under it. Release 0.1.1 on npm does not have these three. | Nothing: read-only. |

## The help command

Commander, the CLI's argument parser, adds `help` to the program and to each command group on its own: no file in `packages/cli/src/commands` defines it.

| Command | Options | What it does | Who signs |
| - | - | - | - |
| `help [command]` | None | Prints the help of the command it names, or of the program when it names none, as `--help` does: `help verify` prints what `verify --help` prints. Each group has its own for the commands in it: `vault help`, `mandate help`, `agent help`, `ledger help` and `spend help`, so `vault help create` prints the help of `vault create`. | Nothing: no transaction. |

## Exit codes

`check` and `verify` give their result as the exit code, so a usage error of theirs exits 64 rather than 1, and a script can tell a refusal or a failed check from a mistyped flag.

| Code | check | verify | Every other command |
| - | - | - | - |
| `0` | The vault would accept the spend. It may hold it for an approver. | No check fails or is UNPROVEN. A skipped check still exits 0: check i skips a vault that names no factory. | Done: the command printed its transaction, its key, its help or its version, or wrote its file. |
| `1` | The vault would refuse the spend, or the check could not run: `error:` on stderr. | A check fails, which always wins over unproven, or verify could not run: `error:` on stderr and no `RESULT` line. | An error: a bad value, a missing or unknown option, or a file the command refuses. The message is on stderr. |
| `2` | None | No check fails, but at least one is UNPROVEN: its row names the spends and what to supply. | None |
| `64` | A usage error: a missing, malformed or conflicting flag, an `--invoice` file that is not UTF-8 text, or a `PROBARION_AGENT_KEY` that is not an ed25519 secret key. | A usage error: a missing, malformed or conflicting flag, a `--snapshot` file that exists or is the ledger, an `--offline` snapshot whose `vault`, `network` or `taken_at` is malformed, an `--invoices` folder that cannot be read or holds no `.txt` file, or an invoice or `--system-prompt` file that cannot be read or is not UTF-8 text. | None |

## What the tables do not cover

- **The calls themselves.** The contract methods behind each printed call, with their arguments and the checks they run, are on [Contract reference](https://probarion.xyz/docs/build/contract-reference.md). The vault's own limits, such as its 10 approvers and 16 agent keys, are on [Limits and costs](https://probarion.xyz/docs/build/limits-and-costs.md).
- **The meaning of a result.** A refusal code is on [Errors](https://probarion.xyz/docs/build/errors.md), and a verifier row on [Verifier checks a to i](https://probarion.xyz/docs/trust/verifier-checks.md).
- **The CLI as a library.** The `probarion` package also exports `runCli` and `buildProgram`, which this page does not document. Code that pays from an agent uses the SDK: see [SDK reference](https://probarion.xyz/docs/build/sdk-reference.md).
- **Signing.** The CLI never runs near-cli-rs. You sign with your own wallet, and nothing the CLI prints is sent until you run it.