---
title: "Overview"
description: "Install the CLI, authenticate it, and run the whole money story from a terminal: mint a cap, spend under it, read the wallet back."
---

import { Callout } from "fumadocs-ui/components/callout";

<VersionBadge pkg="@codespar/cli" />

`codespar` is the CodeSpar API with a terminal in front of it. The 134 commands are derived from the same OpenAPI document the SDK and the HTTP reference are, so anything you can call over HTTP you can also call here, with a key and no integration.

<TerminalDemo />

The terminal above is not a mock. Four commands are the whole money story: log in, mint a capped mandate, spend against it, read the wallet back.

## Install

```bash
npm install -g @codespar/cli
codespar --version
```

<Callout>
If `codespar: command not found` after install, your global `npm bin` directory is not on `$PATH`. `npm config get prefix` tells you where it is.
</Callout>

## Authenticate

```bash
codespar login
```

It **prompts for an API key** and saves it to `~/.codespar/config.json`. No browser opens. Pass `--api-key` to skip the prompt.

In CI, where there is nobody to prompt, use the environment instead:

```bash
export CODESPAR_API_KEY=csk_test_...
codespar whoami
```

`whoami` is the right first call, and the right first thing to run when something stops working: it answers whether the key is valid, which organization and project it is bound to, which environment it acts in, and which scopes it holds. Four questions in one call.

## The four commands

```bash
# 1. authenticate once per machine
codespar login

# 2. mint a mandate: a cap the agent cannot exceed
codespar mandate create --consumer csm_0000 --currency BRL --cap 50000

# 3. spend against it — refused if it would exceed the cap
codespar spend --mandate cm_0000 --payee vendedor@empresa.com.br --amount 2500

# 4. read the wallet back — the consumer is positional
codespar wallet csm_0000
```

The cap is enforced on the server, not here: a spend that would exceed it is refused whatever the client asks. That is the point of step 2, and it is why step 3 can be handed to an agent.

## By the job you are doing

Each page below teaches its commands with a worked example and the real output, and names which refusal a retry can fix.

<NextStepsGrid items={[
  { label: "CLI", title: "Identity and config", description: "login, logout, whoami and init, plus the three places the CLI looks for a credential and the order it looks in.", href: "/docs/cli/identity-and-config" },
  { label: "CLI", title: "Money", description: "The six commands that move or read money: charge, payment-status, wallet, spend, transfer and ledger.", href: "/docs/cli/money" },
  { label: "CLI", title: "Mandates and governance", description: "Mint spend authority, verify a presentation token offline, issue spend cards, read KYC settlement.", href: "/docs/cli/mandates-and-governance" },
  { label: "CLI", title: "Catalog and discovery", description: "Browse the server catalog, search it by intent, and manage per-user provider connections.", href: "/docs/cli/catalog-and-discovery" },
  { label: "CLI", title: "Execution and operation", description: "Run one tool call, read its schema first, follow the session it ran in, tail what it logged.", href: "/docs/cli/execution-and-operation" },
  { label: "CLI", title: "All 134 commands", description: "Every group, every flag, every positional, with a line you can run. Generated from the --help of the published binary and the served OpenAPI document.", href: "/docs/cli/reference" },
]} />

## Related

<NextStepsGrid items={[
  { label: "REFERENCE", title: "API reference", description: "The HTTP operations these commands are derived from.", href: "/docs/api/reference" },
  { label: "REFERENCE", title: "SDK reference", description: "The same operations as typed TypeScript, when a script outgrows a terminal.", href: "/docs/api/sdk" },
  { label: "CLI", title: "Configuration", description: "Config file, environment variables and precedence.", href: "/docs/cli/config" },
]} />