@catena/cli 0.8.0 → 0.10.0

package/README.md

@@ -7,12 +7,12 @@ and submit policy-checked money movement intents.
 Run it without installing:
 
 ```bash
-pnpm dlx @catena/cli <command> [args]
+npx @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.
+The package exposes the `catena` binary. Examples use `npx @catena/cli` so they
+work directly from npm; npx selects `catena` because it is the package's only
+executable.
 
 ## How it works
 
@@ -24,8 +24,31 @@ 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.
+## Hosts without a keychain
+
+A container, a CI job, or a serverless runtime has no OS keychain and no
+browser, so `link` cannot store a credential there. Set `CATENA_SECRET_KEY` to
+the agent's P-256 secret key instead:
+
+```bash
+CATENA_SECRET_KEY="<64 hex characters>" npx @catena/cli whoami
+```
+
+Create the key in the Catena console: open the agent, select the **Secret keys**
+tab, then **Create secret key**. The console shows it one time. `@catena/sdk`
+reads the same variable, so one key serves either client. Set the value with no
+surrounding whitespace: the CLI trims it, and the SDK does not.
+
+While the key is set, `profiles current` reports `source: "secret-key"` with no
+`.profile` field, and `profiles list` adds `shadowedBy` and marks every profile
+`current: false`.
+
+On a machine that also holds a linked profile or sets `CATENA_PROFILE`, every
+command prints one stderr line that names the key as the signing credential.
+Stdout keeps only the command result.
+
+The key outranks every profile tier, but an explicit `--profile` still wins.
+`unlink` does not apply to it; revoke the key in the console instead.
 
 ## First-time setup
 
@@ -34,14 +57,14 @@ 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"
+npx @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>
+npx @catena/cli link <agent-id>
 ```
 
 The browser approval window stays open for up to 5 minutes. If the approval is
@@ -49,11 +72,10 @@ 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` |
+| Flag        | Description                                             | Default                         |
+| ----------- | ------------------------------------------------------- | ------------------------------- |
+| `--name`    | Suggested name when creating an agent from the console. | none                            |
+| `--profile` | Credential profile name.                                | configured default or `default` |
 
 ## Commands
 
@@ -63,8 +85,8 @@ 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>
+npx @catena/cli link --name "Hermes Runtime"
+npx @catena/cli link <agent-id>
 ```
 
 ### `unlink`
@@ -72,7 +94,7 @@ pnpm dlx @catena/cli link <agent-id>
 Disconnect the selected profile from its agent and remove its local credential.
 
 ```bash
-pnpm dlx @catena/cli unlink
+npx @catena/cli unlink
 ```
 
 ### `profiles current`
@@ -80,7 +102,7 @@ pnpm dlx @catena/cli unlink
 Show the selected credential profile and its routing metadata.
 
 ```bash
-pnpm dlx @catena/cli profiles current
+npx @catena/cli profiles current
 ```
 
 ### `profiles list`
@@ -88,7 +110,7 @@ pnpm dlx @catena/cli profiles current
 List linked credential profiles and mark the selected default profile.
 
 ```bash
-pnpm dlx @catena/cli profiles list
+npx @catena/cli profiles list
 ```
 
 ### `profiles use <profile>`
@@ -96,7 +118,7 @@ pnpm dlx @catena/cli profiles list
 Set the selected default profile. The profile must already be linked.
 
 ```bash
-pnpm dlx @catena/cli profiles use mcp
+npx @catena/cli profiles use mcp
 ```
 
 ### `whoami`
@@ -104,7 +126,7 @@ pnpm dlx @catena/cli profiles use mcp
 Show which agent the selected profile is linked to.
 
 ```bash
-pnpm dlx @catena/cli whoami
+npx @catena/cli whoami
 ```
 
 ### `policy show`
@@ -113,7 +135,7 @@ Show the policy assigned to the linked agent. Read this before creating
 counterparties or submitting intents.
 
 ```bash
-pnpm dlx @catena/cli policy show
+npx @catena/cli policy show
 ```
 
 The policy includes `policyCapabilities` rows. Each row grants one `read`,
@@ -126,7 +148,7 @@ counterparty creation.
 Ask a person to approve a temporary increase to one policy limit.
 
 ```bash
-pnpm dlx @catena/cli policy request-override \
+npx @catena/cli policy request-override \
   --account acct_... \
   --amount 500 \
   --duration 4h \
@@ -153,14 +175,15 @@ Fetch an MPP-protected HTTP endpoint and pay a supported USDC charge from a
 wallet account:
 
 ```bash
