---
title: "CLI command reference"
url: "https://docs.alisx.com/reference/cli/"
---
# CLI command reference

The complete reference for the `alis` command line: global flags, conventions, exit codes, the JSON output contract, and one page per command. It is for people and coding agents who script the CLI and need exact names and defaults.

## Invocation

```bash
alis [command] [subcommand] [arguments] [flags]
```

Run with no arguments, `alis` opens the [TUI](https://docs.alisx.com/tutorials/tour-the-tui.md) and needs an interactive terminal. Run with a command, it is a non-interactive CLI. `alis --help` lists the commands; `alis <command> --help` is the source of truth for that command's flags; `alis docs` prints the operating manual for agents and scripts.

## Global flags

These flags are accepted by every command.

| Flag | Type | Default | Meaning |
|---|---|---|---|
| `--json` | bool | false | Print the result as JSON on stdout. Progress goes to stderr as NDJSON. |
| `--verbose` | bool | false | With `--json` on streamed operations: keep every field, including zero values, and stream full progress snapshots. |
| `--cwd <dir>` | string | current directory | Run in this directory without a shell `cd`. Context is resolved from it. |
| `--approve` | bool | false | Record that a human pre-approved this command. Satisfies an `APPROVAL_REQUIRED` gate. Never satisfies the production gate. |
| `-h`, `--help` | bool | | Help for the command. |
| `-v`, `--version` | bool | | Print the CLI version (root command only). |

## Conventions

Package ID
:   A service is addressed by its package ID, `<org>.<product>.<path>.<vN>`, for example `acme.shop.orders.v1`. Inside the service's folder under `~/alis.build/<org>/build/<product>/` the package ID may be omitted. See [alis context](https://docs.alisx.com/reference/cli/context.md).

Dot references
:   Build environments, products and deployment environments are referenced as `<org>`, `<org>.<product>` and `<org>.<product>.<env>`. Inside a product directory the leading parts fill in from the working directory.

Resource names
:   Operations are `operations/<id>`, accounts are `accounts/<id>`, tickets are `tickets/<id>`; a bare id is accepted where the help says so.

Confirmation flags
:   Many mutating subcommands take `--yes`, which has the same effect as the global `--approve`. Production deployment environments are gated separately by `--confirm-production`.

Long-running commands
:   `define`, `build`, `deploy`, `blocks install|upgrade|publish|uninstall`, `product new` and `operations wait` stream progress to stderr and print the final operation on stdout. `--async` returns the operation name at once; `--timeout <duration>` gives up waiting while the operation continues server-side; `--poll-interval <duration>` sets the polling rate; `--quiet` suppresses stderr progress. Durations use Go syntax, for example `90s`, `10m`, `2h`.

## Exit codes

| Code | Meaning |
|---|---|
| 0 | Success. |
| 1 | Failure: invalid usage, or the remote operation failed. |
| 3 | Confirmation required (`PRODUCTION_CONFIRMATION_REQUIRED` or `APPROVAL_REQUIRED`). |
| 4 | Unauthenticated. Run `alis login`. |
| 5 | No change: a wait reached its `--timeout` with nothing new. |

Full detail: [Exit codes](https://docs.alisx.com/reference/cli/exit-codes.md).

## Output contract in brief

- With `--json`, stdout carries exactly one JSON document: the result, the final operation, or an error envelope `{"error": {"code", "message", "retry", "agent"}}`.
- stderr carries progress as one NDJSON event per line; it never carries results.
- Streamed results are pruned to what is actionable; an absent field means zero or empty. `--verbose` restores every field.
- Read stdout whole; never pipe it through `head`, `tail` or `grep`.

Full detail: [Output contract](https://docs.alisx.com/reference/cli/output-contract.md).

## Environment variables

| Variable | Effect |
|---|---|
| `ALIS_COMMAND_TIMEOUT=<duration>` | Overrides the headless budget after which a command exits with `TIMEOUT`. |
| `ALIS_APPROVE` | Equivalent to `--approve`. Never set it on an agent's behalf. |
| `ALIS_INSTALL=<dir>` | Install directory for the installer and `alis upgrade` (default `~/.alis`). |
| `CLAUDE_SESSION_ID`, `ALIS_SESSION_ID` | Default coding-session id for `alis skills load --session`. |
| `ALIS_APP_URL` | Address `alis preview` reports when no flag names one. |
| `ALIS_SKILLS_LOCAL_DIR` | Set by `alis skills evaluate`; serves a local skill copy to `skills load|resource|apply`. |
| `ALIS_SUGGEST_ALWAYS=1` | Lets the skills suggest hook fire outside `~/alis.build/**`. |
| `ALIS_WORKSPACE_ROOT` | Binds Define, Build and Deploy to a handoff worktree. |

## Commands

| Command | Purpose |
|---|---|
| [accounts](https://docs.alisx.com/reference/cli/accounts.md) | Choose the account responsible for Build subscriptions and billing |
| [ask](https://docs.alisx.com/reference/cli/ask.md) | Ask a question across your skills, sessions and specialist history |
| [authorise](https://docs.alisx.com/reference/cli/authorise.md) | Refresh git and package credentials for a product |
| [blocks](https://docs.alisx.com/reference/cli/blocks.md) | Browse and manage a service's code blocks |
| [build](https://docs.alisx.com/reference/cli/build.md) | Build a service into a new version |
| [clone](https://docs.alisx.com/reference/cli/clone.md) | Clone or refresh a product's define and build repos locally |
| [completion](https://docs.alisx.com/reference/cli/completion.md) | Generate the autocompletion script for a shell |
| [context](https://docs.alisx.com/reference/cli/context.md) | Where this folder sits: its build environment, product, service and deployment environments |
| [define](https://docs.alisx.com/reference/cli/define.md) | Define a service's protos into a new version |
| [deploy](https://docs.alisx.com/reference/cli/deploy.md) | Deploy a service version to a deployment environment |
| [docs](https://docs.alisx.com/reference/cli/docs.md) | Print the operating manual for agents and scripts |
| [doctor](https://docs.alisx.com/reference/cli/doctor.md) | Diagnose the local Alis Build environment |
| [environment](https://docs.alisx.com/reference/cli/environment.md) | Manage deployment environments |
| [gcloud](https://docs.alisx.com/reference/cli/gcloud.md) | Google Cloud auth helpers |
| [git](https://docs.alisx.com/reference/cli/git.md) | Git configuration helpers |
| [herdr](https://docs.alisx.com/reference/cli/herdr.md) | Integrate Alis with herdr |
| [ideate](https://docs.alisx.com/reference/cli/ideate.md) | Read and add to the context gathered in Ideate |
| [login](https://docs.alisx.com/reference/cli/login.md) | Sign in to Alis Build |
| [logs](https://docs.alisx.com/reference/cli/logs.md) | Read build, deployment, and Cloud Run runtime logs |
| [operations](https://docs.alisx.com/reference/cli/operations.md) | Inspect and wait on long-running operations |
| [org](https://docs.alisx.com/reference/cli/org.md) | Manage build environments |
| [packages](https://docs.alisx.com/reference/cli/packages.md) | Install, upgrade and add a service's packages |
| [preview](https://docs.alisx.com/reference/cli/preview.md) | Say where a service's frontend answers, for you and your agent's browser |
| [product](https://docs.alisx.com/reference/cli/product.md) | Manage products |
| [run](https://docs.alisx.com/reference/cli/run.md) | Run a service locally with its environment loaded |
| [service](https://docs.alisx.com/reference/cli/service.md) | Manage services |
| [setup](https://docs.alisx.com/reference/cli/setup.md) | Set up this machine for Alis Build |
| [skills](https://docs.alisx.com/reference/cli/skills.md) | Discover and load Alis Build skills |
| [specialist](https://docs.alisx.com/reference/cli/specialist.md) | Request specialist input and manage conversations |
| [upgrade](https://docs.alisx.com/reference/cli/upgrade.md) | Upgrade the Alis Build CLI to the latest version |
| [version](https://docs.alisx.com/reference/cli/version.md) | Print the CLI version |
| [whoami](https://docs.alisx.com/reference/cli/whoami.md) | Show the authenticated user |
| [workstation](https://docs.alisx.com/reference/cli/workstation.md) | Workstations: your machines, one address per port |

Related pages: [Exit codes](https://docs.alisx.com/reference/cli/exit-codes.md), [Output contract](https://docs.alisx.com/reference/cli/output-contract.md), [Agents, skills and the CLI](https://docs.alisx.com/explanation/agents-skills-cli.md).