Catalog and discovery

Eight commands cover the catalog and the per-user connections behind it: servers list, servers show, tools list, discover, connect list, connect start, connect revoke and wizard. None of them moves money, and only connect start and connect revoke change anything. Six go straight to a REST route. discover and wizard take a longer path: they open a session, run a meta-tool inside it, and close the session on the way out.

Every flag, message and exit code on this page was run against @codespar/cli 0.10.0 — the version on npm — and the transcripts are the captured bytes of those runs.

What every command here shares

Credentials and scope

Resolution order, first match wins: the root flag, then the environment variable, then ~/.codespar/config.json.

With nothing set, the host is https://api.codespar.dev. On the six commands that call REST directly, a resolved project rides as the x-codespar-project header and an unresolved one leaves the header off. discover and wizard hand the project to the SDK constructor instead.

Without a key, every command on this page refuses before it opens a socket:

codespar servers list

✗ Not logged in. Run `codespar login` or set CODESPAR_API_KEY.

That line is identical on all eight, and discover and wizard give it too: the key is resolved before the SDK is constructed. A key the API rejects is a different story, and the per-command tables below carry it.

stdout, stderr and --json

Tables, key/value blocks and JSON go to stdout. Status lines go to stderr, prefixed ℹ, ✓ or ⚠, and an empty table prints (no results) there too. A pipe into jq therefore receives the data alone.

--json is declared on the root command, but Commander accepts it on either side of the subcommand: codespar --json servers list and codespar servers list --json both printed the same JSON with an empty stderr. Colour is dropped when stdout is not a TTY, when NO_COLOR is set, or when FORCE_COLOR=0.

Exit codes

codespar servers list

Lists the server catalog your key can see, one row per server, filtered server-side by whatever you pass.

Measured wire: codespar servers list -c payments -r BR issued GET /v1/servers?category=payments&region=BR. An absent filter is left off the query string, never sent empty.

codespar servers list

ID          NAME        CATEGORY  REGION  TOOLS  STATUS
asaas       Asaas       payments  BR      12     live
stark-bank  Stark Bank  banking   BR      8      live
pomelo      Pomelo      issuing   -       -      beta

A column with no value prints -. With no rows at all, stdout is empty and stderr carries (no results).

Calls GET /v1/servers, documented at GET /v1/servers in the HTTP reference.

codespar servers show <id>

Reads one server's detail record and prints its metadata, its description and the tools it exposes.

codespar servers show asaas

ID        asaas
Name      Asaas
Category  payments
Region    BR
Status    live
Auth      api_key
Tools     12

Brazilian payment provider: Pix, boleto and card acquiring.

Tools:
  • codespar_charge — Issue an inbound charge
  • codespar_pay — Send an outbound payment

The Tools count prefers the record's own count and falls back to the length of the returned tool list. The description paragraph and the Tools: block are printed only when the response carries them.

codespar tools list

Lists the tools of one server, with each description cut to fit a terminal column.

codespar tools list --server asaas

NAME                 DESCRIPTION
cancel_subscription  Cancel an active subscription.
create_customer      Create a customer. Required before creating any payment — Asaas requi…
create_payment       Create a payment charge (Pix, boleto, or credit card) linked to a cus…

24 tool(s) on asaas.

The DESCRIPTION column is truncated to 70 characters; --json carries the full text.

Calls GET /v1/servers/{id}/tools, which the HTTP reference documents.

codespar discover <query>

Searches the catalog by intent instead of by name: it opens a session attached to no server, runs the codespar_discover meta-tool inside it, prints the ranked matches and closes the session.

Measured wire, in order: POST /v1/sessions with {"servers":[],"user_id":"cli-user"}, then POST /v1/sessions/{id}/execute with {"tool":"codespar_discover","input":{"use_case":"…","category":"…","country":"…","limit":5}}, then DELETE /v1/sessions/{id}. The session is closed in a finally, so it is closed even when the call fails.

codespar discover "issue an NF-e for a service"

ℹ Strategy: embedding  ·  use_case: "issue an NF-e for a service"
#  SCORE  SERVER.TOOL                CONN          DESCRIPTION
1  0.887  codespar.codespar_invoice  connected     Issue an NF-e / NFS-e fiscal document after settlement.
2  0.609  codespar.codespar_charge   not_required  Issue an inbound charge so there is something to invoice.

ℹ Next steps:
  - Connect a fiscal provider
  - Call codespar_invoice with the charge id

Three things the table does not say for itself:

• SCORE is computed by the CLI, not returned by the API. It is 1 - cosine_distance when a cosine distance is present, the trigram similarity when it is not, and - when neither is, always to three decimals. The stub's cosine_distance: 0.1132 printed as 0.887.
• The Strategy line and the Next steps: label go to stderr; the table and the step items go to stdout. The label and its list are split across the two channels.
• CONN is the match's connection status, one of connected, disconnected or not_required, taken from the SDK's own type. It is what tells you whether the tool you just found is callable today or needs a connection first.

