HLVM CLI Reference

Complete reference for the hlvm command-line interface.

Quick Reference

Command	Description
`hlvm`	Interactive shell
`hlvm ask`	AI agent task execution
`hlvm model`	Model management
`hlvm serve`	HTTP runtime host
`hlvm repair`	Repair HLVM-managed runtime assets
`hlvm bundle`	Install model-included runtime assets
`hlvm doctor`	Check HLVM runtime health
`hlvm browser`	Browser bridge management
`hlvm editor`	HQL editor integration
`hlvm mcp`	MCP server management
`hlvm agent`	Named agent management
`hlvm pet`	Pet avatar management
`hlvm update`	Check for updates and install the latest release

hlvm

Start the interactive shell.

hlvm [options]

Options:

Flag	Description
`--no-banner`	Skip the startup banner
`--port <N>`	Use a dedicated runtime port for dev/test isolation
`--help, -h`	Show help
`--version`	Show version

Input routing:

Input	Action
`(expression)`	HQL code evaluation
`(js "code")`	JavaScript evaluation
`/command`	Slash commands
Everything else	AI conversation

hlvm ask

Interactive AI agent for task execution. Runs the full agent orchestration loop with tool calling and planning.

hlvm ask "<query>"

Options:

Flag	Description
`--print`	Non-interactive output (uses configured mode, otherwise `acceptEdits`)
`--verbose`	Show agent header, tool labels, stats, and trace output
`--output-format <fmt>`	Output format: `text` (default), `json`, `stream-json`
`--usage`	Show token usage summary after execution
`--attach <path>`	Attach a file input (repeatable)
`--model <provider/model>`	Use a specific AI model
`--agent <name>`	Use a named agent
`--port <N>`	Use a dedicated runtime port for dev/test isolation
`--stateless`	Use an isolated hidden conversation for this run only
`--permission-mode <mode>`	Set permission mode (see below)
`--allowed-tools <name>`	Allow specific tool (repeatable)
`--disallowed-tools <name>`	Deny specific tool (repeatable)
`--max-turns <N>`	Maximum agent loop iterations (headless safety cap)
`--help, -h`	Show help

Examples:

# Interactive (default)
hlvm ask "list files in src/"

# Non-interactive print mode
hlvm ask --print "analyze code quality"

# Permission modes
hlvm ask --permission-mode acceptEdits "fix the bug"
hlvm ask --permission-mode readOnly "analyze code"

# Use a named agent
hlvm ask --agent reviewer "review this PR"

# Unlock shell execution explicitly (required in non-interactive mode)
hlvm ask --allowed-tools shell_exec --allowed-tools write_file \
  --permission-mode readOnly \
  "write a python script to generate a chart and run it"

# Block a specific tool
hlvm ask --disallowed-tools shell_exec "analyze code"

# Generate a file from multiple sources
hlvm ask --allowed-tools shell_exec --allowed-tools write_file \
  --allowed-tools read_file --permission-mode readOnly \
  "read all PDFs in ./reports/, summarize them, and write summary.md"

# Generate a PPTX presentation
hlvm ask --allowed-tools shell_exec --allowed-tools write_file \
  --permission-mode readOnly \
  "create a 5-slide dark-themed presentation about MCP, save to ~/Desktop/mcp.pptx, then open it"

# Mutate an existing PPTX in place and reload PowerPoint
hlvm ask --allowed-tools shell_exec --allowed-tools read_file \
  --permission-mode readOnly \
  "open ~/Desktop/mcp.pptx with python-pptx, change slide 1 title to 'New Title', save it, then run: osascript -e 'tell application \"Microsoft PowerPoint\" to quit saving no' && sleep 2 && open ~/Desktop/mcp.pptx"

# Structured output for scripting
hlvm ask --output-format stream-json "count test files"   # NDJSON events
hlvm ask --output-format json "count test files"           # Single JSON result

# Model selection
hlvm ask --model openai/gpt-4o "summarize this codebase"
hlvm ask --model claude-code/claude-sonnet-4-6 "review this PR"

# Attach files (images, PDFs, docs)
hlvm ask --attach ./screenshot.png "describe this UI issue"
hlvm ask --attach ./report.pdf --attach ./data.csv \
  "summarize the report and cross-reference with the data"

# Stateless run (no memory of previous conversations)
hlvm ask --stateless "hello"

# Cap agent loop iterations (useful for automation)
hlvm ask --max-turns 5 "refactor this file"

Output Formats

Format	Description
`text`	Human-readable streaming text (default)
`json`	Single JSON object with the final result
`stream-json`	Newline-delimited JSON events (NDJSON)

stream-json events:

{"type":"token","text":"Hello"}
{"type":"agent_event","event":{"type":"tool_start","name":"read_file"}}
{"type":"final","text":"Done","stats":{"turns":1},"meta":{"model":"ollama/test-fixture"}}

