Hull CLI

The Hull CLI (hull) runs Hull's agents in your terminal. It is the same agent runtime that powers Hull Desktop and the IDE extensions, so agents, skills, permissions and config behave the same way everywhere.

Use it to plan and make changes without leaving the terminal, review your work before you push, and run agents headlessly in scripts and CI.

InstallCopy Anchor Link

curl -fsSL https://withhull.com/cli/install | bash

Check that it worked:

hull --version

For other platforms and troubleshooting, see Install.

UpdateCopy Anchor Link

hull upgrade

hull upgrade detects how you installed the CLI and updates it the same way. Pass a version to install a specific release, for example hull upgrade 0.1.4.

Start a sessionCopy Anchor Link

Open a terminal in your project and run:

hull

This opens the interactive terminal UI (TUI). Type a task and press Enter. The first time you run it, use /connect to sign in to Hull Gateway or add your own provider keys.

Useful ways to start:

AgentsCopy Anchor Link

Press Tab to cycle between primary agents, or use /agents to pick one.

You can add your own agents and subagents. See Custom agents and Subagents.

Slash commandsCopy Anchor Link

Type / in the prompt to see every available command, including your own commands and skills. The most useful built-in ones:

SessionsCopy Anchor Link

Agents, models and toolsCopy Anchor Link

Account and systemCopy Anchor Link

Press Ctrl+P to open the command palette for everything else, such as display toggles.

Review changes locallyCopy Anchor Link

Run /review to have Hull review your work before you push. The review is read-only: Hull reports findings and doesn't edit files until you ask it to fix them. With no arguments it reviews your uncommitted changes. You can name what to review:

Add guidance after the target, for example /review branch focus on error handling. Add quick or deep to change how thorough the review is.

For reviews on pull requests in GitHub or GitLab, see Code review.

Run headlessly with hull runCopy Anchor Link

hull run sends one message, prints the result and exits. Use it in scripts, CI and other automation.

hull run "Add a unit test for the date parser"

By default, hull run can't ask you for approval. If the agent needs an action that your permissions set to ask, Hull rejects it and the run exits with an error. To let it work on its own, choose one of these:

Rules set to deny are never approved by either flag. A safer approach is to allow exactly what the job needs in the project's hull.json.

Other useful flags: --agent, -m/--model, -f/--file to attach files, --command to run a slash command, -c or -s to continue a session, and --attach <url> to send the run to a server started with hull serve. See the CLI reference for the full list.

Example: GitHub ActionsCopy Anchor Link

- name: Run Hull
  run: hull run --auto "Update the changelog for this release"

JSON outputCopy Anchor Link

Use --format json when another program reads the output:

hull run --format json "Check the repository"

Hull writes one JSON object per line to standard output. Diagnostics stay on standard error. Every event has the same envelope:

{"schemaVersion":1,"type":"text","timestamp":1785686400000,"sessionID":"ses_example","part":{"type":"text","text":"Done"}}

Event types are tool_use, step_start, step_finish, text, reasoning and error.

• Check schemaVersion before you process an event.
• Hull may add fields or event types without changing the version, so ignore anything you don't recognize.
• Removing or renaming a field, or changing its meaning or type, requires a new schema version.
• Events arrive in stream order. timestamp is informational, not a unique ID.

OrganizationsCopy Anchor Link

If you belong to a Hull organization, use /teams to choose which one your requests go through. Hull remembers your choice for later sessions, including hull run.

In CI and other non-interactive environments, set HULL_ORG_ID instead. It takes priority over the saved choice. hull run has no --org flag.

Remote controlCopy Anchor Link

Remote control lets you see and steer a local CLI session from Hull Cloud. You must be signed in to Hull.

• Turn it on for the current session with /remote.
• Turn it on for every session by adding "remote_control": true to your global hull.json.

ConfigurationCopy Anchor Link

The CLI reads the same config as every other Hull surface:

Hull also reads opencode.json and opencode.jsonc in the same places, and the legacy .hullcode/ directory. It does not read .opencode/ directories. Project settings override global ones. Run hull debug config to see the merged result and hull config check to find mistakes.

{
  "$schema": "https://app.withhull.com/config.json",
  "permission": {
    "bash": { "*": "ask", "git status *": "allow" }
  }
}

Common keys include model, provider, mcp, permission, instructions, agent, command, formatter and lsp. See Settings for the full list, Permissions for approval rules and MCP in the CLI for MCP servers.

Project trustCopy Anchor Link

Config in a repository can run code on your machine, for example through MCP servers, plugins or instructions. Hull doesn't load a project's hull.json, .hull/ directory, AGENTS.md or similar files until you trust the project. Hull asks the first time you open it. You can also decide from the terminal:

hull trust              # trust the current directory
hull trust --deny       # keep project config disabled
hull trust --remove     # forget the decision

Environment variables in configCopy Anchor Link

Use {env:NAME} to read an environment variable in a config value:

{
  "provider": {
    "openai": { "options": { "apiKey": "{env:OPENAI_API_KEY}" } }
  }
}

Notifications and soundsCopy Anchor Link

Attention alerts are off by default. Turn them on in hull console under Settings > CLI > Notifications, or in ~/.config/hull/tui.json (global) or .hull/tui.json (project):

{
  "attention": {
    "enabled": true,
    "notifications": true,
    "sound": true,
    "volume": 0.4
  }
}

• enabled turns all alerts on or off.
• notifications shows a desktop notification when the terminal isn't focused.
• sound plays a sound. volume is a number from 0 to 1.

To use your own sounds, add file paths under attention.sounds with the keys default, question, permission, error, done or subagent_done. Relative paths are resolved from the folder that holds tui.json.

TelemetryCopy Anchor Link

To turn off Hull's OpenTelemetry tracing, set:

{
  "experimental": { "openTelemetry": false }
}

Shift+Enter in Windows TerminalCopy Anchor Link

Windows Terminal doesn't send Shift+Enter to programs by default. To insert a newline with Shift+Enter, open Windows Terminal's settings.json and add this to the actions array:

{
  "command": { "action": "sendInput", "input": "\u001b[13;2u" },
  "id": "User.sendInput.ShiftEnterCustom"
}

Then add this to the keybindings array:

{ "keys": "shift+enter", "id": "User.sendInput.ShiftEnterCustom" }

Restart Windows Terminal to apply the change.

Next stepsCopy Anchor Link