With no match at all, stderr carries (no matches) and stdout stays empty.

Calls the codespar_discover meta-tool over POST /v1/sessions/{id}/execute. The tool's own arguments and result are documented at codespar_discover.

codespar connect list

Lists the per-user provider connections your project holds, with the dates cut to the day.

This route answers a connections envelope where servers list and tools list get a data envelope. It matters only if you read the raw HTTP; --json unwraps it either way.

codespar connect list --user user_42 --status connected

ID         SERVER       USER     STATUS     CONNECTED   EXPIRES
ca_7Fq2xb  asaas        user_42  connected  2026-09-02  -
ca_9Kd0mn  mercadopago  user_42  connected  2026-09-09  2026-12-08

CONNECTED and EXPIRES are the first ten characters of the ISO timestamp, so the time of day is visible only under --json. A null date prints -.

Calls GET /v1/connections, documented at GET /v1/connections in the HTTP reference.

codespar connect start <server>

Opens a Connect Link flow for one end user and prints the authorize URL they have to visit.

Measured body: {"server_id":"asaas","user_id":"user_42","redirect_uri":"https://app.exemplo.com.br/connect/done","scopes":"payments:read"}.

codespar connect start asaas --user user_42

ℹ Connect asaas for user user_42:

  https://connect.codespar.dev/l/lnk_3Bq8

ℹ Link expires 13/09/2026, 15:00:00
ℹ Tip: pass --open on a future run to launch the link automatically.

The authorize URL is the only thing on stdout: a blank line, the URL indented by two spaces, a blank line. The expiry is rendered in the machine's own locale and timezone, so it is not a stable string to parse; --json carries the expires_at instant.

Before the OS opener is called, the URL is parsed and checked to be http or https, then passed as a literal argument with no shell in between, so a link carrying shell metacharacters cannot run a command. Both refusals, the malformed URL and the non-http scheme, are swallowed by a catch in this command: nothing is printed and the exit code stays 0. The URL is on stdout either way, which is what the fallback assumes.

Calls POST /v1/connect/start, documented at POST /v1/connect/start in the HTTP reference. The concept behind it is Connect Links.

codespar connect revoke <connection-or-server>

Revokes one connection, taking either the connection id or a server id it resolves on your behalf.

The resolve path costs one extra request: GET /v1/connections?user_id=<user>&server_id=<arg>&status=connected, and then the first row of that list is the one revoked. Measured: codespar connect revoke asaas -u user_42 issued that query and then POST /v1/connections/ca_7Fq2xb/revoke.

codespar connect revoke ca_7Fq2xb

✓ Revoked connection ca_7Fq2xb.

This command has no JSON path. --json is accepted and ignored: measured, codespar connect revoke ca_7Fq2xb --json exits 0 with empty stdout and the same success line on stderr. A script that pipes it into a JSON parser gets an empty string.

Calls POST /v1/connections/{id}/revoke, documented at POST /v1/connections/{id}/revoke in the HTTP reference.

codespar wizard [server-id]

Answers what a provider needs before it can be connected: which are connectable, what one connection's state is, and which secrets and steps a new connection takes.

Measured wire for an initiate: POST /v1/sessions with {"servers":[],"user_id":"cli-user"}, then POST /v1/sessions/{id}/execute with {"tool":"codespar_manage_connections","input":{"server_id":"asaas","action":"initiate","country":"BR","environment":"test","return_to":"/dashboard/connections"}}, then DELETE /v1/sessions/{id}.

The human output has three shapes, and the shape is chosen by the action the result carries, not by the flag you passed.

SERVER      AUTH     STATUS        DIFFICULTY  CONNECTED
asaas       api_key  connected     easy        2026-09-02
stark-bank  cert     disconnected  hard        -

✓ Asaas (api_key) → disconnected
server_id    asaas
difficulty   easy
connect_url  https://app.codespar.dev/connect/asaas
next_action  open_connect_url

ℹ Required secrets:
  - api_key  (starts with $aact_)

ℹ Instructions:
  1. Open the Asaas dashboard
  2. Copy the API key
  3. Paste it into the connect page

ℹ Known pitfalls:
  - The sandbox key does not work in live mode

The third shape, status, prints a success line and a four-row block: display_name, auth_type, difficulty, connected_at. As with discover, the section headings go to stderr and their items to stdout, so a redirect of stdout alone gives you the secrets and the steps without the labels that introduce them. An empty list prints (no connections) on stderr.

Calls the codespar_manage_connections meta-tool over POST /v1/sessions/{id}/execute. The tool itself is documented at codespar_manage_connections.

Both validations run before the session is opened, so a rejected flag costs no request.

Related

• codespar_discover and codespar_manage_connections: the two meta-tools behind discover and wizard
• Connect Links: what connect start is starting
• Servers, Connections and Connect: the HTTP routes these commands call