Identity and config

Four commands carry everything the codespar binary knows about who you are. login writes a key to disk, whoami proves that key resolves to an org and a project, logout removes it, and init is the one command in this group that never reads a credential at all.

Measured 12/09/2026, against the repository build of the CLI (packages/cli/dist, compiled 11/09) pointed at an HTTP stub on 127.0.0.1. Every transcript below is captured output and no probe reached the production API. Where a line comes from reading the source instead of running it, the sentence says so.

Where a value comes from

Two values leave the chain at login. It skips baseUrl in the file and resolves the host from the flag, then the variable, then https://api.codespar.dev. It also never sees --api-key, because the root command and the subcommand declare the same flag.

Three sources, first match wins, resolved one value at a time rather than one source at a time (a key from the environment and a project from the file is a normal combination):

1. Root flags: --api-key, --base-url, --project
2. Environment: CODESPAR_API_KEY, CODESPAR_BASE_URL, CODESPAR_PROJECT
3. The file at ~/.codespar/config.json

The base URL falls back to https://api.codespar.dev when no source carries one. The project has no fallback: without it the server applies the org default.

codespar login

Reads an API key from the terminal, spends one GET /v1/whoami call proving the key works, and only then writes it to ~/.codespar/config.json with mode 0600. A key that fails validation is never persisted.

Flags

Root flags still apply. --base-url is the one that matters here: login resolves the host from --base-url, then CODESPAR_BASE_URL, then https://api.codespar.dev. Read from the source: login is the one command that does not consult baseUrl in the config file, so a bare codespar login after a login against a staging host rewrites the stored host back to production.

printf 'csk_test_probekey\n' | codespar login

ℹ Get your API key at https://codespar.dev/dashboard/…
API key:
✓ Logged in as ana@loja.com.br
ℹ Organization: Loja Exemplo

The dashboard URL is truncated above on purpose: the docs audit rejects any paragraph that pairs that path with key language. Mint keys at Dashboard → API Keys.

API key: is written to stdout, not stderr, so codespar login > log.txt swallows the prompt and leaves the terminal looking hung. The ℹ and ✓ lines go to stderr.

On a TTY the key is read without echo: the prompt prints once and the typed characters are swallowed, so a pasted key does not land in your scrollback.

What it writes

{
  "apiKey": "csk_test_probekey",
  "baseUrl": "http://127.0.0.1:8931"
}

What it calls one GET /v1/whoami, the same route as codespar whoami.

Refusals

codespar whoami

Spends one GET /v1/whoami with the resolved credential and prints the five lines the CLI derives from the response. It is the cheapest way to see which org, project and environment a key actually lands on.

Flags none of its own. codespar whoami --help lists only -h, --help; the root flags do the work.

Human output, line by line

Each placeholder was measured against a stub that answered {}. (all) is the CLI's word for "the response carried no key.scopes array", not a statement the API made about the key.

codespar whoami

User          ana@loja.com.br
Organization  Loja Exemplo
Project       checkout-prod
Key env       test
Scopes        sessions:write, charges:write

With --json the response body is printed verbatim, with nothing on stderr:

codespar whoami --json | jq -r '.key.environment'

The flag is declared on the root command but Commander accepts it in both positions, so codespar whoami --json and codespar --json whoami behave the same.

Refusals

codespar logout

Removes the apiKey key from ~/.codespar/config.json and leaves everything else in place. No network call, no credential needed.

Flags none. --json is accepted and ignored: measured, codespar logout --json exits 0 with zero bytes on stdout and ✓ Logged out. on stderr. A script that parses that output gets an empty string.

codespar logout
cat ~/.codespar/config.json

✓ Logged out.
{
  "baseUrl": "http://127.0.0.1:8931"
}

Two measured edges worth knowing before you trust it:

• On a machine that never logged in, logout still creates ~/.codespar/config.json containing {}, with mode 0600.
• It clears the file, not the environment. With CODESPAR_API_KEY exported, the next command is still authenticated. Measured: whoami succeeded after logout with the key in the environment.

codespar init <name>

Copies one of four templates shipped inside the package into ./<name> and substitutes {{name}} in both file contents and file names. Zero network, and no credential: measured with an empty config file and no CODESPAR_* variable set.

Argument and flags

Templates

codespar init loja-pix -y
ls -a loja-pix

ℹ Creating loja-pix using the Pix Payment Agent template...
✓ Created loja-pix/

Next steps:
  cd loja-pix
  cp .env.example .env   # then fill in your keys
  npm install
  npm run dev

.env.example  .gitignore  README.md  package.json  src  tsconfig.json

Without -t and without -y the command prints the four templates on stdout and asks Pick a number [1-4] (default 1):. An empty answer takes the first one.

Refusals

The config file

One file, ~/.codespar/config.json, created by login and rewritten by logout. Three keys are read and nothing else:

Every write goes through the same helper, which merges into whatever is already on disk and then chmods the file to 0600, because the file holds a credential. Measured after login: -rw-------.

Environment variables

Three carry credential and scope, and win over the file:

Three more shape the output rather than the request:

Root flags

Declared once on the root command and valid for every subcommand:

Whatever resolves ends up on the wire: every request carries Authorization: Bearer <key>, Content-Type: application/json and User-Agent: codespar-cli/<version>, plus x-codespar-project when a project resolved. Measured with --project proj_from_flag alongside CODESPAR_PROJECT=proj_from_env: the header carried the flag's value.

Exit codes and streams

Tables, key/value blocks and JSON go to stdout. The ℹ, ✓ and ⚠ lines go to stderr, so codespar whoami --json | jq sees only the document. The exception in this group is the API key: prompt and the init template picker, both of which write to stdout.

Next steps