---
title: "Commands by area"
description: "A tour of the surface area by area, with the meta-tool shortcuts. The exhaustive list, with a runnable line per command, is in All commands."
---

## Commands

### Servers

Browse the server catalog:

```bash
# List all servers
codespar servers list

# Filter by category
codespar servers list --category payments
codespar servers list --country BR

# Show details of a specific server
codespar servers show stripe
```

### Tools

Inspect the tools exposed by a server:

```bash
# List tools for a server
codespar tools list --server asaas

# Show the full input schema of one tool
codespar tools show codespar_pay
```

### Execute

Run a single tool call without writing any SDK code:

```bash
codespar execute codespar_pay \
  --server asaas \
  --input '{ "method": "pix", "amount": 15000, "currency": "BRL" }'
```

Output is JSON with `success`, `data`, `duration`, `server`, and `tool_call_id` — the same shape `session.execute()` returns.

<Callout type="warn">
`codespar execute` creates a session behind the scenes, runs the call, and closes the session. For long-running or multi-call scripts, use the SDK instead.
</Callout>

### Sessions

Inspect and manage sessions:

```bash
# List recent sessions
codespar sessions list

# Show a session's details + logs
codespar sessions show ses_abc123

# Close an active session
codespar sessions close ses_abc123
```

### Connect

Link a user account to a provider (OAuth flow):

```bash
# Start an OAuth connection for the current user
codespar connect start mercado-pago

# List all active connections for your account
codespar connect list

# Revoke a connection
codespar connect revoke stripe --user user_abc
```

This is the CLI equivalent of `session.authorize()` — useful for testing Connect Links during development.

### Logs


```bash
# The tool calls of one session
codespar sessions show ses_abc123 --logs

# Or the recent calls across sessions, with --follow to keep polling
codespar logs tail --limit 20
```

### Init

Scaffold a new commerce agent:

```bash
codespar init my-agent
```

The CLI prompts you to pick:

- Framework (Claude, OpenAI, Vercel AI SDK, LangChain, Mastra, CrewAI)
- Starter template (Pix agent, e-commerce checkout, streaming chat, multi-tenant)
- Servers to pre-configure

Output is a runnable project with `.env.example`, SDK wired up, and a README.

### Meta-tool sugar (SDK 0.9.0+)

Nineteen top-level commands, counted on the published 0.11.3, wrap the typed `Session` methods that landed in `@codespar/sdk@0.9.0` plus the consumer wallet flows that landed in the CLI 0.5.x line. They short-circuit the `tools execute <name> --input '<json>'` dance for the most common flows.

#### Discover

Semantic + lexical search across the catalog (powered by pgvector + pg_trgm):

```bash
# Find tools matching a natural-language intent
codespar discover "issue an NF-e for a service"

# Bias by vertical / country / cap result count
codespar discover "Pix charge" --category payments --country BR --limit 5

# Raw JSON for scripting
codespar discover "kyc verification" --json
```

#### Charge (inbound) and Ship

`charge` opens a session and calls `session.charge(args)`; `ship` calls `session.ship(args)`. Args via `--input` JSON or `--input-file`. Meta-tools route — no `--server` required.

```bash
codespar charge --input '{
  "amount": 5000,
  "currency": "BRL",
  "method": "pix",
  "description": "Pedido #1234",
  "buyer": { "name": "Cliente", "document": "...", "phone": "..." }
}'

codespar ship --input-file ./shipment.json
```

`ship` validates `action ∈ {label, quote, track}` and the per-action required fields.

#### Payment status (poll or stream)

After a `charge` returns a `tool_call_id`, watch settlement:

```bash
# Poll once
codespar payment-status tcl_abc123

# Follow until interrupted (polls; SIGINT stops it)
codespar payment-status tcl_abc123 --stream

# Bound the wait
codespar payment-status tcl_abc123 --stream --timeout 30000
```

#### Verification status (KYC, poll or stream)

KYC sibling for tracking `codespar_kyc` inquiry settlement:

```bash
codespar verification-status tcl_xyz789
codespar verification-status tcl_xyz789 --stream
```

#### Wizard

Inspect what a server requires before connecting + drive the connect flow:

```bash
# List connectable servers
codespar wizard --action list

# Status of an existing connection
codespar wizard asaas

# Initiate a new connection (oauth / path-secret / cert)
codespar wizard banco-do-brasil --action initiate --return-to https://yourapp.dev/callback
```

#### Mandate create (multi-slot)

Mint a multi-slot mandate: one wallet, one signature, per-currency spend authority. Repeat `--slot` once per currency, in the form `CURRENCY:METHOD:CAP:PER_TX`:

```bash
# One signature covers both slots: BRL over Pix, USDC over the usdc rail
codespar mandate create \
  --slot BRL:pix:50000:10000 \
  --slot USDC:usdc:100:25
```

The example above authorizes R$500.00 total (R$100.00 per transaction) on the BRL slot and 100 USDC total (25 per transaction) on the USDC slot. All slots share one mandate id and one signature; there is no FX inside the wallet.

#### Wallet

Inspect a consumer's per-currency spend authority:

```bash
codespar wallet consumer_abc123
```

Prints one row per slot with `authorized`, `spent`, and `available`. Add `--json` for scripting.

#### Transfer

Move balance between slots. The default is a **plan** (shows the route, rate, and legs without moving money); pass `--execute` to run it:

```bash
# Plan a BRL -> USDC move of R$150.00
codespar transfer --from BRL --to USDC --amount 15000

# Execute the planned route
codespar transfer --from BRL --to USDC --amount 15000 --execute
```

Onramp and offramp routes execute today; other slot pairs answer `501` until their rails are wired.

#### Spend

Pay within a mandate. `--payee` takes a Pix key, an EVM address or an x402 resource URL, and a payee that resolves to x402 or USDC routes to the USDC slot automatically:

```bash
# Pay a Pix key from the BRL slot
codespar spend --mandate cm_abc123 --payee vendedor@empresa.com.br --amount 2500
```

There is no flag for a copia-e-cola string. `--payee` takes the key, not the payload a QR code encodes; paying a copia-e-cola goes through `codespar pay` or the `codespar_pay` meta-tool.

Every spend is checked against the slot's cap and per-transaction limit before any provider dispatch.

<Callout>
For the full surface of all 14 meta-tools (`codespar_pay`, `codespar_charge`, `codespar_checkout`, `codespar_shop`, `codespar_wallet`, `codespar_invoice`, `codespar_notify`, `codespar_ship`, `codespar_crypto_pay`, `codespar_kyc`, `codespar_ledger`, `codespar_issue`, `codespar_discover`, `codespar_manage_connections`; `codespar_get_started`, the onboarding planner, sits beside them), see [Meta-tools](/docs/concepts/meta-tools/charge). Anything not covered by the sugar commands above is reachable via `codespar tool <meta-tool> --input '<json>'`.
</Callout>