Execution and operation

Seven leaf commands run a tool and account for what it did: execute, ship, tools show, sessions list, sessions show, sessions close and logs tail. sessions, tools and logs are groups with no action of their own. Running one alone prints its own usage to stderr and exits 1.

They are not one client. sessions *, tools * and logs tail speak HTTP directly from the CLI. execute and ship go through the SDK, which opens a session, runs the call inside it and deletes the session in a finally. That seam is not cosmetic: measured, the two halves answer the same rejected key with different exit codes and disagree about what --project accepts. Both are below.

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. A resolved project rides on every request as the x-codespar-project header; with no project resolved the header is absent.

With no key resolved, all seven refuse before opening a socket, with the same line:

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

That check runs inside the command, so an argument Commander itself rejects is reported first: codespar execute with no credential and no --server answers error: required option '-s, --server <id>' not specified, not the credential line.

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 receives the data alone.

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

Two commands on this page take --json and ignore it, because they have no JSON path at all: sessions close prints its confirmation to stderr and leaves stdout empty either way, and ship without --json writes nothing to stdout.

Exit codes

The same seam shows on rejected credentials. A 401 on sessions list is one line and exit 1; a 401 on execute or ship, raised while creating the session, is exit 2 with a stack trace naming createSession failed: 401.

codespar execute <tool>

Opens a throwaway session against one server, sends one tool call into it, prints the result envelope, and deletes the session in a finally. Three requests per run: POST /v1/sessions, then the execute, then DELETE /v1/sessions/{id}.

With neither --input nor --input-file, the input is the empty object {}.

codespar execute codespar_ship \
  --server melhor-envio \
  --input '{"action":"quote"}'

{
  "success": true,
  "data": {
    "id": "shp_01J",
    "status": "quoted",
    "carrier": "Correios",
    "cost_minor": 2140,
    "estimated_delivery": "2026-09-17"
  },
  "duration": 734,
  "server": "melhor-envio",
  "tool": "codespar_ship",
  "tool_call_id": "tcl_01J"
}

Without --json, stdout carries the same envelope and stderr carries one line, ✓ codespar_ship succeeded in 734ms. With --json, stderr is empty and stdout is unchanged: the envelope is already the machine-readable form.

Calls POST /v1/sessions with {"servers": ["<--server>"], "user_id": "<--user>"}, then POST /v1/sessions/{id}/execute with {"tool": "<tool>", "input": {...}}, then DELETE /v1/sessions/{id}. All three measured on the wire. The SDK equivalent is session.execute.

codespar ship

Opens a session attached to no server, runs the codespar_ship meta-tool inside it, and closes it. The meta-tool picks the carrier, so there is no --server: the whole operation arrives as one JSON object under --input.

The CLI checks four things before it opens the session, and nothing else. These are the fields it names, read from the command's own validator:

codespar ship --input '{
  "action": "quote",
  "origin": { "postal_code": "01310100" },
  "destination": { "postal_code": "22041011" },
  "items": [{ "weight_g": 500 }]
}'

✓ ship shp_01J → quoted
ℹ Carrier: Correios
ℹ ETA: 2026-09-17
ℹ Cost (minor units): 2140

The human form prints, when the result carries them and only then, the tracking code, the carrier, the label URL, the estimated delivery and the cost in minor units. Every one of those lines goes to stderr; without --json this command writes nothing at all to stdout. With --json, stdout carries the typed result object and stderr is empty.

Calls POST /v1/sessions with {"servers": [], "user_id": "<--user>"}, then POST /v1/sessions/{id}/execute with {"tool": "codespar_ship", "input": {...}}, then DELETE /v1/sessions/{id}. The SDK equivalent is session.ship.

All six validations run before the session is opened, so a rejected payload costs no request.

codespar tools show <name>

Prints one tool's identity and its prose description, found inside its server's tool listing.

codespar tools show codespar_ship

Name    codespar_ship
Server  codespar

