CLI reference · Catena Docs

This reference covers the public commands in @catena/cli 0.19.0, and we generate it from the CLI's own help text. You can install the CLI with npm i -g @catena/cli, which requires Node.js 20 or later. Once it's installed, catena <command> --help will print the same text for your installed version, and catena guide will tell you when to use each command.

Common behavior

The following behavior is shared across commands:

Output: Every command except link prints JSON on stdout, while errors and upgrade notices go to stderr.
Compact JSON: --json prints compact single-line JSON, which is useful for piping.
Profiles: --profile <name> selects a credential profile. If you don't pass it, the CLI will pick credentials in the following order: CATENA_SECRET_KEY, CATENA_PROFILE, the directory binding, the default profile, and the only linked profile. See Link with the CLI.
Exit codes: The exit code only reports whether the command ran. For example, a send that policy blocks will still exit 0, so read .status and .reasons for the outcome.

The CLI also reads the following environment variables:

Environment variable	Effect
`CATENA_SECRET_KEY`	Sign with this secret key instead of a linked profile. See Link with secret keys.
`CATENA_PROFILE`	Select a profile by name.
`CATENA_HOME`	Keep profiles and credential files in this directory instead of `~/.config/catena`.
`CATENA_API_URL`	Use a different Catena API URL. The default is `https://api.catena.com`.
`DO_NOT_TRACK`	Set to `1` or `true` to turn off local failure reports.

Linking

catena link

Link an existing agent, or create and link a new agent when agent-id is omitted.

Shell

catena link [OPTIONS] [AGENT-ID]

Argument	Description
`AGENT-ID`	Optional agent ID shown in the Catena console; omit to create and link a new agent

Option	Description	Default
`--api-url=<api_url>`	Catena API URL (defaults to $CATENA_API_URL)	`https://api.catena.com`
`--browser`	The person approving is at this machine: open the approval in its browser and wait. With an agent id this is the browser sign-in	`false`
`--no-browser`	Print the approval link and exit (the default; kept for older scripts)
`--name=<name>`	Suggested name for an agent created from this link; only used when agent-id is omitted
`--service`	Provision a deployed-service signing credential instead of linking this machine: approval registers a P-256 key, no session tokens are minted, and nothing is stored locally. Interactive agent hosts must NOT use this	`false`
`--public-key=<public_key>`	With --service: register this existing compressed P-256 public key (the deployment already holds the secret key) instead of generating a keypair
`--relink`	With an agent id: link this machine's profile for it again although it is linked and its key works, for example to add a wallet-send key once signing setup is done. The profile keeps working until the person approves	`false`
`--wait`	For a person at a terminal who approves on another device: print the link and wait up to 15 minutes for the approval instead of exiting. An agent should not use it, and should run link again once the person says they approved	`false`

Text

Linking in brief:

  1. Run link. It prints a link for the person who approves, and exits.
  2. Send them the link. With no Catena account, they sign up from it.
  3. When they say they approved, or on your schedule, run the same command
     again from the same directory, until it prints Done. Each run checks
     once and exits. After they approve, you have 24 hours.
  4. Declined: stop, and send no new link unless they ask. Expired: send the
     new link it prints.
  5. On a schedule, pass the same --profile <name> on every run.
  6. To cancel, ask the person to deny it on the approval page, or let it
     expire. The catena unlink --profile <name> --force command link printed,
     if any, forgets it on this machine.

  An agent should not use --wait. catena guide has the details.

catena unlink

Disconnect the selected agent profile.

Shell

catena unlink [OPTIONS]

Option	Description	Default
`--force`	Remove the profile and its local credentials without contacting the server; use when the credential is missing, revoked, or a link was interrupted	`false`

catena whoami

Show which agent you are currently acting as.

Shell

catena whoami [OPTIONS]

catena setup-state

Read setup steps and available assets for the authenticated organization.

Shell

catena setup-state [OPTIONS]

Profiles

catena profiles use

Set the default credential profile.

Shell

catena profiles use [OPTIONS] <PROFILE>

Argument	Description
`PROFILE`	Profile name Required.

catena profiles current

Show the selected credential profile and how it was chosen.

