--- title: CLI description: The codespar CLI — authenticate, list servers, execute tools, manage connections, and scaffold projects from your terminal. --- import { Callout } from "fumadocs-ui/components/callout"; # 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. 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 ```bash npm install -g @codespar/cli ``` Verify the install: ```bash 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 Log in with your CodeSpar API key — you only do this once per machine: ```bash 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): ```bash export CODESPAR_API_KEY=csk_live_... codespar whoami ``` ## Commands ### Servers Browse the server catalog: ```bash # 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: ```bash # 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: ```bash 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: ```bash # 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): ```bash # 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 Stream or inspect execution logs: ```bash # 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: ```bash 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 --input ''` dance for the most common flows. #### Discover Semantic + lexical search across the catalog (powered by pgvector + pg_trgm): ```bash # 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. ```bash 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: ```bash # 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: ```bash codespar verification-status tcl_xyz789 codespar verification-status tcl_xyz789 --stream ``` #### Wizard Inspect what a server requires before connecting + drive the connect flow: ```bash # 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`: ```bash # 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: ```bash 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: ```bash # 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: ```bash # 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. For the full surface of all 14 meta-tools (`codespar_pay`, `codespar_charge`, `codespar_checkout`, `codespar_shop`, `codespar_wallet`, `codespar_invoice`, `codespar_notify`, `codespar_ship`, `codespar_crypto_pay`, `codespar_kyc`, `codespar_ledger`, `codespar_issue`, `codespar_discover`, `codespar_manage_connections`), see [Meta-tools](/docs/concepts/meta-tools/charge). Anything not covered by the sugar commands above is reachable via `codespar tools execute --input ''`. ## 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: ```bash codespar config set project proj_abc123 ``` Or per-command: ```bash 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`: ```bash # 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: ```bash codespar servers list --verbose ``` Reset the CLI (clears cached auth, config, and completions): ```bash codespar reset ``` ## Next steps