CLI Reference

The akili CLI is the primary developer interface for the Akili Data Product Platform. It is a thin wrapper around the control plane API — every command maps to an API call with no local business logic.

Installation

# From the platform release
curl -sSL https://releases.akili.dev/cli/latest/install.sh | sh

# From source
cargo install --path platform/control-plane/crates/akili-cli

Command Groups

Command	Description
akili auth	Authentication management — login, logout, status, token
akili product	Manage data products — create, list, show, deploy, delete
akili tenant	Manage tenants — create, list, suspend, reactivate, archive
akili run	Manage executions — trigger, list, get, cancel, view steps
akili registry	Registry and dependency graph — search, impact analysis, contracts
akili dlq	Dead letter queue — list, inspect, replay, purge
akili governance	Governance — quality, lineage, SLA, retention, policies, concepts
akili discovery	Discovery and search — full-text search, NL-to-SQL query, sample
akili connection	Connection management — create, test, discover resources, schema
akili domain	Domain management — list, get, view domain products
akili ingestion	Ingestion management — state, backfill, list
akili validate	Validate manifest files against the platform schema
akili scaffold	Scaffold a new data product with manifest templates
akili config	CLI configuration — init, show, set profile, path

Additional Commands

Command	Description
akili status	Check platform health (API connectivity and auth status)
akili version	Print CLI and API version information
akili completion <shell>	Generate shell completions (bash, zsh, fish, powershell)
akili graph <args...>	Delegate to the akili-graph CLI for graph operations

Global Options

Every command accepts these flags. They are defined on the root command and inherited by all subcommands.

Flag	Short	Type	Default	Description
--json		bool	false	Output as JSON instead of tables
--no-color		bool	auto-detect	Disable ANSI color codes
--verbose	-v	bool	false	Print verbose output including HTTP request/response details
--quiet	-q	bool	false	Suppress non-essential output
--profile		string		Config profile to use (from config.toml)
--api-url		string	http://localhost:8080	API base URL override
--timeout		integer	30	Request timeout in seconds

Precedence

Configuration values are resolved in this order (highest priority first):

1. CLI flag (e.g., --api-url)
2. Environment variable (e.g., AKILI_API_URL)
3. Config file (~/.config/akili/config.toml)
4. Built-in default

Environment Variables

Variable	Maps to
AKILI_API_URL	--api-url
AKILI_TOKEN	Authentication token
AKILI_OUTPUT	Output format
AKILI_TIMEOUT	--timeout

Configuration

The CLI reads configuration from ~/.config/akili/config.toml. Initialize it with akili config init.

# Default profile
[default]
api_url = "https://api.akili.systems"

# Named profiles
[profiles.staging]
api_url = "https://staging-api.akili.systems"

[profiles.local]
api_url = "http://localhost:8080"

Switch profiles with the --profile flag:

akili --profile staging product list

Tokens are stored separately with 0600 file permissions. For CI/CD, use the AKILI_TOKEN environment variable instead of a config file.

See akili config for full configuration management.

Exit Codes

Code	Meaning	When
0	Success	Command completed successfully
1	General error	Unspecified failure
2	Usage error	Invalid flags, missing arguments
3	Authentication error	Token expired, invalid, or missing
4	Not found	Requested resource does not exist (HTTP 404)
5	Validation error	Manifest validation failed (HTTP 422)
6	Conflict	Resource already exists or state conflict (HTTP 409)
7	Rate limited	Too many requests (HTTP 429)
8	Server error	API returned 5xx
9	Timeout	Request exceeded --timeout duration
10	Network error	Cannot reach API (DNS, connection refused, TLS)

CI/CD Usage

Scripts should check specific exit codes, not just zero vs. non-zero:

akili product validate ./my-product/
case $? in
  0) echo "PASS: validation succeeded" ;;
  3) echo "FAIL: authentication -- check AKILI_TOKEN" ;;
  5) echo "FAIL: validation errors found" ;;
  *) echo "FAIL: unexpected error $?" ;;
esac

Output Formats

The CLI supports two output modes:

• Table format (default in TTY): Human-readable aligned columns with ANSI colors. Long values are truncated. List commands show a summary line.
• JSON format (--json or piped output): Raw API response body with no wrapping or transformation. Suitable for jq and scripting.

Errors always go to stderr. Data always goes to stdout. This ensures piping works correctly:

akili product list --json | jq '.[] | .name'

Long-running operations (deploy, trigger) display a spinner on stderr with elapsed time when connected to a TTY.