Home / Docs / CLI Reference

Helixor Code CLI

The helixor command-line interface is the primary local control surface for Helixor Code. It installs and repairs the local companion, starts and stops desktop surfaces, registers source roots, configures agent MCP connections, builds code indexes, authenticates against your environment, and reports system health.

What The CLI Owns

The CLI manages local runtime setup and reconciliation. It does not replace your AI coding agent, and it does not make the portal the source of local execution state. Use the CLI for:

First-time setup with helixor init
Starting the companion and desktop surfaces with helixor up
Stopping local runtime with helixor down
Inspecting local and remote bindings with helixor status
Diagnosing integration health with helixor doctor
Repairing runtime, tray, desk, autostart, and agent registration drift with helixor repair
Updating the installed CLI with helixor update
Registering AI agents with helixor agent install and helixor agent repair
Building or refreshing indexes with helixor index
Quarantining broken or obsolete indexes with helixor index-reset

First-Time Setup

Install the package using pipx (recommended to isolate dependencies from your project virtual environments) and run initialization:

pipx install helixor
helixor init

When pipx is not available, standard pip works identically:

python -m pip install --upgrade helixor
helixor init

During initialization, the CLI will:

Collect an optional display name, email, portal login, and organization selection.
Record one or more local source roots to monitor.
Register the machine's local companion process.
Start the companion on http://127.0.0.1:18733.
Launch the macOS tray and Local Desk unless disabled.
Install a per-user startup service (launchd on macOS) unless disabled.
Detect and configure Codex, Claude Code, Cursor, Grok, Antigravity, and Qwen Code integrations.
Discover code repositories below source roots and configure lazy/eager indexing.

Useful initialization flags:

helixor init --source-root ~/code
helixor init --source-root ~/code --index-strategy eager
helixor init --skip-login
helixor init --no-tray
helixor init --no-desk
helixor init --no-autostart
helixor init --no-agent-repair
helixor init --no-index

Lazy Indexing Default

--index-strategy lazy is the default. Lazy setup records a workspace router and builds specific module indexes on-demand when an AI agent first queries that codebase, saving disk and CPU time.

Runtime Lifecycle

Start the local companion and background surfaces:

helixor up

By default, helixor up starts the companion, the tray, the Local Desk, and index file watching. Useful flags include:

helixor up --no-tray
helixor up --no-desk
helixor up --no-index-watch
helixor up --require-tray
helixor up --companion-port 18733
helixor up --index-root ~/.helixor/code_index

Stop the local runtime:

helixor down

Diagnostics & Health Checks

Inspect current process and slot bindings with status:

helixor status
helixor status --json

Run active readiness probes across companion, ports, and agent registrations with doctor:

helixor doctor
helixor doctor --skip-agent-checks

Repair & Drift Reconciliation

If an agent configuration file is overwritten or an IDE update disconnects the companion, run repair:

helixor repair
helixor repair --source-root ~/code
helixor agent repair codex
helixor agent repair claude-code

Building & Refreshing Indexes

Index a single repository directly:

helixor index /path/to/repo
helixor index /path/to/repo --codebase-id billing-service
helixor index /path/to/repo --sparse
helixor index /path/to/repo --full
helixor index /path/to/repo --exclude 'dist/**' --exclude 'tmp/**'
helixor index /path/to/repo --dry-run

Quarantine corrupted or obsolete indexes, or prune individual codebases:

helixor index-reset --yes
helixor prune --codebase billing-service --yes

Previous ← Documentation Hub Next Code Indexing →