The codespar CLI — authenticate, list servers, execute tools, manage connections, and scaffold projects from your terminal.

CodeSpar CLI

@codespar/cliv0.4.0

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.

The CLI is the fastest way to explore the server catalog, run smoke tests, and debug production sessions — no frontend or SDK integration required.

Install

npm install -g @codespar/cli

Verify the install:

codespar --version

If codespar: command not found after install, make sure your global npm bin directory is on your $PATH. Run npm config get prefix to check.

Authenticate

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.

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.

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

Stream or inspect execution logs:

# Tail logs in real time
codespar logs tail

# Filter by server, tool, or status
codespar logs tail --server stripe --status error

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

Six top-level commands wrap the typed Session methods that landed in @codespar/sdk@0.9.0. 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

For the full surface of all 9 meta-tools (codespar_pay, codespar_charge, codespar_invoice, codespar_notify, codespar_ship, codespar_crypto_pay, codespar_kyc, codespar_discover, codespar_manage_connections), see Meta-tools. Anything not covered by the sugar commands above is reachable via codespar tools execute <meta-tool> --input '<json>'.

Configuration

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

Command-line flags (--api-key, --project)
Environment variables (CODESPAR_API_KEY, CODESPAR_PROJECT)
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'

# Latency of the last 50 tool calls for `stripe`
codespar logs tail --server stripe --limit 50 --json | jq '.[] | .duration_ms'