CodeSpar CLI

The codespar CLI lets you interact with the CodeSpar platform directly from your terminal. Use it to authenticate, inspect servers and tools, execute one-off tool calls, manage per-user connections, and scaffold new agents.

Install

npm install -g @codespar/cli

Verify the install:

codespar --version

Authenticate

Log in with your CodeSpar API key — you only do this once per machine:

codespar login

The CLI opens a browser window for you to authorize, then stores a session token at ~/.codespar/config.json. All subsequent commands use that token.

Alternatively, authenticate non-interactively with an API key (useful in CI):

export CODESPAR_API_KEY=csk_live_...
codespar whoami

Commands

Servers

Browse the server catalog:

# List all servers
codespar servers list

# Filter by category
codespar servers list --category payments
codespar servers list --region 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 mercadopago

# 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

# Dump logs for a specific session
codespar logs show ses_abc123

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

Ten top-level commands 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

# Stream until terminal (SSE; SIGINT cancels cleanly)
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. Accepts a Pix key or a copia-e-cola string; payees that resolve to x402 / USDC route to the USDC slot automatically:

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

# Paste a copia-e-cola string
codespar spend --mandate cm_abc123 --code "00020126580014BR.GOV.BCB.PIX..."

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

Configuration

The CLI reads configuration in this order (first match wins):

1. Command-line flags (--api-key, --project)
2. Environment variables (CODESPAR_API_KEY, CODESPAR_PROJECT)
3. The config file at ~/.codespar/config.json

Project scoping

If you have multiple CodeSpar projects, pin the CLI to one:

codespar config set project proj_abc123

Or per-command:

codespar servers list --project proj_abc123

Scripting

The CLI returns valid JSON on stdout and human-readable messages on stderr, so you can pipe output into jq:

# Servers that support Pix, as a newline-delimited list
codespar servers list --json | jq -r '.[] | select(.capabilities | contains(["pix"])) | .id'

Use --json on any command to force JSON output even in a TTY.

Debugging

Add --verbose to any command to see the underlying HTTP requests:

codespar servers list --verbose

Reset the CLI (clears cached auth, config, and completions):

codespar reset

Next steps