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

19 commands in `@codespar/cli 0.11.2`.

### `codespar login`

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

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

| opção | o que faz |
|---|---|
| `--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>
```

| opção | o que faz |
|---|---|
| `--action <action>` | Action to run, validated against the tool's published |
| `--arg <key=value>` | Single input property (repeatable); typed by the |
| `-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]
```

| opção | o que faz |
|---|---|
| `--action <action>` | Action to run, validated against the tool's published |
| `--arg <key=value>` | Single input property (repeatable); typed by the |
| `-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]
```

| opção | o que faz |
|---|---|
| `--action <action>` | Action to run, validated against the tool's published |
| `--arg <key=value>` | Single input property (repeatable); typed by the |
| `-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>
```

| opção | o que faz |
|---|---|
| `-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>
```

| opção | o que faz |
|---|---|
| `--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]
```

| opção | o que faz |
|---|---|
| `-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]
```

| opção | o que faz |
|---|---|
| `-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>
```

| opção | o que faz |
|---|---|
| `--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 |
| `--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]
```

| opção | o que faz |
|---|---|
| `-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>
```

| opção | o que faz |
|---|---|
| `--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>
```

| opção | o que faz |
|---|---|
| `--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]
```

| opção | o que faz |
|---|---|
| `--action <name>` | list | status | initiate (default: status if server-id |
| `--country <code>` | Filter list action by country code |
| `--environment <env>` | live | test (initiate only) |
| `--return-to <path>` | Dashboard return path after initiate (validated |
| `-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]
```

| opção | o que faz |
|---|---|
| `-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]
```

| opção | o que faz |
|---|---|
| `-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 init`

Scaffold a new commerce agent from a template

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

| opção | o que faz |
|---|---|
| `-t, --template <slug>` | Template slug (pix-agent, ecommerce-checkout, |
| `-y, --yes` | Use default template without prompting |