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

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'

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

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

• Quickstart — Install the SDK after you've explored the catalog via CLI
• Servers — Browse the server catalog in the dashboard
• Authentication — How API keys, service auth, and Connect Links fit together
• Debugging — Deep dive into tool-call logs and observability