@codespar/cli

@codespar/cli

Command-line interface for CodeSpar — authenticate, inspect servers, execute tools, and manage sessions from your terminal.

Install

npm install -g @codespar/cli

Verify:

codespar --version

Quick start

# One-time: authenticate with your API key
codespar login

# Inspect the catalog
codespar servers list
codespar servers show stripe
codespar tools list --server asaas
codespar tools show codespar_pay

# Run a one-shot tool call
codespar execute codespar_pay \
  --server asaas \
  --input '{"method":"pix","amount":15000,"currency":"BRL"}'

# Manage sessions
codespar sessions list
codespar sessions show ses_abc123 --logs
codespar sessions close ses_abc123

Commands

Command	What it does
login	Save your API key to ~/.codespar/config.json
logout	Clear the stored API key
whoami	Show authenticated user, org, project, and key scopes
servers list	List the server catalog (filter by --category, --region)
servers show <id>	Show a server's details and tools
tools list	List tools (filter by --server)
tools show <name>	Show a tool's full input/output schema
execute <tool>	Run a single tool call in a throwaway session
sessions list	List recent sessions (filter by --status, --limit)
sessions show <id>	Show session details (add --logs for tool calls)
sessions close <id>	Close an active session
connect list	List active Connect Links per user
connect start <server>	Start an OAuth Connect Link flow (add --open to launch it)
connect revoke <server>	Revoke a connection
logs tail	Stream tool-call logs in real time (filter by --server, --status, --tool)
init <name>	Scaffold a new commerce agent from a template

Templates available via init

Slug	Stack	What you get
pix-agent	Node + OpenAI	Minimal Pix charge + WhatsApp notify loop
ecommerce-checkout	Node + Claude	Full Complete Loop: checkout → invoice → ship → notify
streaming-chat	Next.js + Vercel AI	Token-by-token streaming commerce chat
multi-tenant	Next.js + OpenAI	One API key, N tenants, per-tenant billing

Every command supports:

• --json — machine-readable JSON output (pipe into jq)
• --api-key <key> — override the stored key
• --base-url <url> — point at a custom API (staging, self-hosted)

Configuration

Resolution order (first match wins):

• Command-line flags (--api-key, --base-url)
• Environment variables (CODESPAR_API_KEY, CODESPAR_BASE_URL)
• Config file at ~/.codespar/config.json (chmod 600)

Scripting

Output is valid JSON on stdout and human messages on stderr, so you can pipe cleanly:

# IDs of all servers that handle Pix
codespar servers list --json \
  | jq -r '.[] | select(.capabilities | contains(["pix"])) | .id'

# p95 latency of the last 100 stripe calls in a session
codespar sessions show ses_abc123 --logs --json \
  | jq '[.logs[] | select(.server == "stripe") | .duration_ms] | sort | .[95]'

Use --json explicitly when piping — the CLI defaults to tables in a TTY.

Development

This package lives in the codespar-core monorepo.

# From repo root
npm install
npm run build --workspace @codespar/cli
npm run typecheck --workspace @codespar/cli

# Run the local build directly
node packages/cli/dist/index.js --help

License

MIT © CodeSpar