mirror of
https://github.com/hanzoai/dev.git
synced 2026-10-25 03:32:32 +00:00
zeekay
eb49cac620
457 sites carried an upstream prefix into every surface a user reaches — shell exports, docs, CI, the SDK. CODEX_ is not our name and it was never going to stop arriving on its own: it is what upstream writes, and every sync brings more. Two namespaces, because they answer different questions. DEV_* the app's own configuration — DEV_HOME, DEV_PROFILE, the rest HANZO_API_KEY a credential for the Hanzo stack, which is not app config CODEX_API_KEY held the literal string "CODEX_API_KEY", so the rename moves the value and not just the constant. It becomes HANZO_API_KEY, which is what create_hanzo_provider already reads through HANZO_MACHINE_ENV_KEYS — one name for one credential instead of two spellings of it. vendor/ is untouched, which is the point of vendor/: upstream code keeps upstream names, and the boundary is a path rather than a habit.
113 lines
4.7 KiB
Markdown
113 lines
4.7 KiB
Markdown
# Non-interactive mode
|
||
|
||
Use Hanzo Dev in non-interactive mode to automate common workflows.
|
||
|
||
```shell
|
||
dev exec "count the total number of lines of code in this project"
|
||
```
|
||
|
||
In non-interactive mode, Dev does not ask for command or edit approvals. By default it runs in `read-only` mode, so it cannot edit files or run commands that require network access.
|
||
|
||
Use `dev exec --full-auto` to allow file edits. Use `dev exec --sandbox danger-full-access` to allow edits and networked commands.
|
||
|
||
### Default output mode
|
||
|
||
By default, Dev streams its activity to stderr and only writes the final message from the agent to stdout. This makes it easier to pipe `dev exec` into another tool without extra filtering.
|
||
|
||
To write the output of `dev exec` to a file, in addition to using a shell redirect like `>`, there is also a dedicated flag to specify an output file: `-o`/`--output-last-message`.
|
||
|
||
### JSON output mode
|
||
|
||
`dev exec` supports a `--json` mode that streams events to stdout as JSON Lines (JSONL) while the agent runs.
|
||
|
||
Supported event types:
|
||
|
||
- `thread.started` - when a thread is started or resumed.
|
||
- `turn.started` - when a turn starts. A turn encompasses all events between the user message and the assistant response.
|
||
- `turn.completed` - when a turn completes; includes token usage.
|
||
- `turn.failed` - when a turn fails; includes error details.
|
||
- `item.started`/`item.updated`/`item.completed` - when a thread item is added/updated/completed.
|
||
|
||
Supported item types:
|
||
|
||
- `assistant_message` - assistant message.
|
||
- `reasoning` - a summary of the assistant's thinking.
|
||
- `command_execution` - assistant executing a command.
|
||
- `file_change` - assistant making file changes.
|
||
- `mcp_tool_call` - assistant calling an MCP tool.
|
||
- `web_search` - assistant performing a web search.
|
||
|
||
Typically, an `assistant_message` is added at the end of the turn.
|
||
|
||
Sample output:
|
||
|
||
```jsonl
|
||
{"type":"thread.started","thread_id":"0199a213-81c0-7800-8aa1-bbab2a035a53"}
|
||
{"type":"turn.started"}
|
||
{"type":"item.completed","item":{"id":"item_0","item_type":"reasoning","text":"**Searching for README files**"}}
|
||
{"type":"item.started","item":{"id":"item_1","item_type":"command_execution","command":"bash -lc ls","aggregated_output":"","status":"in_progress"}}
|
||
{"type":"item.completed","item":{"id":"item_1","item_type":"command_execution","command":"bash -lc ls","aggregated_output":"AGENTS.md\nCHANGELOG.md\nREADME.md\ncode-rs\ndocs\nscripts\nsdk\n","exit_code":0,"status":"completed"}}
|
||
{"type":"item.completed","item":{"id":"item_2","item_type":"reasoning","text":"**Checking repository root for README**"}}
|
||
{"type":"item.completed","item":{"id":"item_3","item_type":"assistant_message","text":"Yep — there’s a `README.md` in the repository root."}}
|
||
{"type":"turn.completed","usage":{"input_tokens":24763,"cached_input_tokens":24448,"output_tokens":122}}
|
||
```
|
||
|
||
### Structured output
|
||
|
||
By default, the agent responds with natural language. Use `--output-schema` to provide a JSON Schema that defines the expected JSON output.
|
||
|
||
The JSON Schema must follow the [strict schema rules](https://platform.openai.com/docs/guides/structured-outputs).
|
||
|
||
Sample schema:
|
||
|
||
```json
|
||
{
|
||
"type": "object",
|
||
"properties": {
|
||
"project_name": { "type": "string" },
|
||
"programming_languages": { "type": "array", "items": { "type": "string" } }
|
||
},
|
||
"required": ["project_name", "programming_languages"],
|
||
"additionalProperties": false
|
||
}
|
||
```
|
||
|
||
```shell
|
||
dev exec "Extract details of the project" --output-schema ~/schema.json
|
||
...
|
||
|
||
{"project_name":"Hanzo Dev","programming_languages":["Rust","TypeScript","Shell"]}
|
||
```
|
||
|
||
Combine `--output-schema` with `-o` to only print the final JSON output. You can also pass a file path to `-o` to save the JSON output to a file.
|
||
|
||
### Git repository requirement
|
||
|
||
Dev requires a Git repository to avoid destructive changes. To disable this check, use `dev exec --skip-git-repo-check`.
|
||
|
||
### Resuming non-interactive sessions
|
||
|
||
Resume a previous non-interactive session with `dev exec resume <SESSION_ID>` or `dev exec resume --last`. This preserves conversation context so you can ask follow-up questions or give new tasks to the agent.
|
||
|
||
```shell
|
||
dev exec "Review the change, look for use-after-free issues"
|
||
dev exec resume --last "Fix use-after-free issues"
|
||
```
|
||
|
||
Only the conversation context is preserved; you must still provide flags to customize Dev behavior.
|
||
|
||
```shell
|
||
dev exec --model zen5-coder --json "Review the change, look for use-after-free issues"
|
||
dev exec --model enso --json resume --last "Fix use-after-free issues"
|
||
```
|
||
|
||
## Authentication
|
||
|
||
By default, `dev exec` uses the same authentication as the TUI. On the `openai` provider you can override the API key by setting the `HANZO_API_KEY` environment variable.
|
||
|
||
```shell
|
||
HANZO_API_KEY=your-api-key-here dev exec "Fix merge conflict"
|
||
```
|
||
|
||
NOTE: `HANZO_API_KEY` is only supported in `dev exec`.
|