--- 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 The API exposes no log-streaming endpoint today, so `codespar logs tail` has nothing to connect to. Inspect tool calls through the session and tool APIs instead, or read them in the dashboard. This section stays documented because the commands still ship in the CLI. ```bash # 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 15 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`, `codespar_get_started`), 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' ``` 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