Shell

catena profiles current

catena profiles list

List credential profiles and their directory bindings.

Shell

catena profiles list

catena profiles bind

Bind a directory to a profile for automatic selection.

Shell

catena profiles bind [OPTIONS] <PROFILE> [PATH]

Argument	Description
`PROFILE`	Profile name to bind Required.

catena profiles unbind

Remove a directory's profile binding.

Shell

catena profiles unbind [OPTIONS] [PATH]

Argument	Description
`PATH`	Directory to unbind (defaults to the current directory)

Accounts

catena accounts list

List accounts accessible under the agent's policy.

Shell

catena accounts list [OPTIONS]

catena accounts balance

Request an account balance through the policy engine.

Shell

catena accounts balance [OPTIONS] <ACCOUNT>

Argument	Description
`ACCOUNT`	Account id Required.

catena accounts transactions

Read an account's transaction history through the policy engine.

Shell

catena accounts transactions [OPTIONS] <ACCOUNT>

Argument	Description
`ACCOUNT`	Account id Required.

Option	Description	Default
`--start=<start>`	Only include transactions at or after this ISO 8601 time
`--end=<end>`	Only include transactions at or before this ISO 8601 time
`--limit=<limit>`	Maximum transactions to return (default 50, max 200)
`--offset=<offset>`	Number of transactions to skip for pagination

catena accounts deposit-address

Read an account deposit address through the policy engine.

Shell

catena accounts deposit-address [OPTIONS] <ACCOUNT>

Argument	Description
`ACCOUNT`	Account id Required.

Option	Description	Default
`--network=<network>`	Deposit network; defaults to base. Availability depends on the connected environment.	`base`
`--asset=<asset>`	Deposit asset; defaults to USDC. Use setup-state for available assets.	`usdc`

Counterparties

catena counterparties list

List counterparties available under the agent's policy.

Shell

catena counterparties list [OPTIONS]

Option	Description	Default
`--address=<address>`	Only counterparties with a wallet rail matching this address (0x…)
`--network=<network>`	Only counterparties owning a wallet address in this network class (e.g. base); not a settlement promise

catena counterparties create

Request counterparty creation through the policy engine. Without a subcommand, --name and --email create a record without payment details and send no email.

Shell

catena counterparties create [OPTIONS] email|bank|wallet

Option	Description	Default
`--name=<name>`	Counterparty name; required without a subcommand
`--email=<email>`	Contact email; required without a subcommand; creating the counterparty sends no email
`--idempotency-key=<idempotency_key>`	Optional operation key. Reuse the same value only when retrying the same submission; omitted generates a fresh key for this invocation.

Subcommand	Description
`email`	Create a counterparty with an email and no payment details. Sends no email.
`bank`	Request bank counterparty creation through the policy engine. Prints an intent envelope.
`wallet`	Request wallet counterparty creation through the policy engine. Prints an intent envelope.

catena counterparties create bank

Request bank counterparty creation through the policy engine. Prints an intent envelope.

Shell

catena counterparties create bank [OPTIONS] --name=<name> --bank-name=<bank_name> --routing-number=<routing_number> --account-number=<account_number> --address-street=<address_street> --address-city=<address_city> --address-state=<address_state> --address-postal-code=<address_postal_code>

Option	Description	Default
`--name=<name>`	Counterparty name Required.
`--bank-name=<bank_name>`	Receiving bank name Required.
`--routing-number=<routing_number>`	9-digit ABA routing number Required.
`--account-number=<account_number>`	Receiving bank account number Required.
`--account-type=<account_type>`	checking \| savings (default checking)
`--address-street=<address_street>`	Street address of the receiving bank account holder Required.
`--address-city=<address_city>`	City Required.
`--address-state=<address_state>`	State (e.g. NY) Required.
`--address-postal-code=<address_postal_code>`	Postal code Required.
`--address-country=<address_country>`	Default USA
`--email=<email>`	Optional contact email
`--idempotency-key=<idempotency_key>`	Optional operation key. Reuse the same value only when retrying the same submission; omitted generates a fresh key for this invocation.

catena counterparties create wallet

