# CLI Reference URL: https://docs.hanzo.ai/docs/dev/reference/cli > Complete command-line reference for the dev CLI tool. ## Synopsis ```bash dev [OPTIONS] [PROMPT] dev [OPTIONS] ``` Hanzo Dev is an AI-powered coding assistant that runs in your terminal. When invoked without a subcommand, it launches the interactive TUI. ## Global Options | Option | Short | Description | | -------------------------------------------- | ----- | --------------------------------------------------- | | `--model ` | `-m` | Model the agent should use | | `--profile ` | `-p` | Configuration profile from config.toml | | `--sandbox ` | `-s` | Sandbox policy for shell commands | | `--ask-for-approval ` | `-a` | When to require human approval | | `--cd ` | `-C` | Working directory for the agent | | `--image ` | `-i` | Attach image(s) to initial prompt (comma-separated) | | `--oss` | | Use local open source model provider (Ollama) | | `--full-auto` | | Enable low-friction sandboxed automatic execution | | `--dangerously-bypass-approvals-and-sandbox` | | Skip all safety checks (DANGEROUS) | | `--auto` | | Run Auto Drive for non-interactive sessions | | `--demo ` | | Developer message to prepend for demos | | `--debug` | `-d` | Enable debug logging of LLM requests | | `-c ` | | Override configuration values | | `--version` | | Print version information | | `--help` | `-h` | Print help information | ### Sandbox Modes - `off` — No sandboxing (commands run directly) - `workspace-read` — Read-only access to workspace - `workspace-write` — Read/write access to workspace (default for full-auto) - `network-off` — Disable network access ### Approval Policies - `always` — Always ask before executing commands - `on-failure` — Ask only when a command fails (default for full-auto) - `on-request` — Ask when the model explicitly requests approval - `never` — Never ask for approval --- ## Subcommands ### Interactive Mode (default) ```bash dev [OPTIONS] [PROMPT] ``` Launch the interactive TUI. If PROMPT is provided, it starts the conversation. **TUI-Specific Options:** | Option | Description | | ------------------------------ | ------------------------------------ | | `--search` | Enable web search (default: enabled) | | `--no-search` | Disable web search | | `--compact-prompt ` | Override compaction prompt text | | `--compact-prompt-file ` | Read compaction prompt from file | | `--order` | Show ordering debug overlays | | `--timing` | Enable timing diagnostics | **Examples:** ```bash dev dev "Help me refactor this function" dev -m gpt-4.1 "Explain this code" dev -i screenshot.png "What's in this image?" ``` --- ### exec Run non-interactively for a single task. \*_Alias:_\* `e` ```bash dev exec [OPTIONS] [PROMPT] ``` | Option | Description | | ------------------------------ | --------------------------------------- | | `--auto` | Run Auto Drive instead of single turn | | `--auto-review` | Use Auto Review models and limits | | `--json` | Print events to stdout as JSONL | | `--color ` | Color output: `always`, `never`, `auto` | | `--max-seconds ` | Maximum wall-clock time budget | | `--turn-cap ` | Maximum Auto Drive coordinator turns | | `--include-plan-tool` | Include planning tool in conversation | | `--output-last-message ` | Write final message to file | | `--output-schema ` | JSON Schema for structured output | | `--review-output-json ` | Write review output JSON | | `--skip-git-repo-check` | Allow running outside Git repos | **Examples:** ```bash dev exec "Add error handling to main.py" dev exec --auto --max-seconds 300 "Implement the TODO items" dev exec --full-auto "Fix all linting errors" dev exec --json "List all functions in src/" ``` --- ### auto Run Auto Drive headless. Alias for `exec --auto --full-auto`. ```bash dev auto [OPTIONS] [PROMPT] ``` ```bash dev auto "Refactor the database module" dev auto --turn-cap 10 "Complete the migration" ``` --- ### resume Resume a previous interactive session. ```bash dev resume [SESSION_ID] [OPTIONS] ``` | Option | Description | | -------- | -------------------------------- | | `--last` | Continue the most recent session | ```bash dev resume dev resume --last dev resume abc123-def456-... dev resume --last -m gpt-4.1 ``` --- ### login / logout Manage authentication credentials. ```bash dev login [--with-api-key] dev login status dev logout ``` ```bash dev login # Interactive (opens browser) printenv OPENAI_API_KEY | dev login --with-api-key # API key from stdin dev login status # Check status ``` --- ### apply Apply the latest diff produced by the agent. \*_Alias:_\* `a` ```bash dev apply ``` --- ### mcp Manage MCP (Model Context Protocol) servers. \*_Alias:_\* `acp` #### mcp list ```bash dev mcp list [--json] ``` #### mcp get ```bash dev mcp get [--json] ``` #### mcp add ```bash dev mcp add [OPTIONS] [-- COMMAND...] ``` | Option | Description | | ------------------------ | ---------------------------------- | | `--url ` | URL of remote MCP server | | `--bearer-token ` | Bearer token for authentication | | `--env ` | Environment variables (repeatable) | ```bash dev mcp add my-tool -- /path/to/mcp-server dev mcp add remote-tool --url https://mcp.example.com/api dev mcp add api-tool --url https://api.example.com --bearer-token $TOKEN dev mcp add secure-tool --env API_KEY=secret -- my-mcp-server ``` #### mcp remove ```bash dev mcp remove ``` --- ### bridge Manage browser integration. #### bridge subscription ```bash dev bridge subscription [OPTIONS] ``` | Option | Description | | ---------------------- | ----------------------------------------------------------- | | `--show` | Display current subscription | | `--levels ` | Set log levels: errors,warn,info,trace | | `--capabilities ` | Set capabilities: screenshot,pageview,control,console,error | | `--filter ` | LLM filter: off, minimal, aggressive | | `--clear` | Remove override and revert to defaults | #### bridge list ```bash dev bridge list ``` #### bridge tail ```bash dev bridge tail [OPTIONS] ``` | Option | Description | | -------------------------- | ---------------------------------------- | | `--level ` | Minimum level: errors, warn, info, trace | | `--bridge ` | Select specific bridge target | | `--raw` | Print raw JSON frames | #### bridge screenshot ```bash dev bridge screenshot [--timeout ] [--bridge ] ``` #### bridge javascript Execute JavaScript via the bridge control channel. \*_Alias:_\* `js` ```bash dev bridge javascript [--timeout ] [--bridge ] ``` --- ### cloud Browse and manage Cloud tasks. \*_Alias:_\* `cloud-tasks` #### cloud submit ```bash dev cloud submit [OPTIONS] ``` | Option | Description | | ----------------- | ------------------------------- | | `--env ` | Environment ID | | `--best-of ` | Best-of-N attempts (default: 1) | | `--qa` | Enable QA/review mode | | `--git-ref ` | Git ref (default: main) | | `--wait` | Wait for completion | --- ### llm Side-channel LLM utilities (no TUI events). #### llm request ```bash dev llm request [OPTIONS] ``` | Option | Description | | ---------------------- | ------------------------------------------ | | `--developer ` | Developer message | | `--message ` | User message | | `--model ` | Model override | | `--format-type ` | Output format type (default: json\_schema) | | `--format-name ` | Output format name | | `--format-strict` | Enable strict format (default: true) | | `--schema-json ` | Inline JSON schema | | `--schema-file ` | Path to JSON schema file | --- ### completion Generate shell completion scripts. ```bash dev completion bash > ~/.local/share/bash-completion/completions/dev dev completion zsh > ~/.zfunc/_dev dev completion fish > ~/.config/fish/completions/dev.fish ``` Shells: `bash`, `zsh`, `fish`, `powershell`, `elvish` --- ### doctor Diagnose PATH, binary collisions, and version conflicts. ```bash dev doctor ``` Output includes: current executable path and version, PATH, all `dev` and `coder` binaries found, version information, and package manager conflict detection. --- ### preview Download and run a preview build by slug. ```bash dev preview [OPTIONS] [-- EXTRA_ARGS...] ``` | Option | Description | | --------------------- | ------------------- | | `--repo ` | Override repository | | `--out ` | Output directory | --- ### debug Internal debugging commands. - `dev debug seatbelt [COMMAND...]` — Run under Seatbelt (macOS only) - `dev debug landlock [COMMAND...]` — Run under Landlock+seccomp (Linux only) --- ## Configuration Configuration is loaded from `~/.code/config.toml` (or the legacy `~/.codex/config.toml`). Use `-c key=value` to override: ```bash dev -c model=gpt-4.1 dev -c model=gpt-4.1 -c model_provider=openai dev exec -c model=gpt-4.1 "Your prompt" ``` --- ## Environment Variables | Variable | Description | | ------------------- | ----------------------------------------------- | | `OPENAI_API_KEY` | OpenAI API key | | `HANZO_API_KEY` | Hanzo API key | | `CODE_HOME` | Override config directory (default: `~/.hanzo`) | | `CODEX_HOME` | Legacy config directory (fallback) | | `CODEX_SECURE_MODE` | Enable security hardening when set to `"1"` | --- ## Common Workflows ### Quick Task Execution ```bash dev exec --full-auto "Fix the null pointer exception in user.py" dev exec --auto-review "Review the changes in this PR" ``` ### Interactive Development ```bash dev -C /path/to/project "Let's implement the new feature" dev resume --last dev -m gpt-4.1 "Architect the new microservice" ``` ### CI/CD Integration ```bash dev exec --json --max-seconds 120 "Review this diff" | jq . dev exec --output-last-message docs.md "Document the API" ``` ### MCP Server Setup ```bash dev mcp add my-search -- /path/to/search-mcp dev mcp list --json dev mcp remove my-search ``` --- ## Exit Codes | Code | Description | | ---- | -------------------- | | 0 | Success | | 1 | General error | | 130 | Interrupted (SIGINT) |