---
title: "Direct commands"
description: "The commands that do not live under a group: authentication, the meta-tools and the money shortcuts."
---

The commands that do not live under a group: authentication, the meta-tools and the money shortcuts.

20 commands in `@codespar/cli 0.16.0`.

These are written by hand, so each shapes its own table; `--json` gives a script the payload instead. [Configuration](/docs/cli/config#what-a-script-gets-when-a-command-fails) has the exit codes and the shape of a failure.

### `codespar login`

Authenticate and save your API key to ~/.codespar/config.json

```bash
codespar login [options]
```

| option | what it does |
|---|---|
| `--api-key <key>` | API key (prompts if omitted) |

### `codespar whoami`

Show the authenticated user, org, project, and key scopes

```bash
codespar whoami [options]
```

### `codespar logout`

Clear the stored API key

```bash
codespar logout [options]
```

### `codespar tool`

Invoke a published meta-tool by name (15 of them — see `codespar tools meta`)

```bash
codespar tool [options] <name>
```

| option | what it does |
|---|---|
| `--action <action>` | Action to run, validated against the tool's published vocabulary |
| `--arg <key=value>` | Single input property (repeatable); typed by the published schema (default: []) |
| `-i, --input <json>` | Full input as a JSON string |
| `-f, --input-file <path>` | Full input from a JSON file |
| `-u, --user <id>` | User id for the session (default: cli-user) |

### `codespar pay`

Invoke codespar_pay (alias of `codespar tool codespar_pay`)

```bash
codespar pay [options]
```

| option | what it does |
|---|---|
| `--action <action>` | Action to run, validated against the tool's published vocabulary |
| `--arg <key=value>` | Single input property (repeatable); typed by the published schema (default: []) |
| `-i, --input <json>` | Full input as a JSON string |
| `-f, --input-file <path>` | Full input from a JSON file |
| `-u, --user <id>` | User id for the session (default: cli-user) |

### `codespar kyc`

Invoke codespar_kyc (alias of `codespar tool codespar_kyc`)

```bash
codespar kyc [options]
```

| option | what it does |
|---|---|
| `--action <action>` | Action to run, validated against the tool's published vocabulary |
| `--arg <key=value>` | Single input property (repeatable); typed by the published schema (default: []) |
| `-i, --input <json>` | Full input as a JSON string |
| `-f, --input-file <path>` | Full input from a JSON file |
| `-u, --user <id>` | User id for the session (default: cli-user) |

### `codespar execute`

Run a single tool call (creates a throwaway session)

```bash
codespar execute [options] <tool>
```

| option | what it does |
|---|---|
| `-s, --server <id>` | Server to open the session against |
| `-i, --input <json>` | Input as JSON string |
| `-f, --input-file <path>` | Input as JSON file path |
| `-u, --user <id>` | User id for the session (default: cli-user) |

### `codespar discover`

Search the catalog for tools matching a use case (codespar_discover)

```bash
codespar discover [options] <query>
```

| option | what it does |
|---|---|
| `--limit <n>` | Max results to display (default 10, server clamps 1..20) |
| `--category <name>` | Filter by category |
| `--country <code>` | Filter by country code (BR, MX, ...) |
| `-u, --user <id>` | User id for the session (default: cli-user) |

### `codespar charge`

Issue an inbound charge via codespar_charge (router picks the rail)

```bash
codespar charge [options]
```

| option | what it does |
|---|---|
| `-i, --input <json>` | Charge args as JSON string |
| `-f, --input-file <path>` | Charge args from JSON file |
| `-u, --user <id>` | User id for the session (default: cli-user) |

### `codespar spend`

Execute an agentic spend against a consumer mandate (Pix / USDC / x402 by payee)

```bash
codespar spend [options]
```

| option | what it does |
|---|---|
| `-m, --mandate <id>` | Consumer mandate id |
| `-p, --payee <payee>` | Pix key, EVM address, or x402 resource URL |
| `-a, --amount <minor>` | Amount in minor units (cents) |
| `--agent <id>` | Agent id making the spend |

### `codespar wallet`

Show a consumer's unified wallet, rolled up per currency (multi-slot mandate balances)

```bash
codespar wallet [options] <consumer>
```

### `codespar transfer`

Move value between wallet slots (per-currency, no FX — a cross-currency move is a real ramp trade)

```bash
codespar transfer [options] <consumer>
```

| option | what it does |
|---|---|
| `--from <currency>` | Source slot currency (e.g. BRL) |
| `--to <currency>` | Destination slot currency (e.g. USDC) |
| `--amount <minor>` | Amount in the source currency's minor units |
| `--execute` | Actually run the ramp legs (real money). Omit to just plan the move. |
| `--agent <id>` | Agent id attributed for audit |
| `--purpose <text>` | Human purpose for the transfer |

### `codespar ship`

Generate label / quote rates / track shipment via codespar_ship

```bash
codespar ship [options]
```

| option | what it does |
|---|---|
| `-i, --input <json>` | Ship args as JSON string |
| `-f, --input-file <path>` | Ship args from JSON file |
| `-u, --user <id>` | User id for the session (default: cli-user) |

### `codespar payment-status`

Get the async settlement status for a tool call (poll once or --stream)

```bash
codespar payment-status [options] <tool-call-id>
```

| option | what it does |
|---|---|
| `--stream` | Open an SSE stream and print updates until terminal frame |
| `--timeout <ms>` | Max wait for the stream in ms (default 600000) |
| `-u, --user <id>` | User id for the session (default: cli-user) |

### `codespar verification-status`

Get the async KYC verification status for a tool call (poll once or --stream)

```bash
codespar verification-status [options] <tool-call-id>
```

| option | what it does |
|---|---|
| `--stream` | Open an SSE stream and print updates until terminal frame |
| `--timeout <ms>` | Max wait for the stream in ms (default 600000) |
| `-u, --user <id>` | User id for the session (default: cli-user) |

### `codespar wizard`

Connection wizard for a server — required secrets, connect URL, next steps

```bash
codespar wizard [options] [server-id]
```

| option | what it does |
|---|---|
| `--action <name>` | list | status | initiate (default: status if server-id given, else list) |
| `--country <code>` | Filter list action by country code |
| `--environment <env>` | live | test (initiate only) |
| `--return-to <path>` | Dashboard return path after initiate (validated /dashboard/*) |
| `-u, --user <id>` | User id for the session (default: cli-user) |

### `codespar ledger`

Post journal entries / read balances / create accounts via codespar_ledger (Midaz)

```bash
codespar ledger [options]
```

| option | what it does |
|---|---|
| `-i, --input <json>` | Ledger args as JSON string |
| `-f, --input-file <path>` | Ledger args from JSON file |
| `-u, --user <id>` | User id for the session (default: cli-user) |

### `codespar issue`

Issue / freeze / read agent spend cards via codespar_issue (Pomelo)

```bash
codespar issue [options]
```

| option | what it does |
|---|---|
| `-i, --input <json>` | Issue args as JSON string |
| `-f, --input-file <path>` | Issue args from JSON file |
| `-u, --user <id>` | User id for the session (default: cli-user) |

### `codespar eval`

Run the agent's manifest check plus its eval suite (adversarial cases and scenarios); exit 1 on any failing case

```bash
codespar eval [options] <dir>
```

### `codespar init`

Scaffold a new commerce agent from a template

```bash
codespar init [options] [name]
```

| option | what it does |
|---|---|
| `-t, --template <slug>` | Template slug; `--list` shows the available templates with a one-line description each: pix-agent                Minimal Pix charge + WhatsApp notification via OpenAI ecommerce-checkout       Full Complete Loop: checkout → invoice → ship → notify (Claude) streaming-chat           Next.js 15 + Vercel AI SDK with token-by-token streaming multi-tenant             SaaS pattern — one API key, N tenants, per-tenant billing bills-agent              The consumer delegates the month's bills to an agent that pays under a signed mandate: per-payment cap, monthly cap, named payees, expiry. Every payment returns a receipt. collections-agent        The merchant's agent that collects: agrees terms with the payer inside a negotiation envelope, issues one bolepix per instalment with an idempotency key, presents the QR and the copy-and-paste in the conversation, and closes the cycle on commerce.charge.paid or commerce.charge.expired. hello-agent              The worked example of the codespar-agent-builder skill: a read-only agent that reads the month's bills and cannot pay. Built from the five files, the packs and one kit module. supplier-payments-agent  A company delegates its suppliers, commissions and payroll to an agent that pays them in batches under one signed mandate. A batch is a loop of executions: one refusal does not stop the others, and re-running it pays nobody twice. |
| `-y, --yes` | Use default template without prompting |
| `-l, --list` | List the available templates, with a one-line description each, and exit |