@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 package is two programs behind one name.

hlix <command> is the command-line control plane. 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. Every call goes through @hlix/sdk, which owns transport, auth, retry and error mapping.

hlix on its own opens Hlix Code, the interactive terminal harness. It gives you a coding agent with every CLI command available as a slash command, and it chooses where that agent's files and shell live: your project's cloud Coding Workspace when the folder is bound to hlix, a Docker container when one is running, and this machine otherwise. --sandbox cloud|docker|local decides it yourself; --local is short for --sandbox local. The Docker sandbox runs node:22-bookworm (git, node, python3 — no bun); --docker-image <ref>, or hlix config set dockerImage <ref>, runs a different one. No official image carries all four: oven/bun's Debian variant ships bun alone, and its node is a symlink to bun rather than Node.js. For a project whose commands need bun, hlix config set dockerImage imbios/bun-node:22-debian is a community image that has git, node, bun and python3 together.

Hlix Code needs no model key of your own. hlix auth login is the whole setup: the workspace the credential names pays for the coder, and /model offers only the models that workspace serves. In a local or docker sandbox you may add endpoints of your own — see Your own model endpoints below.

Requires Node.js 22.19 or newer.

Install

npm install --global @hlix/cli
hlix --help          # the commands
hlix                 # open Hlix Code

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

npm install --global @hlix/[email protected]
npx @hlix/[email protected] 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 optional: an API key authenticates a user and names no workspace, so the key is used to list the workspaces its owner belongs to. With one, it is taken automatically; with several, a terminal offers a numbered list and a non-interactive run names the ids to pass. 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_SESSION_TOKEN=…     # a signed-in session instead of a key (what the desktop app hands its bundled hlix)
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:

1. an explicit flag — --workspace, --base-url
2. the HLIX_* environment
3. the nearest .hlix/config.json, walking up from the working directory
4. the stored credential
5. 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] [--project <id>] [--json]
hlix terminal [project-id] [--print] [--web] [--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.

Hlix Code

hlix                                   # open the shell in this folder
hlix --local                           # …with the agent running on this machine
hlix --yolo                            # …approving every tool, nothing asks
hlix -p "write a test for parseArgs"   # one turn, print the answer, exit
hlix -p "fix the build" --yolo          # …and let that turn change files
hlix -p "what does this repo do" --json # JSONL events instead of prose

Inside the shell:

| | | | --- | --- | | /help | every command this build knows | | /model | pick the model, from what your workspace serves | | /harness | pick which coder does the work | | /sandbox | pick where this session's files and commands run | | /rules | which rules files the agent loaded, and how big they are | | /standards | what this folder gave the agent, and which MCP servers connected | | /yolo | run without being asked for approval — toggles | | /log | what this session's libraries logged, which the screen never shows | | /new, /threads, /resume, /compact | start a conversation, list this project's, pick an earlier one, condense one into memory | | /<any hlix command> | /status, /tasks-list, /push — the CLI, inline, as its own panel | | /<your own> | every .md file in .claude/commands or .hlix/commands | | ⇧Tab | switch between build and plan | | Ctrl-O | expand the newest tool, command or subagent panel | | ESC | stop the turn that is running | | Ctrl-C twice | leave |

A tool that changes something asks first, as a block above the prompt: allow once, decline with a reason, or allow that family for the rest of the session. /yolo turns the asking off for as long as you leave it on, and the footer says yolo while it is — your "always allow" choices are untouched, so turning it off puts you back where you were. -p has nobody to ask, so it reads freely and declines writes; --yolo (older spelling: --allow-writes) lets a headless turn change things. hlix config set yolo true makes it the default for a folder, or --global for every project.

An edit shows the change as a diff, a command shows its output and its exit code, and long output is collapsed with a line saying how much is hidden — Ctrl-O opens it. Scrolling is your terminal's own: the wheel, PageUp, the scrollbar.

What the agent knows about your project

hlix rules shows the two instruction files Hlix Code loads, and hlix rules --edit opens one in $EDITOR:

• ~/.hlix/AGENTS.md — your rules, read in every project you open.
• this project's AGENTS.md, else CLAUDE.md, else GEMINI.md — one of them, the first that exists.

Yours go into the prompt first and the project's second, so the project wins a disagreement. Nothing else is duplicated: a repository that keeps CLAUDE.md as a copy of AGENTS.md pays for it once.

Everything other coding agents left in the folder comes too — hlix standards lists it. Skills load from .claude/skills, .agents/skills, .hlix/skills and .codex/skills, and a skill whose name: is a human title loads under its directory name rather than being refused. Subagents come from .claude/agents and .hlix/agents, alongside the three Hlix Code ships: explore (read-only), plan and execute.

MCP servers

A project's MCP servers start with the session and their tools join the agent's. They are read from .mcp.json, .hlix/mcp.json, and the Cursor, Windsurf, Gemini, VS Code and Codex registrations already in the folder — ${VAR} placeholders resolve from your environment, so no secret has to live in the file. A server that cannot start costs one line in /standards and nothing else.

Machine-wide registrations are listed and not started: an MCP server is a process, usually holding a credential, and it belongs to the project it was configured for. Copy one into .hlix/mcp.json to use it here.

Conversations are kept in ~/.hlix/code/, per project — what a session remembers is the project it was started in and nothing else, and the startup line names it (memory: project adde1bea… · 3 threads). A long conversation is condensed into memory rather than truncated; hlix config set memoryTokens <n> sizes that budget (default 200000). Anything the libraries log goes to ~/.hlix/code/hlix-code.log instead of onto the screen; /log reads it.

Your own model endpoints

A local or docker session can run an OpenAI-compatible endpoint of your own alongside the workspace's models. Hlix Code never asks you to paste a key: add the endpoint to ~/.hlix/config.json yourself, and name an environment variable rather than writing a secret into the file.

{
  "schemaVersion": 1,
  "providers": [
    { "name": "lab", "url": "http://localhost:1234/v1", "models": ["qwen3-coder"] },
    { "name": "acme", "url": "https://api.acme.test/v1", "models": ["acme-coder"],
      "apiKeyEnv": "ACME_API_KEY" }
  ]
}

A cloud session ignores them: it runs on the workspace's account, so it offers the workspace's models and nothing else.

--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.