# 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:

```bash
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`; 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.

```bash
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_...`.

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

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

```bash
pnpm dlx catena-cli unlink
```

### `profiles current`

Show the selected credential profile and its routing metadata.

```bash
pnpm dlx catena-cli profiles current
```

### `profiles list`

List linked credential profiles and mark the selected default profile.

```bash
pnpm dlx catena-cli profiles list
```

### `profiles use <profile>`

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

```bash
pnpm dlx catena-cli profiles use mcp
```

### `whoami`

Show which agent the selected profile is linked to.

```bash
pnpm dlx catena-cli whoami
```

### `policy show`

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

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

```bash
pnpm dlx catena-cli accounts list
```

### `counterparties list`

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

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

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

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

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

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

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

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

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

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

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

```bash
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
```
