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¶

❯ alis [command] [subcommand] [arguments] [flags]

Run with no arguments, alis opens the TUI 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.
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.

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.

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