HLVM CLI Reference

hlvm                                # Current directory
hlvm -C ~/dev/my-project            # Interactive shell in one project
hlvm -C ~/dev/my-project ask "test" # One-shot agent in one project
hlvm --global                       # Explicit global assistant

hlvm [options]

hlvm ask "<query>"

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

# Run against another directory without changing the parent shell
hlvm -C ~/dev/my-project 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"

# Isolated hidden conversation (persistent memory still follows normal settings)
hlvm ask --stateless "hello"

# One run with no persistent memory reads or writes
hlvm ask --memory-free "answer without using saved memory"

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

{"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"}}

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

hlvm model [command]

hlvm model                                         # Show model help
hlvm model list                                    # List all models
hlvm model login codex                             # Sign in to a backend
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 ollama/llama3.2:latest           # Remove

hlvm serve

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"}]}'

hlvm mcp <command>

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

hlvm doctor
hlvm doctor --json
hlvm doctor memory
hlvm doctor memory --json

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

hlvm editor setup
hlvm editor status

hlvm lsp

hlvm agent <command>

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"
# `remove` prints the ID accepted by `restore`
hlvm agent remove coder
hlvm agent restore <removal-id>

hlvm pet <command>

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

auto                           # Automatic eligible-route selection (default)
ollama/qwen3:8b                # Optional existing Ollama route
openai/gpt-4o                  # OpenAI
codex/<exact-model>            # Native Codex App Server harness
claude-code/<exact-model>      # Direct Claude subscription provider
claude-code-agent/<exact-model> # Native Claude Code Agent SDK harness
grok-build/<exact-model>       # Native Grok Build ACP harness
opencode/<profile>/<model>     # Native OpenCode ACP harness
google/gemini-2.0-flash        # Google

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