CLI
CLI reference
Every Hull CLI command, subcommand and flag, taken from the CLI's own help output.
This page lists every hull command with its flags. The text in each block is the CLI's own help output, so it matches what hull <command> --help prints. Run hull help --all to see the same reference in your terminal.
Global options
These options work with every command:
| Option | Description |
|---|---|
-h, --help | Show help |
-v, --version | Show the version number |
--print-logs | Print logs to stderr |
--log-level | Log level: DEBUG, INFO, WARN or ERROR |
--pure | Run without external plugins |
hull [project]
Running hull with no command starts the interactive terminal UI (TUI) in the current directory, or in project if you pass a path.
start Hull Code TUI
Positionals:
project path to start Hull Code in [string]
Options:
--port port to listen on [number] [default: 0]
--hostname hostname to listen on [string] [default: "127.0.0.1"]
--mdns enable mDNS service discovery (defaults hostname to 0.0.0.0)
[boolean] [default: false]
--mdns-domain custom domain name for mDNS service (default: hull.local)
[string] [default: "hull.local"]
--cors additional domains to allow for CORS [array] [default: []]
-m, --model model to use in the format of provider/model [string]
-c, --continue continue the last session [boolean]
-s, --session session id to continue [string]
--fork fork the session when continuing (use with --continue or --session) [boolean]
--worktree create or reuse a git worktree with this name and start Hull Code there[string]
--prompt prompt to use [string]
--agent agent to use [string]hull acp
start ACP (Agent Client Protocol) server
Options:
--port port to listen on [number] [default: 0]
--hostname hostname to listen on [string] [default: "127.0.0.1"]
--mdns enable mDNS service discovery (defaults hostname to 0.0.0.0)
[boolean] [default: false]
--mdns-domain custom domain name for mDNS service (default: hull.local)
[string] [default: "hull.local"]
--cors additional domains to allow for CORS [array] [default: []]
--cwd working directory
[string] [default: current directory]hull mcp
manage MCP (Model Context Protocol) servers
Commands:
hull mcp add add an MCP server
hull mcp list list MCP servers and their status [aliases: ls]
hull mcp auth [name] authenticate with an OAuth-enabled MCP server
hull mcp logout [name] remove OAuth credentials for an MCP server
hull mcp debug <name> debug OAuth connection for an MCP serverhull mcp add
add an MCP serverhull mcp auth
authenticate with an OAuth-enabled MCP server
Commands:
hull mcp auth list list OAuth-capable MCP servers and their auth status [aliases: ls]
Positionals:
name name of the MCP server [string]hull mcp auth list
list OAuth-capable MCP servers and their auth status
Positionals:
name name of the MCP server [string]hull mcp debug
debug OAuth connection for an MCP server
Positionals:
name name of the MCP server [string] [required]hull mcp list
list MCP servers and their statushull mcp logout
remove OAuth credentials for an MCP server
Positionals:
name name of the MCP server [string]hull attach
attach to a running Hull Code server
Positionals:
url http://localhost:4096 [string] [required]
Options:
--dir directory to run in [string]
-c, --continue continue the last session [boolean]
-s, --session session id to continue [string]
--fork fork the session when continuing (use with --continue or --session) [boolean]
-p, --password basic auth password (defaults to HULL_SERVER_PASSWORD) [string]
-u, --username basic auth username (defaults to HULL_SERVER_USERNAME or 'hull') [string]hull run
run Hull Code with a message
Positionals:
message message to send [array] [default: []]
Options:
--command the command to run, use message for args [string]
-c, --continue continue the last session [boolean]
-s, --session session id to continue [string]
--fork fork the session before continuing (requires --continue or
--session) [boolean]
-m, --model model to use in the format of provider/model [string]
--agent agent to use [string]
--format format: default (formatted) or json (versioned NDJSON events)
[string] [choices: "default", "json"] [default: "default"]
-f, --file file(s) to attach to message [array]
--title title for the session (uses truncated prompt if no value
provided) [string]
--attach attach to a running Hull Code server (e.g.,
http://localhost:4096) [string]
-p, --password basic auth password (defaults to HULL_SERVER_PASSWORD)[string]
-u, --username basic auth username (defaults to HULL_SERVER_USERNAME or
'hull') [string]
--dir directory to run in, path on remote server if attaching
[string]
--port port for the local server (defaults to random port if no value
provided) [number]
--variant model variant (provider-specific reasoning effort, e.g., high,
max, minimal) [string]
--thinking show thinking blocks [boolean]
--replay replay interactive session history on resume and after resize
(use --no-replay to disable) [boolean] [default: true]
--replay-limit cap visible interactive replay to the newest N messages
[number]
-i, --interactive run in direct interactive split-footer mode
[boolean] [default: false]
--dangerously-skip-permissions auto-approve permissions that are not explicitly denied
(dangerous!) [boolean] [default: false]
--auto auto-approve all permissions (for autonomous/pipeline usage)
[boolean] [default: false]
--demo enable direct interactive demo slash commands; pass one as the
message to run it immediately [boolean] [default: false]hull debug
debugging and troubleshooting tools
Commands:
hull debug config show resolved configuration
hull debug lsp LSP debugging utilities
hull debug rg ripgrep debugging utilities
hull debug file file system debugging utilities
hull debug scrap list all known projects
hull debug skill list all available skills
hull debug snapshot snapshot debugging utilities
hull debug startup print startup timing
hull debug agent <name> show agent configuration details
hull debug v2 debug v2 catalog and built-in plugins
hull debug info show debug information
hull debug paths show global paths (data, config, cache, state)
hull debug wait wait indefinitely (for debugging)hull debug agent
show agent configuration details
Positionals:
name Agent name [string] [required]
Options:
--tool Tool id to execute [string]
--params Tool params as JSON or a JS object literal [string]hull debug config
show resolved configurationhull debug file
file system debugging utilities
Commands:
hull debug file read <path> read file contents as JSON
hull debug file list <path> list files in a directory
hull debug file search <query> search files by query
hull debug file tree [dir] show directory treehull debug file list
list files in a directory
Positionals:
path File path to list [string] [required]hull debug file read
read file contents as JSON
Positionals:
path File path to read [string] [required]hull debug file search
search files by query
Positionals:
query Search query [string] [required]hull debug file tree
show directory tree
Positionals:
dir Directory to tree
[string] [default: current directory]hull debug info
show debug informationhull debug lsp
LSP debugging utilities
Commands:
hull debug lsp diagnostics <file> get diagnostics for a file
hull debug lsp symbols <query> search workspace symbols
hull debug lsp document-symbols <uri> get symbols from a documenthull debug lsp diagnostics
get diagnostics for a file
Positionals:
file [string] [required]hull debug lsp document-symbols
get symbols from a document
Positionals:
uri [string] [required]hull debug lsp symbols
search workspace symbols
Positionals:
query [string] [required]hull debug paths
show global paths (data, config, cache, state)hull debug rg
ripgrep debugging utilities
Commands:
hull debug rg tree show file tree using ripgrep
hull debug rg files list files using ripgrep
hull debug rg search <pattern> search file contents using ripgrephull debug rg files
list files using ripgrep
Options:
--query Filter files by query [string]
--glob Glob pattern to match files [string]
--limit Limit number of results [number]hull debug rg search
search file contents using ripgrep
Positionals:
pattern Search pattern [string] [required]
Options:
--glob File glob patterns [array]
--limit Limit number of results [number]hull debug rg tree
show file tree using ripgrep
Options:
--limit [number]hull debug scrap
list all known projectshull debug skill
list all available skillshull debug snapshot
snapshot debugging utilities
Commands:
hull debug snapshot track track current snapshot state
hull debug snapshot patch <hash> show patch for a snapshot hash
hull debug snapshot diff <hash> show diff for a snapshot hashhull debug snapshot diff
show diff for a snapshot hash
Positionals:
hash hash [string] [required]hull debug snapshot patch
show patch for a snapshot hash
Positionals:
hash hash [string] [required]hull debug snapshot track
track current snapshot statehull debug startup
print startup timinghull debug v2
debug v2 catalog and built-in pluginshull debug wait
wait indefinitely (for debugging)hull auth
manage AI providers and credentials
Commands:
hull auth list list providers and credentials [aliases: ls]
hull auth login [url] log in to a provider
hull auth logout log out from a configured providerhull auth list
list providers and credentialshull auth login
log in to a provider
Positionals:
url hull auth provider [string]
Options:
-p, --provider provider id or name to log in to (skips provider selection) [string]
-m, --method login method label (skips method selection) [string]hull auth logout
log out from a configured providerhull agent
manage agents
Commands:
hull agent create create a new agent
hull agent list list all available agentshull agent create
create a new agent
Options:
--path directory path to generate the agent file [string]
--description what the agent should do [string]
--mode agent mode [string] [choices: "all", "primary", "subagent"]
--permissions, --tools comma-separated list of permissions to allow (default: all).
Available: "bash, read, edit, glob, grep, webfetch, task, todowrite,
websearch, lsp, skill" [string]
-m, --model model to use in the format of provider/model [string]hull agent list
list all available agentshull upgrade
upgrade Hull Code to the latest or a specific version
Positionals:
target version to upgrade to, for ex '0.1.48' or 'v0.1.48' [string]
Options:
-m, --method installation method to use
[string] [choices: "curl", "npm", "yarn", "pnpm", "bun", "brew", "choco", "scoop"]hull uninstall
uninstall Hull Code and remove all related files
Options:
-c, --keep-config keep configuration files [boolean] [default: false]
-d, --keep-data keep session data and snapshots [boolean] [default: false]
--dry-run show what would be removed without removing [boolean] [default: false]
-f, --force skip confirmation prompts [boolean] [default: false]hull serve
start a headless Hull Code server
Options:
--port port to listen on [number] [default: 0]
--hostname hostname to listen on [string] [default: "127.0.0.1"]
--mdns enable mDNS service discovery (defaults hostname to 0.0.0.0)
[boolean] [default: false]
--mdns-domain custom domain name for mDNS service (default: hull.local)
[string] [default: "hull.local"]
--cors additional domains to allow for CORS [array] [default: []]hull models
list all available models
Positionals:
provider provider ID to filter models by [string]
Options:
--verbose use more verbose model output (includes metadata like costs) [boolean]
--refresh refresh the models cache from models.dev [boolean]hull stats
show token usage and cost statistics
Options:
--days show stats for the last N days (default: all time) [number]
--tools number of tools to show (default: all) [number]
--models show model statistics (default: hidden). Pass a number to show top N, otherwise
shows all
--project filter by project (default: all projects, empty string: current project)[string]hull export
export session data as JSON
Positionals:
sessionID session id to export [string]
Options:
--sanitize redact sensitive transcript and file data [boolean]hull import
import session data from JSON file or URL
Positionals:
file path to JSON file or share URL [string] [required]hull github
manage GitHub agent
Commands:
hull github install install the GitHub agent
hull github run run the GitHub agenthull github install
install the GitHub agenthull github run
run the GitHub agent
Options:
--event GitHub mock event to run the agent for [string]
--token GitHub personal access token (github_pat_********) [string]hull pr
manage pull requests
Commands:
hull pr checkout <number> fetch and checkout a GitHub PR branch, then run Hull Code
hull pr link <url> link the current worktree to a pull request
hull pr unlink clear the linked pull request
hull pr status show the linked pull requesthull pr checkout
fetch and checkout a GitHub PR branch, then run Hull Code
Positionals:
number PR number to checkout [number] [required]hull pr link
link the current worktree to a pull request
Positionals:
url PR URL to link [string] [required]hull pr status
show the linked pull requesthull pr unlink
clear the linked pull requesthull session
manage sessions
Commands:
hull session list list sessions
hull session delete <sessionID> delete a sessionhull session delete
delete a session
Positionals:
sessionID session ID to delete [string] [required]hull session list
list sessions
Options:
-n, --max-count limit to N most recent sessions [number]
--format output format [string] [choices: "table", "json"] [default: "table"]
-a, --all list sessions from all projects [boolean] [default: false]
-s, --search filter sessions by title [string]hull plugin
install plugin and update config
Positionals:
module npm module name [string] [required]
Options:
-g, --global install in global config [boolean] [default: false]
-f, --force replace existing plugin version [boolean] [default: false]hull db
database tools
Commands:
hull db [query] open an interactive sqlite3 shell or run a query [default]
hull db path print the database path
Positionals:
query SQL query to execute [string]
Options:
--format Output format [string] [choices: "json", "tsv"] [default: "tsv"]hull db path
print the database pathhull console
open or stop the local Hull Code Console
Commands:
hull console open the local Hull Code Console [default]
hull console stop stop the local Hull Code daemon
Options:
--port port to listen on [number] [default: 0]
--hostname hostname to listen on [string] [default: "127.0.0.1"]
--mdns enable mDNS service discovery (defaults hostname to 0.0.0.0)
[boolean] [default: false]
--mdns-domain custom domain name for mDNS service (default: hull.local)
[string] [default: "hull.local"]
--cors additional domains to allow for CORS [array] [default: []]
-f, --foreground keep the command active until interrupted [boolean]hull console stop
stop the local Hull Code daemon
Options:
--json print daemon details as JSON [boolean]hull roll-call
batch-test text models matching a filter for connectivity and latency
Positionals:
filter regex to filter models by provider/modelID (required) [string] [required]
Options:
--prompt Prompt to send to each model [string] [default: "Hello"]
--timeout Timeout for each model call in milliseconds [number] [default: 25000]
--parallel Number of parallel model calls [number] [default: 5]
--verbose Show verbose output [boolean] [default: false]
--quiet Suppress progress and decoration [boolean] [default: false]
--output Output format (table, json, or md)
[string] [choices: "table", "json", "md"] [default: "table"]hull daemon
manage the local Hull Code daemon
Commands:
hull daemon start the local Hull Code daemon [default]
hull daemon start start the local Hull Code daemon
hull daemon status show local Hull Code daemon status
hull daemon stop stop the local Hull Code daemon
hull daemon restart restart the local Hull Code daemon
Options:
--port port to listen on [number] [default: 0]
--hostname hostname to listen on [string] [default: "127.0.0.1"]
--mdns enable mDNS service discovery (defaults hostname to 0.0.0.0)
[boolean] [default: false]
--mdns-domain custom domain name for mDNS service (default: hull.local)
[string] [default: "hull.local"]
--cors additional domains to allow for CORS [array] [default: []]
--json print daemon details as JSON [boolean]
-f, --foreground keep the command active until interrupted [boolean]hull daemon restart
restart the local Hull Code daemon
Options:
--port port to listen on [number] [default: 0]
--hostname hostname to listen on [string] [default: "127.0.0.1"]
--mdns enable mDNS service discovery (defaults hostname to 0.0.0.0)
[boolean] [default: false]
--mdns-domain custom domain name for mDNS service (default: hull.local)
[string] [default: "hull.local"]
--cors additional domains to allow for CORS [array] [default: []]
--json print daemon details as JSON [boolean]
-f, --foreground keep the command active until interrupted [boolean]hull daemon start
start the local Hull Code daemon
Options:
--port port to listen on [number] [default: 0]
--hostname hostname to listen on [string] [default: "127.0.0.1"]
--mdns enable mDNS service discovery (defaults hostname to 0.0.0.0)
[boolean] [default: false]
--mdns-domain custom domain name for mDNS service (default: hull.local)
[string] [default: "hull.local"]
--cors additional domains to allow for CORS [array] [default: []]
--json print daemon details as JSON [boolean]
-f, --foreground keep the command active until interrupted [boolean]hull daemon status
show local Hull Code daemon status
Options:
--json print daemon details as JSON [boolean]hull daemon stop
stop the local Hull Code daemon
Options:
--json print daemon details as JSON [boolean]hull trust
manage project trust
Positionals:
path project directory
[string] [default: current directory]
Options:
--deny keep project-controlled executable configuration disabled [boolean]
--remove remove the exact decision and use the nearest parent decision [boolean]hull config
configuration tools
Commands:
hull config check check configuration for warnings and errorshull config check
check configuration for warnings and errorshull worktree
manage git worktrees
Commands:
hull worktree create <name> create or reuse a git worktree by name
hull worktree list list git worktrees for the current project
hull worktree remove <name> remove a git worktree by name, deleting its branch toohull worktree create
create or reuse a git worktree by name
Positionals:
name [string] [required]hull worktree list
list git worktrees for the current projecthull worktree remove
remove a git worktree by name, deleting its branch too
Positionals:
name [string] [required]hull help
Show the full CLI reference, or help for one command.
hull help --all
hull help runhull completion
Generate a shell completion script. Add the output to your shell profile to get tab completion for hull commands.
hull completion >> ~/.zshrc