@catena/cli

Catena CLI lets an approved agent act from a named local profile: inspect the policy it has been assigned, list the accounts and counterparties it can see, and submit policy-checked money movement intents.

Run it without installing:

pnpm dlx @catena/cli <command> [args]

The package exposes the catena binary. Examples use pnpm dlx @catena/cli so they work directly from npm; pnpm selects catena because it is the package's only executable.

How it works

link connects a profile to an agent through a browser approval flow. After linking, Catena writes routing metadata to ~/.catena/profiles.json and stores session material in the OS credential store. Every other command resolves the selected profile and prints pretty JSON to stdout so it can be piped through tools such as jq; pass --json to print compact single-line JSON instead. unlink revokes only the selected profile's server link and removes that profile's local credential.

By default the CLI talks to https://api.catena.com. Set CATENA_API_URL when you need to target another Catena environment.

First-time setup

To create or choose an agent from the Catena console, run link without an agent id. Use --name to suggest a name when the console creates a new agent; the approving operator can edit it before approval.

pnpm dlx @catena/cli link --name "Hermes Runtime"

To link a specific existing agent, ask the Catena customer for the agent id shown in the Catena console. It looks like agent_....

pnpm dlx @catena/cli link <agent-id>

The browser approval window stays open for up to 5 minutes. If the approval is denied or times out, run the command again.

Useful flags:

| Flag | Description | Default | | ------------ | ------------------------------------------------------- | ------------------------------- | | --bank-url | Bank API URL. | $CATENA_API_URL or prod | | --name | Suggested name when creating an agent from the console. | none | | --profile | Credential profile name. | configured default or default |

Commands

link [agent-id]

Connect the selected profile to an agent. Omit agent-id to create or choose an agent from the Catena console.

pnpm dlx @catena/cli link --name "Hermes Runtime"
pnpm dlx @catena/cli link <agent-id>

unlink

Disconnect the selected profile from its agent and remove its local credential.

pnpm dlx @catena/cli unlink

profiles current

Show the selected credential profile and its routing metadata.

pnpm dlx @catena/cli profiles current

profiles list

List linked credential profiles and mark the selected default profile.

pnpm dlx @catena/cli profiles list

profiles use <profile>

Set the selected default profile. The profile must already be linked.

pnpm dlx @catena/cli profiles use mcp

whoami

Show which agent the selected profile is linked to.

pnpm dlx @catena/cli whoami

policy show

Show the policy assigned to the linked agent. Read this before creating counterparties or submitting intents.

pnpm dlx @catena/cli policy show

The policy includes policyCapabilities rows. Each row grants one read, send, or transfer capability on one account and carries block or approval rules. It also includes counterpartyRules for send recipient scope and counterparty creation.

accounts list

List the accounts available under the agent's policy.

pnpm dlx @catena/cli accounts list

counterparties list

List counterparties and their rails. Use rail ids from this output with send.

pnpm dlx @catena/cli counterparties list

counterparties create bank

Request creation of a bank-rail counterparty. The command returns an intent envelope; policy may complete it, block it, or route it to approval.

pnpm dlx @catena/cli counterparties create bank \
  --name "Acme Vendor" \
  --bank-name "Chase" \
  --routing-number 021000021 \
  --account-number 123456789 \
  --address-street "123 Main St" \
  --address-city "New York" \
  --address-state NY \
  --address-postal-code 10001

Required flags: --name, --bank-name, --routing-number, --account-number, --address-street, --address-city, --address-state, --address-postal-code.

Optional flags: --account-type (checking or savings), --address-country, --email.

counterparties create wallet

Request creation of a wallet-rail counterparty. The command returns an intent envelope; policy may complete it, block it, or route it to approval.

pnpm dlx @catena/cli counterparties create wallet \
  --name "DAO Treasury" \
  --address 0xAbC123...

Required flags: --name, --address.

Optional flags: --network (defaults to base; Base is the only supported wallet network), --email.

send

Request a USD send to a counterparty rail.

pnpm dlx @catena/cli send \
  --account acct_... \
  --rail cprl_... \
  --amount 125.00 \
  --method ach

Required flags: --account, --rail, --amount, --method.

Optional flags: --memo, --description, --idempotency-key.

--method must be one of ach, wire, or on-chain.

To check whether a send completed, run intents get <id> with the returned intent id. If the original command is retried with the same details after a network error, the server deduplicates it automatically and returns the original intent instead of sending again. Use --idempotency-key only when you intentionally want another payment with the same details.

transfer

Request a USD transfer between two accounts visible to the agent.

pnpm dlx @catena/cli transfer \
  --from acct_... \
  --to acct_... \
  --amount 125.00

Required flags: --from, --to, --amount.

Optional flags: --memo, --description, --idempotency-key.

To check whether a transfer completed, run intents get <id> with the returned intent id. Identical retries are deduplicated automatically and return the original intent. Use --idempotency-key only when you intentionally want another transfer with the same details.

accounts balance

Read an account balance through the policy engine.

pnpm dlx @catena/cli accounts balance acct_...

accounts transactions

Read an account's transaction history through the policy engine. Granted by the same read access as accounts balance and never creates an intent. Returns { accountId, transactions, total } newest-first.

pnpm dlx @catena/cli accounts transactions acct_...

Optional flags: --start / --end (ISO 8601 bounds), --limit (default 50, max 200), --offset (pagination). Page until offset + transactions.length >= total.

accounts deposit-address

Read an account deposit address through the policy engine. --network and --asset default to base and usdc.

pnpm dlx @catena/cli accounts deposit-address acct_... --network base --asset usdc

intents get

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

pnpm dlx @catena/cli intents get int_...

The response includes a data field carrying the associated result once one exists: the linked transaction for send/transfer intents, or the created counterparty for create_counterparty. It is null when there is no associated result yet. When data has a console destination, metadata.dataUrl contains the browser URL for that result.

feedback <message>

Send free-form feedback about Catena to the Catena team. Use it to report a bug, request a feature, or share an observation about working with Catena. The message must be 1-4000 characters after trimming. Write-only: previously submitted feedback cannot be read back.

Pass the message as a single quoted argument, or omit it and pipe the message on stdin. Use stdin (or -- before the argument) when the message starts with - or spans multiple lines.

pnpm dlx @catena/cli feedback "The transfer flow worked great"

pnpm dlx @catena/cli feedback <<'EOF'
- transfer failed
- policy was confusing
EOF

Output and exit codes

Non-link commands print pretty JSON to stdout. Errors print to stderr and exit with code 1.

send and transfer exit as soon as the intent is created and any immediate next action is submitted. Inspect the returned .status and .reasons fields, then use pnpm dlx @catena/cli intents get <intent-id> to check whether it later completes, requires approval, or fails.

Configuration

| Variable | Purpose | Default | | ---------------- | ------------- | ------------------------ | | CATENA_API_URL | Bank API URL. | https://api.catena.com |

Discovering options

Every command supports --help.

pnpm dlx @catena/cli --help
pnpm dlx @catena/cli send --help
pnpm dlx @catena/cli counterparties create --help
pnpm dlx @catena/cli counterparties create bank --help
pnpm dlx @catena/cli counterparties create wallet --help