json output:

{"type":"result","result":"Done","stats":{"turns":1},"meta":{"model":"ollama/test-fixture"}}

Permission Modes

Mode	L0 (Read)	L1 (Write)	L2 (Destructive)
`default`	Auto-approve	Prompt	Prompt
`acceptEdits`	Auto-approve	Auto-approve	Prompt
`plan`	Auto-approve	Prompt after plan	Prompt after plan
`bypassPermissions`	Auto-approve	Auto-approve	Auto-approve
`readOnly`	Auto-approve	Auto-deny	Auto-deny

Tool safety levels:

L0: Safe read-only (read_file, list_files, search_code)
L1: Mutations (write_file, edit_file, shell_exec)
L2: High-risk (destructive shell commands, delete operations)

Priority order: deny > allow > mode > default

hlvm model

Manage AI models — list, pull, remove, and run them.

hlvm model [command]

Subcommands:

Command	Description
(none)	Show model help
`list`	List all available models (grouped by provider)
`key list`	List configured cloud provider keys
`key set <id>`	Save a provider API key in the credential store
`key unset <id>`	Remove a provider API key from the credential store
`set <name>`	Set default model (persisted to `~/.hlvm/settings.json`)
`show <name>`	Show model details (params, capabilities, size)
`pull <name>`	Download a model (Ollama only)
`remove <name>`	Remove a model (Ollama only)

Examples:

hlvm model                                         # Show model help
hlvm model list                                    # List all models
hlvm model key list                                # List provider keys
hlvm model set claude-code/claude-haiku-4-5-20251001  # Set default
hlvm model show llama3.1:8b                        # Model details
hlvm model pull ollama/llama3.2:latest             # Download
hlvm model remove llama3.2:latest                  # Remove

The set command persists to the same config SSOT used by the REPL model picker, hlvm ask, and the ai() API.

hlvm serve

Start the HTTP runtime host. Used by GUI clients and host-backed CLI surfaces.

hlvm serve

Starts on port 11435.

Endpoints:

Method	Path	Description
`POST`	`/api/chat`	Submit chat, eval, or agent turns
`GET`	`/api/chat/messages`	Read active conversation messages
`GET`	`/api/chat/stream`	Subscribe to active conversation updates
`GET`	`/health`	Health check

Examples:

hlvm serve

# Health check
curl http://localhost:11435/health

# Evaluate HQL
curl -X POST http://localhost:11435/api/chat \
  -H "Content-Type: application/json" \
  -d '{"mode":"eval","messages":[{"role":"user","content":"(+ 1 2)"}]}'

# Chat
curl -X POST http://localhost:11435/api/chat \
  -H "Content-Type: application/json" \
  -d '{"mode":"chat","messages":[{"role":"user","content":"hello"}]}'

GUI-visible top-level submission uses POST /api/chat. Internal compatibility endpoints may still exist, but they are not part of the public runtime-host contract.

hlvm mcp

Model Context Protocol server management.

hlvm mcp <command>

Subcommands:

Command	Description
`add <name> <url>`	Add a remote MCP server
`add <name> -- <command> [args...]`	Add a stdio MCP server
`show <name>`	Show details for one MCP server
`list`	List configured servers
`remove <name>`	Remove a server
`login <name>`	OAuth authentication for a remote MCP server
`logout <name>`	Remove stored OAuth token

Options:

Flag	Description
`--transport <type>`	`http` or `sse` for remote URLs; stdio uses `--`
`--env KEY=VALUE`	Environment variable (repeatable, for `add`)
`--header "Name: v"`	HTTP/SSE header (repeatable, for `add`)
`--client-id <id>`	OAuth client ID (for `add`)
`--client-secret`	OAuth client secret input toggle (for `add`)
`--callback-port <port>`	OAuth callback port (for `add`)

Examples:

hlvm mcp add github -- npx -y @modelcontextprotocol/server-github
hlvm mcp add db http://localhost:8080
hlvm mcp add sentry --env SENTRY_TOKEN=abc123 -- npx @sentry/mcp-server
hlvm mcp show github
hlvm mcp list
hlvm mcp remove github
hlvm mcp login notion
hlvm mcp logout notion

Notes:

Servers persist to ~/.hlvm/mcp.json. Inherited sources (Cursor, Windsurf, Zed, Codex CLI, Gemini CLI, Claude Code plugins) are read-only from HLVM.
URL inputs default to HTTP. Use --transport sse for SSE servers, or use the -- separator for stdio commands.
list and show report live MCP connection status.
hlvm mcp <subcommand> --help shows subcommand-specific help.

See the MCP guide for the full MCP surface, configuration model, and runtime behavior.

hlvm repair

Repair HLVM-managed runtime assets.

hlvm repair

hlvm bundle

Install a model-included local AI runtime bundle.