Request wallet counterparty creation through the policy engine. Prints an intent envelope.

Shell

catena counterparties create wallet [OPTIONS] --name=<name> --address=<address>

Option	Description	Default
`--name=<name>`	Counterparty name Required.
`--address=<address>`	Wallet address (0x… or ENS name on EVM networks) Required.
`--network=<network>`	Wallet network; defaults to base. Availability depends on the connected environment.	`base`
`--asset=<asset>`	Wallet asset; omitted means USDC. Use setup-state for available assets.
`--email=<email>`	Optional contact email
`--idempotency-key=<idempotency_key>`	Optional operation key. Reuse the same value only when retrying the same submission; omitted generates a fresh key for this invocation.

catena counterparties request-details

Ask a counterparty to provide bank details, wallet details, or both through the policy engine.

Shell

catena counterparties request-details [OPTIONS] <COUNTERPARTY>

Argument	Description
`COUNTERPARTY`	Counterparty id Required.

Option	Description	Default
`--bank`	Request bank account details	`false`
`--wallet`	Request wallet details	`false`
`--idempotency-key=<idempotency_key>`	Optional operation key. Reuse the same value only when retrying the same submission; omitted generates a fresh key for this invocation.

Money movement

catena send

Submit a USD send intent to a counterparty rail.

Shell

catena send [OPTIONS] --rail=<rail> --amount=<amount> --method=<method>

Option	Description	Default
`--account=<account>`	Source account id; omit when the policy allows sends from exactly one account
`--rail=<rail>`	Destination counterparty rail id (cpr_...) Required.
`--amount=<amount>`	USD amount as a decimal string (e.g. 125.00) Required.
`--method=<method>`	ach \| wire \| on-chain; ach and wire require a bank rail, on-chain a wallet rail Required.
`--memo=<memo>`	ACH/wire payment reference; an organization's default ACH memo replaces it on ACH; deprecated for on-chain sends
`--description=<description>`	Internal note stored in Catena
`--idempotency-key=<idempotency_key>`	Optional operation key. Reuse the same value only when retrying the same submission; omitted generates a fresh key for this invocation.

catena transfer

Submit a USD transfer intent between two of this agent's accounts.

Shell

catena transfer [OPTIONS] --from=<from> --to=<to> --amount=<amount>

Option	Description	Default
`--from=<from>`	Source account id Required.
`--to=<to>`	Destination account id Required.
`--amount=<amount>`	USD amount as a decimal string (e.g. 125.00) Required.
`--memo=<memo>`	Memo on the underlying transfer
`--description=<description>`	Operator-facing description
`--idempotency-key=<idempotency_key>`	Optional operation key. Reuse the same value only when retrying the same submission; omitted generates a fresh key for this invocation.

Paying for APIs

catena x402

Fetch a URL, paying its x402.

Shell

catena x402 [OPTIONS] --url=<url> --account=<account>

Option	Description	Default
`--url=<url>`	The paywalled URL to fetch (an x402 v2 endpoint) Required.
`--account=<account>`	Source wallet account id the payment draws from Required.
`--max-amount=<max_amount>`	Refuse challenges above this USD amount (decimal string, e.g. 0.25). Policy limits still apply server-side.
`--method=<method>`	HTTP method for the request
`--data=<data>`	Request body. Use @path to read a file or @- for stdin. Implies POST and a JSON content type unless overridden.
`--content-type=<content_type>`	Content-Type header for the request body (default application/json when --data is set)
`--output=<output>`	Write the full response body to this file (must be a regular file; written for any HTTP status — check .status). Without it .body is capped at 4000 characters; longer or non-UTF-8 bodies are saved to a file (path reported in .bodyPath)
`--header=<header>`	Request header as "Name: Value" (repeatable, like curl -H); sent on the initial request and the paid retry

catena mpp

Fetch a URL, paying its MPP challenge via USDC.

Shell

catena mpp [OPTIONS] --url=<url> --account=<account>