Quote, label or track a shipment.

Input schema:
{
  "type": "object",
  "properties": {
    "action": {
      "enum": [
        "label",
        "quote",
        "track"
      ]
    }
  },
  "required": [
    "action"
  ]
}

The description, the input schema and the output schema each print only when the route returns them; the Name and Server pair always prints. An Output schema: block follows the input one under the same rule.

Calls GET /v1/servers/{id}/tools and finds the named tool in the listing.

codespar tools list

Lists tools across the catalog, or one server's, with each description cut to fit a terminal column. It takes -s, --server <id>, which is sent as the server query parameter, and the root --json. Its full block, including the truncation rule and the empty-result behaviour, is on Catalog and discovery, because it reads the catalog rather than a running session, which is why it lives there.

codespar sessions list

Lists the sessions the key can see as a six-column table, newest first as the route returns them. Both filters are forwarded to the route verbatim; the CLI parses neither and defaults neither.

✗ --status expects one of active, closed, error, got "inventado".
✗ --limit expects a positive whole number, got "abc".

codespar sessions list --status active --limit 5

ID        USER      STATUS  SERVERS  TOOL CALLS  CREATED
ses_01J8  cli-user  active  asaas    3           2026-09-12 14:02:11
ses_01J7  agent-7   closed           12          2026-09-12 11:47:03

A missing field prints -; SERVERS is the list joined with commas, and CREATED is the timestamp cut to YYYY-MM-DD HH:MM:SS. An empty result prints (no results) on stderr with nothing on stdout, and still exits 0; --json prints [].

Calls GET /v1/sessions, reading the rows from a data array in the response.

codespar sessions show <id>

Prints one session as a seven-line key/value block, and with --logs fetches that session's tool calls in a second request and prints them as a table underneath.

codespar sessions show ses_01J8 --logs

ID          ses_01J8
User        cli-user
Status      active
Servers     asaas
Tool calls  2
Created     2026-09-12T14:02:11.000Z
Closed      -

Logs:
TOOL             SERVER    STATUS   MS   AT
codespar_ship    codespar  success  812  14:02:14
codespar_charge  codespar  error    190  14:03:01

Created and Closed print the raw timestamp, unlike the list, which trims it. The log table's AT column is the time of day only.

Calls GET /v1/sessions/{id}, plus GET /v1/sessions/{id}/tool-calls when --logs is given.

codespar sessions close <id>

Closes an active session by id and prints one confirmation line. It takes no flags of its own, and --json does nothing: stdout stays empty either way.

codespar sessions close ses_01J8

✓ Session ses_01J8 closed at 2026-09-14T16:41:02.118Z.

codespar logs tail

Reads the project's recent tool calls and prints one fixed-width line each, oldest first. With --follow it keeps polling for new ones until you interrupt it.

| --json | boolean | no | Root flag. One JSON document per entry (see below) |

codespar logs tail --status error --tool codespar_charge

14:02:14  SUCCESS  codespar_ship             melhor-envio      812ms
14:03:01  ERROR    codespar_charge           asaas             190ms no_eligible_providers

The columns are padded to fixed widths (status to 7, tool to 24, server to 16), with the status green, red or yellow for success, error and running. Tailing logs — press Ctrl-C to stop goes to stderr before the first frame. A frame the parser cannot read is skipped in silence, which is how keep-alives pass through.

Calls GET /v1/tool-calls, once without --follow and once per poll with it.

The first two, verbatim:

✗ Auth failed (401). Check CODESPAR_API_KEY or re-run `codespar login`.

Related

• codespar_ship: the schema, the carriers and the result shapes behind codespar ship
• Sessions: the HTTP routes the session commands call, and the async-settlement flow a tool call starts
• session.execute and session.ship: the SDK calls execute and ship wrap
• Catalog and discovery: tools list, and the commands that find a tool worth executing
• Debugging: what to do with a tool call once you have its id