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 both catena-cli and catena binaries. Examples use pnpm dlx catena-cli so they work directly from npm.

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. 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

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 | | --profile | Credential profile name. | configured default or default |

Commands

link <agent-id>

Connect the selected profile to an agent. This is the same setup command shown above.

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... \
  --network base

Required flags: --name, --address, --network.

Optional flags: --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, --wait.

--method must be one of ach, wire, or on-chain. Use --wait to poll for up to 60 seconds until the intent reaches a terminal state or pending_approval.

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, --wait.

accounts balance

Read an account balance through the policy engine.

pnpm dlx catena-cli accounts balance acct_...

intents get

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

pnpm dlx catena-cli intents get int_...

Output and exit codes

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

Without --wait, send and transfer exit as soon as the intent is created. Inspect the returned .status and .reasons fields to see whether it later completes, requires approval, or fails.

With --wait, the CLI prints the final intent envelope and exits with:

| Exit | Meaning | | ---- | ----------------------------------------------------------- | | 0 | The intent completed. | | 1 | The intent was denied, blocked, failed, or expired. | | 2 | The intent timed out while polling or needs human approval. |

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