# Habitat CLI for scripts and agents

Work with your music catalog, deals, and royalty data from a terminal.
The Habitat command-line interface (CLI) uses the same team API as your integrations.
Use `hab` in scripts or give this guide to your agent.

[Download and install](#install) · [Connect your team](#connect-your-team) · [Agent guide](#agent-guide) · [API reference](https://app.habitat.financial/api/docs/)

## Install

The CLI is available for macOS, Linux, and Windows. Files are served from Habitat’s public download storage. You do not need access to the source repository.

| Platform | Download |
| --- | --- |
| macOS, Apple silicon | [Download archive](/downloads/cli/latest/hab-aarch64-apple-darwin.tar.gz) |
| macOS, Intel | [Download archive](/downloads/cli/latest/hab-x86_64-apple-darwin.tar.gz) |
| Linux, x86-64 | [Download archive](/downloads/cli/latest/hab-x86_64-unknown-linux-gnu.tar.gz) |
| Linux, ARM64 | [Download archive](/downloads/cli/latest/hab-aarch64-unknown-linux-gnu.tar.gz) |
| Windows, x86-64 | [Download ZIP](/downloads/cli/latest/hab-x86_64-pc-windows-msvc.zip) |

[Current version](/downloads/cli/latest/VERSION) · [SHA-256 checksums](/downloads/cli/latest/SHA256SUMS) · [Release manifest](https://downloads.habitat.financial/cli/latest.json)

Linux binaries require glibc 2.39 or later, as provided by Ubuntu 24.04. They do not run on Alpine Linux.
The binaries are not signed or notarized. Check your organization's software policy before installation.

### macOS and Linux

Download the installer, read it, then run it. It verifies the archive checksum and installs `hab` in `~/.local/bin`.
It does not need administrator access. Run it again to update the CLI.

```sh
curl --fail --silent --show-error https://habitat.financial/install.sh -o install-hab.sh
less install-hab.sh
sh install-hab.sh
export PATH="$HOME/.local/bin:$PATH"
hab --version
```

Set `HAB_VERSION=0.2.0` to install a specific version. Set `HAB_INSTALL_DIR` to change the installation directory.
For a manual installation, download the archive and checksums for the same version. Verify the checksum before extracting the archive.

### Windows PowerShell

Download a version, verify its checksum, and extract it:

```powershell
$version = (Invoke-RestMethod 'https://habitat.financial/downloads/cli/latest/VERSION').Trim()
$base = "https://habitat.financial/downloads/cli/$version"
$file = 'hab-x86_64-pc-windows-msvc.zip'
Invoke-WebRequest "$base/$file" -OutFile $file
$checksums = Invoke-RestMethod "$base/SHA256SUMS"
$line = ($checksums -split "`n" | Where-Object { $_.EndsWith("  $file") })
$expected = ($line -split '\s+')[0]
if (!$expected -or (Get-FileHash $file -Algorithm SHA256).Hash -ne $expected) { throw 'Checksum mismatch' }
Expand-Archive $file -DestinationPath .\hab-cli -Force
.\hab-cli\hab.exe --version
```

Add the extracted directory to your user `Path` to run `hab` from any directory. Repeat these steps to update.

## Connect your team

Use your tenant's HTTPS origin as `HABITAT_BASE_URL`, without `/api` at the end.
The standard origin is `https://app.habitat.financial`. The CLI defaults to `http://localhost:8000` if you do not configure it.

For an interactive session, sign in through your browser:

```sh
hab auth web-login --base-url https://app.habitat.financial
hab auth whoami --json
hab health --json
```

For an agent or unattended script, provide `HABITAT_BASE_URL` and `HABITAT_TOKEN` through your secret manager.
The token must include its `habitatkey_` prefix. The CLI adds the `Authorization: Token` header.
Do not include a real token in prompts, source files, or command examples.

Environment variables override the saved configuration in `~/.config/habitat/config.toml`.
On Windows, this path is relative to your user profile directory.
`hab auth whoami` shows the configured origin and a masked token. It does not validate the token or identify the team.
`hab auth logout` removes the saved token. It does not unset `HABITAT_TOKEN` or revoke the server token.

## Agent guide

1. Read this guide and the [OpenAPI schema](https://app.habitat.financial/openapi.json).
2. Confirm the tenant origin with the user. Ask for credentials through a secret manager.
3. Use tokens with only the scopes needed for the task. Start with read scopes for inspection.
4. Check `hab --version` and `hab <resource> --help` before constructing commands.
5. Use `--json` for data output. Read errors from standard error and check the exit code.
6. Read target records before a write. Confirm the intended records and operation with the user.
7. After a timeout, read the resulting state before retrying a write. A failed response does not prove that nothing changed.

The server enforces team ownership, token scopes, and module permissions. A CLI option cannot override them.
Scope names include `content:read`, `payees:read`, and `statements:read`. Writes need the corresponding `:write` scope.
Read the [scope metadata](https://app.habitat.financial/.well-known/oauth-protected-resource) for the full list.

### Read records and earnings

The following identifiers are examples. Replace them with records from the authorized team.

```sh
hab tracks list --json
hab payees get 42 --json
hab tracks list --page 2 --json
hab payee-track-dsp-earnings list --filter payee_id=42 --filter period=2026-Q1 --json
hab track-dsp-earnings list --filter isrc=USABC2600001 --json
hab statement-sale-items list --filter isrc=USABC2600001 --json
```

Repeat `--filter KEY=VALUE` to supply API query parameters. Use the schema to find parameters supported by each endpoint.
Use `--all` to follow pagination and return a JSON array. Without it, paginated responses retain the API's `results` and `next` fields.
`--all` collects results in memory. Use individual pages for large datasets. Use `--page` separately from `--all`.
Prefer `tracks` for new work. `records` remains a legacy command.

### Make authorized changes

Read the schema for required fields and allowed operations. For example, after approval:

```sh
hab payees update 42 --data '{"payee_name":"Example Artist"}' --json
```

Revenue streams support list, get, and update. Stores and overall period payee earnings are read-only.
The detailed earnings and statement sale item resources support list only.
The CLI also has commands for deals, royalty statements, and report generation. Use their `--help` output for required arguments.
Report generation can return a task identifier. Use the matching generation-status command before treating the report as complete.

### Use a custom endpoint

```sh
hab raw get '/api/tracks/?page=2' --json
```

`hab raw` supports `get`, `post`, `put`, `patch`, and `delete`. Paths start with `/api/`.
Use `--data` for a JSON payload. It does not validate payload fields against the schema.
Non-JSON responses are wrapped in a `raw` field. Report commands return URLs; they do not download report files.

### Exit codes

| Code | Meaning |
| --- | --- |
| 0 | Command completed |
| 2 | Invalid arguments, JSON, or filter syntax |
| 4 | Missing token, authentication failure, or permission denial |
| 5 | Record or endpoint not found |
| 6 | API validation error |
| 10 | Connection, server, or other error |

`--json` applies to resource data and raw requests. Authentication setup commands still print status messages.
A 404 response does not prove that a record exists in another team. Respect the denial and keep the authorized tenant origin.

## Documentation for agents

This page and [its Markdown version](/cli.md) use the same source.
Agents can also request `/cli` with `Accept: text/markdown`.
Start at [llms.txt](/llms.txt) to find the guide, API schema, and other public documentation.