@hlix/cli

@hlix/cli

hlix is the AI OS for agencies and companies — the control plane that runs your parallel coding agents, orchestrates them across projects and cycles, and delivers reviewed work end to end.

This is its command-line interface. It binds a folder to a hlix project, imports an existing codebase into one, and reads projects, tasks and verified review evidence from the terminal. It owns argument parsing and output formatting and nothing else — every call goes through @hlix/sdk, which owns transport, auth, retry and error mapping.

Requires Node.js 20 or newer.

Install

npm install --global @hlix/cli
hlix --help

For CI, and for anything else that must not change underneath you, pin the version instead of floating to latest:

npm install --global @hlix/cli@0.2.0
npx @hlix/cli@0.2.0 status --json

Authenticate

hlix auth login --workspace <workspace-id>

The command reads the API key from a hidden terminal prompt; it never accepts a credential as a command-line argument. --workspace is required. An API key authenticates a user; it names no workspace, so the caller states which one to act in. The key is verified against a real API call before it is written to disk, so a key that does not work is never stored.

For CI, skip the login step and set the environment directly:

HLIX_API_KEY=hlix_…      # secret environment variable; never pass it in argv
HLIX_BASE_URL=…          # defaults to the production API
HLIX_WORKSPACE_ID=…      # the workspace to act in

hlix auth status says which of those two sources supplied the credential in use and whether it still works — without printing the key. hlix auth logout removes the stored file (and only the stored file: a key in HLIX_API_KEY is reported and left to the shell that set it).

Where a command points

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

• an explicit flag — --workspace, --base-url
• the HLIX_* environment
• the nearest .hlix/config.json, walking up from the working directory
• the stored credential
• the built-in default

So a folder bound to workspace A is queried against workspace A even when the last login named workspace B — the bug this replaced was the opposite. When a flag or environment variable contradicts the folder's binding, the command exits workspace_mismatch naming both rather than picking one. --cwd <dir> moves the whole resolution to another directory, and hlix status prints the result with the source that decided each value.

Commands

hlix status [--json]
hlix init [folder] [--json]
hlix import [folder] [--dry-run] [--env-file <path>] [--history preserve] [--yes]
hlix push [--dry-run]  |  hlix pull [--force] [--yes] [--dry-run]  |  hlix sync [--dry-run]
hlix projects list [--json]
hlix projects get [project-id] [--json]
hlix tasks list [--project <id>] [--status <status>] [--json]
hlix tasks get <id> [--json]
hlix tasks review <id> [--json]
hlix tasks watch <id>          # follows the task's status stream over SSE

--dry-run on push, pull and sync prints the divergence and the verdict the real command would reach, and changes nothing. pull --force replaces local files, so it asks first; --yes is the documented script bypass.

hlix import . scans the selected root, builds a temporary Git bundle without mutating the source repository, uploads it resumably, restores it into the project's Coding Workspace, and records the initial immutable revision. Dotenv values never enter the bundle: choose one file with --env-file, review the key-only dry-run, and approve with --yes. Agent instructions, skills, and MCP configuration are quarantined for separate review instead of being executed during import.

--json is a contract

Human output may change at any time. --json may not. Every JSON response carries a schemaVersion, and the envelope is fixed:

{ "schemaVersion": 1, "command": "projects list", "data": … }

data is the API's response unmodified — the CLI does not reshape, trim or enrich it. Errors use the same envelope with an error object carrying a stable code, and the process exit code reflects the class of failure rather than always being 1.

What this CLI deliberately does not do

• No execution commands. Dispatching a run from a dropped connection can duplicate work, and the commands to do so are not part of this surface.
• No tasks logs --follow. There is no log stream on the API — only plain reads — so a --follow here would be a poll dressed up as a stream. Use hlix tasks watch for the real status stream instead.
• No retries on non-idempotent verbs. A retried POST is a duplicated request; the SDK refuses it and this CLI inherits that.

Skill guide for coding agents

skills/hlix/SKILL.md ships with the package and describes only commands that exist. It is tested against the command table in both directions, so a command documented but unregistered — or registered but undocumented — fails the build.

hlix --version prints the installed version; hlix --help prints the command list this build actually registers.