hlvm bundle install <runtime-dir>

The runtime directory must contain:

Path	Meaning
`hlvm-runtime-bundle.json`	Bundle manifest
`engine/`	Bundled runtime engine
`models/`	Bundled model files

After installation, HLVM reports whether the engine/model were copied or reused and sets the bundle-selected model as the default local model.

hlvm doctor

Check HLVM runtime health.

hlvm doctor
hlvm doctor --json

hlvm browser

Manage the native browser bridge.

hlvm browser setup
hlvm browser status
hlvm browser verify
hlvm browser uninstall

hlvm editor

Install and inspect HQL editor integration for supported VS Code-compatible editors.

hlvm editor setup
hlvm editor status

Subcommands:

Command	Description
`setup`	Build/install the HQL extension for detected Code/Cursor editors
`status`	Show detected editors, extension source status, and server reachability

After setup, opening a .hql file starts hlvm lsp from the installed editor extension. If the hlvm binary is not reachable from the editor extension, setup links it into the extension-visible path when possible or reports the manual hql.serverPath setting needed by the editor.

hlvm agent

Manage named agents — reusable AI personas, each with its own identity and memory. Run one with hlvm ask --agent <name>.

hlvm agent <command>

Subcommands:

Command	Description
`list`	List all addressable agents
`show <name>`	Show one agent's full file
`add <name>`	Scaffold a new agent file
`identity <name> [options]`	Update identity (emoji, color, image, avatar)
`remove <name>`	Remove the agent and its memory
`generate "<description>"`	AI-generate an agent from a text description

identity options:

Flag	Description
`--emoji <char>`	Set the agent's emoji
`--color <#HEX>`	Set the accent color
`--image-url <url\|path>`	Set an avatar image from a URL or local path
`--avatar <name>`	Use a named built-in avatar
`--description <text>`	Set the agent description
`--default`	Mark this agent as the default
`--no-default`	Unmark this agent as the default

Examples:

hlvm agent list
hlvm agent add coder
hlvm agent identity coder --emoji 🧑‍💻 --color "#4FC3F7"
hlvm agent generate "an agent that triages my email"
hlvm ask --agent coder "review this PR"

hlvm pet

Manage Codex-compatible pet avatars, resolved from ~/.hlvm/pets and ~/.codex/pets. Assign a pet to an agent to give it a visual avatar.

hlvm pet <command>

Subcommands:

Command	Description
`list`	List pets from `~/.hlvm/pets` and `~/.codex/pets`
`show <pet-id>`	Show one resolved pet
`validate <pet-id\|folder>`	Validate a Codex-compatible pet package
`import <pet-id\|folder>`	Copy a pet package into `~/.hlvm/pets`
`update <pet-id>`	Update HLVM-owned pet metadata
`remove <pet-id>`	Remove an HLVM-owned pet package
`assign <agent> <pet-id>`	Assign a pet avatar to an agent

Examples:

hlvm pet list
hlvm pet show sakiko
hlvm pet import ~/Downloads/my-pet --id my-pet
hlvm pet assign hlvm sakiko

hlvm update

Check for updates and install the latest release.

hlvm update [options]

Options:

Flag	Description
`--check`	Check for updates without installing
`--help, -h`	Show help

Model Identification

Models use <provider>/<model-name> format:

ollama/gemma4:12b              # Local Ollama (default)
ollama/llama3.1:8b             # Local Ollama
openai/gpt-4o                  # OpenAI
claude-code/claude-sonnet-4-6  # Claude (via the claude-code provider)
google/gemini-2.0-flash        # Google

Environment Variables

Supported user-facing environment variables:

Variable	Description
`HLVM_FORCE_SETUP`	Force first-run setup
`HLVM_NO_UPDATE_CHECK`	Disable the startup update check

HLVM's state lives at ~/.hlvm/ — this is fixed and not configurable. HLVM runs as a single user-level daemon, shared by the CLI, the macOS GUI, and any messaging-channel receivers; there is no per-directory isolation at the user contract.

Runtime port isolation:

hlvm --port 18442 ask "test against an isolated runtime"
hlvm ask --port 18442 "same isolation, command-local form"
hlvm --port 18442

The default 11435 port is the shared product runtime. Use --port only for source-mode work, E2E tests, or diagnostics where touching the GUI runtime would be wrong. HLVM does not silently auto-increment ports because that would split runtime state without making the isolation explicit.

Internal equivalent used by tests and spawned runtime hosts:

Variable	Description
`HLVM_REPL_PORT`	Environment form of `--port` for explicit dev/test isolation only

Configuration Files

File	Description
`~/.hlvm/settings.json`	Unified config: model, theme, permission mode, etc.
`~/.hlvm/`	Global config and cache directory
`hql.json`	HQL package metadata (name, version, exports)

Exit Codes

Code	Meaning
`0`	Success
`1`	General failure