Option	Description	Default
`--url=<url>`	The paywalled URL to fetch (an MPP endpoint) Required.
`--account=<account>`	Source wallet account id the payment draws from Required.
`--max-amount=<max_amount>`	Refuse challenges above this USD amount (decimal string, e.g. 0.25). Policy limits still apply server-side.
`--method=<method>`	HTTP method for the request
`--data=<data>`	Request body. Use @path to read a file or @- for stdin. Implies POST and a JSON content type unless overridden.
`--content-type=<content_type>`	Content-Type header for the request body (default application/json when --data is set)
`--output=<output>`	Write the full response body to this file (must be a regular file; written for any HTTP status — check .status). Without it .body is capped at 4000 characters; longer or non-UTF-8 bodies are saved to a file (path reported in .bodyPath)
`--header=<header>`	Request header as "Name: Value" (repeatable, like curl -H); sent on both requests, except caller Authorization is replaced on the paid retry when MPP uses that field for its credential

Intents

catena intents list

List intents created by this agent, newest first.

Shell

catena intents list [OPTIONS]

Option	Description	Default
`--status=<status>`	Intent status to include (repeatable): pending\|processing\|completed\|blocked\|failed
`--type=<type>`	Intent type to include (repeatable): send\|transfer\|create_counterparty\|request_counterparty_details\|x402\|mpp\|policy_override
`--start=<start>`	Only include intents created at or after this ISO 8601 time
`--account=<account>`	Only include intents with this resolved source account id
`--limit=<limit>`	Maximum intents to return (default 50, max 200)
`--offset=<offset>`	Number of intents to skip for pagination

catena intents get

Look up the current state of an intent created by this agent.

Shell

catena intents get [OPTIONS] <ID>

Argument	Description
`ID`	Intent id (e.g. int_…) Required.

catena intents cancel

Cancel an intent before execution starts.

Shell

catena intents cancel [OPTIONS] <ID>

Argument	Description
`ID`	Intent id (e.g. int_…) Required.

Policy

catena policy show

Show the agent's assigned policy.

Shell

catena policy show [OPTIONS]

catena policy request-override

Ask a person to approve a temporary change to this agent's limits.

Shell

catena policy request-override [OPTIONS] --duration=<duration> --reason=<reason>

Option	Description	Default
`--account=<account>`	Account whose own hard limit should increase. For a transfer limit, the source account funds move out of. Use --all-accounts instead for a limit shared across all accounts.
`--all-accounts`	Raise the one limit shared across all accounts combined (accountAggregationScope across_accounts in policy show), not one account's own limit	`false`
`--capability=<capability>`	Which capability's limit to increase: send (payments to counterparties) or transfer (between the user's own accounts)	`send`
`--counterparty=<counterparty>`	Counterparty ID (cp_...) whose scoped send limit should increase. Omit for the all-counterparties limit.
`--rule=<rule>`	Which limit to adjust	`per_transaction_amount`
`--amount=<amount>`	New threshold for an amount limit, as a decimal USD string (e.g. 500.00)
`--count=<count>`	New threshold for a transaction-count limit (e.g. 20)
`--duration=<duration>`	How long the override should last once approved (e.g. 90s, 30m, 4h, 2d). One minute to seven days. Required.
`--reason=<reason>`	Why the task needs this, for the person who reviews the request Required.
`--idempotency-key=<idempotency_key>`	Optional operation key. Reuse the same value only when retrying the same submission; omitted generates a fresh key for this invocation.

Help and feedback

catena guide

Print the Catena CLI agent operating guide.

Shell

catena guide

catena feedback

Send free-form feedback about Catena to the Catena team.

Shell

catena feedback [OPTIONS] [MESSAGE]

Argument	Description
`MESSAGE`	Plain-text feedback (1-4000 chars); omit to pipe on stdin.

Text

Use this format and omit sections that do not apply:

**Goal**
What I was trying to accomplish and why.

**Attempt**
What I tried, including relevant context.

**Outcome**
What happened and where I became blocked or confused.

**Evidence**
Relevant commands, inputs, responses, errors, documentation, or other concrete observations.

For a reproducible bug:
- Reproduction steps:
- Expected behavior:
- Whether it reproduces consistently:

**Impact**
What I could not do, or what became unnecessarily difficult or risky.

**Workaround** _(optional)_
Any workaround I found and its limitations.