> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getlago.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Overview
> The Lago API from your terminal. One binary, every endpoint, safe defaults.
The [Lago CLI](https://github.com/getlago/lago-cli) is generated from the Lago OpenAPI spec. Every endpoint is a command, every API field is a flag. It works with Lago Cloud US, Lago Cloud EU, and self-hosted Lago.
## Install
Homebrew on macOS and Linux installs the binary, the man page and the shell completions:
```bash theme={"dark"}
brew install getlago/tap/lago
```
Anywhere Go 1.27 or later runs:
```bash theme={"dark"}
go install github.com/getlago/lago-cli/cmd/lago@latest
```
Release archives for macOS, Linux and Windows, with checksums signed by cosign, are on the [releases page](https://github.com/getlago/lago-cli/releases). `lago version` prints the CLI version and the API spec version it was built from. `lago upgrade` tells you whether a newer release exists and the command to install it.
If `lago version` prints a Docker Compose version, a shell alias named `lago` from a self-hosted Lago setup is shadowing the binary. Run `unalias lago` and remove the alias from your shell profile.
## Configure
Get an API key from **Developers > API keys** in the Lago app, then:
```bash Cloud US theme={"dark"}
lago init --api-key "$LAGO_API_KEY" --region us --mode test
```
```bash Cloud EU theme={"dark"}
lago init --api-key "$LAGO_API_KEY" --region eu --mode test
```
```bash Self-hosted theme={"dark"}
lago init --api-key "$LAGO_API_KEY" --region self-hosted --api-url https://lago.example.com --mode test
```
`init` checks the key against the API before saving anything to `~/.config/lago/config.toml`. Pass the base URL only: the CLI adds `/api/v1`. The dashboard URL (`app.getlago.com`) is refused, because it is not the API.
`lago whoami` shows the profile and the exact host requests go to. `lago doctor` checks configuration, network, and authentication.
## First commands
```bash theme={"dark"}
lago billable-metrics create --name Requests --code api_requests --aggregation-type count_agg
lago customers create --external-id acme_001 --name "Acme Inc." --currency USD
lago customers get acme_001
lago customers list --limit 5
lago customers get acme_001 --output json --query 'customer.email'
```
`lago seed demo` creates a full chain (metric, plan, customer, subscription, event, invoice preview) in one command.
## How it works
### Flags are API fields
A `snake_case` field is a `--kebab-case` flag. Nested fields carry their parent as a prefix. Objects and arrays take JSON. `--input` sends a whole request body.
```bash theme={"dark"}
lago customers create --external-id acme_001 --billing-configuration-payment-provider stripe
lago customers create --input @customer.json
```
### Creates print identifiers
A `create` or `update` prints the identifier block. Add `--output json` for the full resource.
```console theme={"dark"}
$ lago customers create --external-id acme_001 --name "Acme Inc." --currency USD
LAGO_ID 1a901a90-1a90-1a90-1a90-1a901a901a90
EXTERNAL_ID acme_001
NAME Acme Inc.
```
### Responses are wrapped
The API wraps every response in its resource name. A `--query` starts with that wrapper. A query that matches nothing prints `null` and lists the available keys on stderr.
```bash theme={"dark"}
lago customers get acme_001 --query 'customer.email'
lago customers list --query 'customers[].external_id'
```
### Destructive operations ask first
`delete`, `void`, `finalize`, `terminate`, and `retry-payment` prompt for the identifier. In a script, pass it with `--confirm`.
```bash theme={"dark"}
lago invoices void 1a901a90-1a90-1a90-1a90-1a901a901a90 --confirm 1a901a90-1a90-1a90-1a90-1a901a901a90
```
### Live is the default mode
`--mode test` is a safety declaration, not a sandbox. Live mode prints `[LIVE]` and gates destructive operations. Credentials passed by flag or environment run live unless you set a mode.
### Nothing is sent on `--dry-run`
The CLI prints the method, URL, redacted headers, and exact body. No connection is opened.
```bash theme={"dark"}
lago customers create --external-id acme_001 --name "Acme Inc." --dry-run
```
## Scripting
| Flag | Use |
| -------------------- | -------------------------------------------------------------------------------------------- |
| `--output json` | Full resource. Also `yaml`. Default is `table`. |
| `--query ` | Select from the response. Implies `--output json`. |
| `--all` | Every page of a `list`, streamed 100 at a time. Pipe to `jq`. Not combinable with `--query`. |
| `--limit`, `--page` | One page. `--limit` takes 1 to 1000. |
| `--dry-run` | Print the request, send nothing. |
| `--confirm ` | Confirm a destructive operation non-interactively. |
| `--profile ` | Switch organization or region. |
```bash theme={"dark"}
lago customers list --all --output json | jq -r '.customers[].external_id'
lago invoices list --output json --query 'invoices[?status==`"finalized"`].total_amount_cents'
lago api GET /customers?page=2 # any endpoint, same auth and output handling
```
Precedence is flags, then environment, then profile.
| Environment variable | Sets |
| -------------------- | ---------------- |
| `LAGO_API_KEY` | API key |
| `LAGO_API_URL` | API base URL |
| `LAGO_MODE` | `live` or `test` |
| `LAGO_PROFILE` | Profile name |
## Exit codes
| Code | Meaning |
| ---- | ------------------------------------------------------- |
| 0 | Success |
| 2 | Usage error, including a missing `--confirm` |
| 3 | Authentication |
| 4 | Not found. The error names the resource type and value. |
| 5 | Validation or other 4xx |
| 6 | Rate limited |
| 7 | Server 5xx |
| 8 | Network or timeout |
Money is exact: `*_amount_cents` are integers, `units` are decimal strings. The CLI sends no telemetry.
One page per command group, with commands and their output side by side.
The schemas the CLI is generated from.