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 · Connect your team · Agent guide · API reference

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.

Current version · SHA-256 checksums · Release manifest

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.

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:

$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:

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.
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 for the full list.

Read records and earnings

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

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:

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

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

--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 use the same source. Agents can also request /cli with Accept: text/markdown. Start at llms.txt to find the guide, API schema, and other public documentation.