CLI reference

This page documents what every hlix command has in common: the global options, how a command decides which workspace and API it is talking to, the shape of --json output, and the codes automation branches on. Each command group has its own page, linked below.

Run hlix <command> --help for the exact usage of the version you have installed.

Command groups

Group	Commands	Page
Cloud client & coding	hlix with no command	Hlix Code
Authentication	login, logout, auth login, auth status, auth logout	auth
Orientation	status, standards, rules	status
Local setup	init	init
Project creation	import	import
Reconciliation	push, pull, sync, mirror	push, pull & sync
Explicit resources	skill import, agent import, mcp import	resources
Projects	projects list, projects get, projects delete, projects watch, projects message	projects
Tasks	tasks list, tasks get, tasks review, tasks watch	tasks
New work	cycles create, tasks create	hlix cycles create --help, hlix tasks create --help
Coder choice	harness get, harness set, harness clear	Connect your agents
Project secrets	secrets list, secrets set, secrets delete, secrets import, secrets export	Secrets
Settings	config list, config get, config set	Hlix Code settings
Cloud Machine shell	terminal	terminal
Installation	uninstall	Install the CLI

Global options

Accepted by every command, whether or not the command’s own usage lists them.

• --json (boolean, default false): print a stable, versioned machine envelope instead of the human view. Streams emit JSONL.
• --cwd <dir> (string, default the process working directory): operate on another directory, including the project-binding lookup. A path that is not a directory exits invalid_usage before the command runs.
• --workspace <id> (string, default resolved — see below): the workspace to act in, overriding the folder’s binding. The selected Workspace must match the folder binding.
• --base-url <url> (string, default https://server.hlix.ai): the API to talk to, overriding the folder’s binding. hlix auth login additionally requires HTTPS before it will store a credential — plain HTTP is accepted there only for localhost, 127.0.0.1, and ::1.
• --help (boolean): show global help, or the matched command’s usage.
• --version (boolean): print the installed CLI version.

Pass API keys securely

Use hlix login --api-key with the hidden prompt or stdin, or set HLIX_API_KEY in CI. Supplying the key as a command-line argument exits 2; arguments can be retained in shell history and process listings.

Where a command points

Every command resolves its workspace and API through one chain, highest first:

1. an explicit flag            --workspace, --base-url
2. the HLIX_* environment      HLIX_WORKSPACE_ID, HLIX_BASE_URL
3. the nearest hlix.yml        walking up from the working directory
4. the stored credential       ~/.config/hlix/credentials.json
5. the built-in default        https://server.hlix.ai

The folder’s binding is the hlix: block in that file: workspace and project id. hlix.api is optional. When that key is absent, the folder uses https://server.hlix.ai, and that host outranks the stored credential. hlix init and hlix import write hlix.api only when the server is a different host. A file that already names the production server keeps that line. The binding outranks the machine-wide credential: a folder bound to workspace A is queried against workspace A even when the last login named workspace B. Commands read hlix.yml only. A folder that still has just .hlix/config.json is not bound; hlix init copies that binding into hlix.yml. Local coder configuration is covered in Hlix Code settings.

Use the folder’s Workspace

Flags and environment variables must agree with an existing folder binding. A mismatch exits workspace_mismatch and names both targets.

/Users/you/acme-invoices is bound to workspace org_2p9xk4, but --workspace
names org_7t1mz2. Drop the override, or point --cwd at a folder bound to it.

hlix auth login can select another Workspace while leaving the folder binding unchanged.

Commands that act on a bound project — push, pull, sync, status, projects get, tasks list, and the three resource imports — find that binding by walking up from the working directory. Running hlix push from packages/api pushes the project, not a fragment of it.

JSON contract

Success:

{
  "schemaVersion": 1,
  "command": "projects list",
  "data": []
}

Failure:

{
  "schemaVersion": 1,
  "command": "projects list",
  "error": {
    "code": "unauthenticated",
    "message": "…",
    "status": 401
  }
}

Use the versioned JSON envelope, command name, documented data and error.code in automation. For inspection commands, data contains the API response. Local project commands such as import, push, pull, and sync return their documented local result shapes.

Watch commands such as tasks watch --json and projects watch --json emit one envelope per line (JSONL). Read streaming output line by line.

For AI agents

Pass --json and read error.code for structured results.

A --json run cannot answer a prompt. Confirmation gates return approval_required; import instead returns invalid_usage with instructions to review --dry-run and repeat with --yes. tasks watch --json is JSONL, so read it line by line.

Error codes

Branch on error.code, never on error.message — the message is human-readable and not stable.

Code	Raised when
unauthenticated	No credential, or the key was rejected
forbidden	The key is valid but may not act here
not_found	No such resource in this workspace
conflict	The operation collided with another change
invalid_request	The request failed schema validation
bad_request	The request failed validation
rate_limited	Too many requests
not_implemented	The requested operation is unavailable
server_error	The API failed
unreachable	The API could not be contacted
missing_argument	A required positional argument was omitted
invalid_usage	Unknown flag, bad flag value, or too many arguments
unknown_command	No such command
workspace_mismatch	An explicit target contradicts the folder’s binding
workspace_required	Nothing in the resolution chain named a workspace
approval_required	A destructive step needs approval the caller cannot give
cancelled	An interactive prompt was declined
not_initialized	The folder is not bound to a project
invalid_project_file	hlix.yml or hlix.local.yml cannot be read. The message names the file and the key
scan_blocked	The import scan found a blocker
invalid_base_url	--base-url is not HTTPS, and is not a loopback host
missing_credential	No API key was entered, or a browser login was asked for with nobody at a terminal
login_denied	The browser login was denied
login_expired	The browser login code expired before it was approved
login_failed	The server would not start or finish a browser login
unknown	Unclassified

approval_required means the command needs confirmation in a non-interactive context. cancelled means an interactive confirmation was declined. Check the command’s reference for supported preview and confirmation flags.

Exit codes

Code	Meaning
0	success
1	operational failure or scan blocker
2	usage, parsing, or unknown-command failure
3	authentication or permission failure

A pull --dry-run or sync --dry-run that reports a conflict exits 1. An import dry run with a blocker also exits 1. push --dry-run reports conflicts with exit 0 and makes no changes.

Environment variables

Variable	Purpose
HLIX_API_KEY	API credential; overrides the saved file
HLIX_WORKSPACE_ID	workspace selection
HLIX_BASE_URL	API origin; defaults to https://server.hlix.ai
HLIX_CONFIG_HOME	hlix-specific credential directory root
XDG_CONFIG_HOME	standard config root when HLIX_CONFIG_HOME is absent

Deleting a project

hlix projects delete <id|name> names the selected project before deleting it. Names must match exactly and be unique. Non-interactive use, --json, and removing this folder’s bound project require --yes; interactive use asks for confirmation. Local files are kept.

If a command fails before it runs

• unknown_command — the words did not match a registered command. hlix --help lists them.
• invalid_usage — --cwd is not a directory: /path — --cwd is checked before dispatch, so this exits 2 even for a command that would otherwise always exit 0.
• missing_argument — a required positional was omitted. The message is the command’s usage line.
• error: API keys are never accepted as command-line arguments. — drop the key from the command line: run hlix login --api-key and use the hidden prompt, pipe the key in, or set HLIX_API_KEY.

Next steps

hlix auth

Sign in, check which credential is in use, and sign out.

hlix status

Where am I, and has anything moved since the last sync.

hlix import

Import arguments, flags, reports and approval.

Troubleshooting

Symptom-first recovery for the failures above.