Commands by area

Commands

Servers

Browse the server catalog:

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

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

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.

Sessions

Inspect and manage sessions:

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

# 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

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

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

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

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:

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

codespar verification-status tcl_xyz789
codespar verification-status tcl_xyz789 --stream

Wizard

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

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

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

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:

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

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