-pnpm dlx @catena/cli mpp --url https://api.example.com/paid \
+npx @catena/cli mpp --url https://api.example.com/paid \
   --account acct_... --max-amount 0.25
 ```
 
-Initial support covers `evm/charge` and `usdc/charge` for native USDC on Base
-and Base Sepolia. Payments use the agent's normal send capability, counterparty
-allowlist, spend limits, and approval flow. The recipient must already be a
-saved counterparty wallet rail.
+The CLI recognizes structurally valid EVM `evm/charge` and `usdc/charge`
+challenges and leaves network and canonical USDC support to the connected
+server. Current support includes Base and Base Sepolia. Payments use the agent's
+normal send capability, counterparty allowlist, spend limits, and approval flow.
+The recipient must already be a saved counterparty wallet rail.
 
 The command accepts the same request-body, header, output, profile, and JSON
 flags as `x402`; run `mpp --help` for details. If approval is required, approve
@@ -173,7 +196,7 @@ retrying so the resource is not paid twice.
 List the accounts available under the agent's policy.
 
 ```bash
-pnpm dlx @catena/cli accounts list
+npx @catena/cli accounts list
 ```
 
 ### `counterparties list`
@@ -182,7 +205,7 @@ List counterparties, their status, and their rails. Use rail ids from this
 output with `send`.
 
 ```bash
-pnpm dlx @catena/cli counterparties list
+npx @catena/cli counterparties list
 ```
 
 ### `counterparties create`
@@ -192,7 +215,7 @@ saves the counterparty without sending an email. The command returns an intent
 envelope; policy may complete it, block it, or route it to approval.
 
 ```bash
-pnpm dlx @catena/cli counterparties create \
+npx @catena/cli counterparties create \
   --name "Acme Vendor" \
   --email billing@acme.test
 ```
@@ -210,7 +233,7 @@ 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 \
+npx @catena/cli counterparties create bank \
   --name "Acme Vendor" \
   --bank-name "Chase" \
   --routing-number 021000021 \
@@ -234,15 +257,15 @@ 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 \
+npx @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`, `--idempotency-key`.
+Optional flags: `--network` (defaults to `base`; availability depends on the
+connected environment), `--email`, `--idempotency-key`.
 
 ### `counterparties request-details`
 
@@ -250,7 +273,7 @@ Ask an existing counterparty to provide bank details, wallet details, or both.
 The request follows policy and may require human approval.
 
 ```bash
-pnpm dlx @catena/cli counterparties request-details cp_... --bank
+npx @catena/cli counterparties request-details cp_... --bank
 ```
 
 Pass at least one of `--bank` or `--wallet`. `--idempotency-key` is optional.
@@ -261,7 +284,7 @@ The outstanding-invitation conflict remains independent of idempotency.
 Request a USD send to a counterparty rail.
 
 ```bash
-pnpm dlx @catena/cli send \
+npx @catena/cli send \
   --rail cprl_... \
   --amount 125.00 \
   --method ach
@@ -296,7 +319,7 @@ when its inputs match an earlier command.
 Request a USD transfer between two accounts visible to the agent.
 
 ```bash
-pnpm dlx @catena/cli transfer \
+npx @catena/cli transfer \
   --from acct_... \
   --to acct_... \
   --amount 125.00
@@ -315,7 +338,7 @@ when its inputs match an earlier command.
 Read an account balance through the policy engine.
 
 ```bash
-pnpm dlx @catena/cli accounts balance acct_...
+npx @catena/cli accounts balance acct_...
 ```
 
 ### `accounts transactions`
@@ -325,7 +348,7 @@ 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_...
+npx @catena/cli accounts transactions acct_...
 ```
 
 Optional flags: `--start` / `--end` (ISO 8601 bounds), `--limit` (default 50,
@@ -338,7 +361,7 @@ 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
+npx @catena/cli accounts deposit-address acct_... --network base --asset usdc
 ```
 
 ### `intents get`
@@ -346,7 +369,7 @@ pnpm dlx @catena/cli accounts deposit-address acct_... --network base --asset us
 Look up the current state of an intent created by this agent.
 
 ```bash
-pnpm dlx @catena/cli intents get int_...
+npx @catena/cli intents get int_...
 ```
 
 The response includes a `data` field carrying the associated result once one
@@ -367,9 +390,9 @@ 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"
+npx @catena/cli feedback "The transfer flow worked great"
 
-pnpm dlx @catena/cli feedback <<'EOF'
+npx @catena/cli feedback <<'EOF'
 - transfer failed
 - policy was confusing
 EOF
@@ -382,25 +405,26 @@ 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.
+then use `npx @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` |
+| Variable            | Purpose                                              | Default |
+| ------------------- | ---------------------------------------------------- | ------- |
+| `CATENA_SECRET_KEY` | Agent P-256 secret key (64 hex). Selects no profile. | none    |
+| `CATENA_PROFILE`    | Credential profile name.                             | none    |
 
 ## 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 email --help
-pnpm dlx @catena/cli counterparties create bank --help
-pnpm dlx @catena/cli counterparties create wallet --help
-pnpm dlx @catena/cli counterparties request-details --help
+npx @catena/cli --help
+npx @catena/cli send --help
+npx @catena/cli counterparties create --help
+npx @catena/cli counterparties create email --help
+npx @catena/cli counterparties create bank --help
+npx @catena/cli counterparties create wallet --help
+npx @catena/cli counterparties request-details --help
 ```