CLI

hordecode CLI options and commands.

The hordecode CLI by default starts the TUI when run without any arguments.

horde

But it also accepts commands as documented on this page. This allows you to interact with hordecode programmatically.

horde run "Explain how closures work in JavaScript"

tui

Start the hordecode terminal user interface.

horde [project]

Flags

Flag	Short	Description
`--continue`	`-c`	Continue the last session
`--session`	`-s`	Session ID to continue
`--fork`		Fork the session when continuing (use with `--continue` or `--session`)
`--prompt`		Prompt to use
`--model`	`-m`	Model to use in the form of provider/model
`--agent`		Agent to use
`--auto`		Auto-approve permissions that are not explicitly denied
`--port`		Port to listen on
`--hostname`		Hostname to listen on
`--mdns`		Enable mDNS discovery
`--mdns-domain`		Custom mDNS domain name
`--cors`		Additional browser origin(s) to allow CORS

Commands

The hordecode CLI also has the following commands.

agent

Manage agents for hordecode.

horde agent [command]

create

Create a new agent with custom configuration.

horde agent create

This command will guide you through creating a new agent with a custom system prompt and permission configuration. Anything you don’t allow is denied in the generated agent’s frontmatter.

Flags

Flag	Short	Description
`--path`		Directory to write the agent file to (defaults to global `~/.config/hordecode/agents` or project `.hordecode/agents` based on the prompt)
`--description`		What the agent should do
`--mode`		Agent mode: `all`, `primary`, or `subagent`
`--permissions`		Comma-separated list of permissions to allow (default: all). Available: `bash`, `read`, `edit`, `glob`, `grep`, `webfetch`, `task`, `todowrite`, `websearch`, `lsp`, `skill`. Anything omitted is denied. Alias: `--tools`
`--model`	`-m`	Model to use, in `provider/model` format

Passing all of --path, --description, --mode, and --permissions runs the command non-interactively.

list

List all available agents.

horde agent list

attach

Attach a terminal to an already running hordecode backend server started via serve or web commands.

horde attach [url]

This allows using the TUI with a remote hordecode backend. For example:

# Start the backend server for web/mobile access
horde web --port 4096 --hostname 0.0.0.0

# In another terminal, attach the TUI to the running backend
horde attach http://10.20.30.40:4096

Flags

Flag	Short	Description
`--dir`		Working directory to start TUI in
`--continue`	`-c`	Continue the last session
`--session`	`-s`	Session ID to continue
`--fork`		Fork the session when continuing (use with `--continue` or `--session`)
`--password`	`-p`	Basic auth password (defaults to `HORDECODE_SERVER_PASSWORD`)
`--username`	`-u`	Basic auth username (defaults to `HORDECODE_SERVER_USERNAME` or `hordecode`)

auth

Command to manage credentials and login for providers.

horde auth [command]

hordecode is powered by the provider list at Models.dev, so you can use horde auth login to configure API keys for any provider you’d like to use. This is stored in ~/.local/share/hordecode/auth.json.

horde auth login

When hordecode starts up it loads the providers from the credentials file. And if there are any keys defined in your environments or a .env file in your project.

Flags

Flag	Short	Description
`--provider`	`-p`	Provider ID or name to log in to
`--method`	`-m`	Login method label to use, skipping method selection

list

Lists all the authenticated providers as stored in the credentials file.

horde auth list

Or the short version.

horde auth ls

logout

Logs you out of a provider by clearing it from the credentials file.

horde auth logout

mcp

Manage Model Context Protocol servers.

horde mcp [command]

add

Add an MCP server to your configuration.

horde mcp add

This command will guide you through adding either a local or remote MCP server.

list

List all configured MCP servers and their connection status.

horde mcp list

Or use the short version.

horde mcp ls

auth

Authenticate with an OAuth-enabled MCP server.

horde mcp auth [name]

If you don’t provide a server name, you’ll be prompted to select from available OAuth-capable servers.

You can also list OAuth-capable servers and their authentication status.

horde mcp auth list

Or use the short version.

horde mcp auth ls

logout

Remove OAuth credentials for an MCP server.

horde mcp logout [name]

remove

Remove an MCP server entry from the config file that holds it. Comments in that file are kept.

horde mcp remove <name>

Or use the short version.

horde mcp rm <name>

Stored OAuth credentials stay; horde mcp logout removes them.

debug

Debug OAuth connection issues for an MCP server.

horde mcp debug <name>

models

List all available models from configured providers.

horde models [provider]

This command displays all models available across your configured providers in the format provider/model.

This is useful for figuring out the exact model name to use in your config.

You can optionally pass a provider ID to filter models by that provider.

horde models anthropic

Flags

Flag	Description
`--refresh`	Refresh the models cache from models.dev
`--verbose`	Use more verbose model output (includes metadata like costs)

Use the --refresh flag to update the cached model list. This is useful when new models have been added to a provider and you want to see them in hordecode.

horde models --refresh

run

Run hordecode in non-interactive mode by passing a prompt directly.

horde run [message..]

This is useful for scripting, automation, or when you want a quick answer without launching the full TUI. For example.

horde run Explain the use of context in Go

You can also attach to a running horde serve instance to avoid MCP server cold boot times on every run:

# Start a headless server in one terminal
horde serve

# In another terminal, run commands that attach to it
horde run --attach http://localhost:4096 "Explain async/await in JavaScript"

Flags

Flag	Short	Description
`--command`		The command to run, use message for args
`--continue`	`-c`	Continue the last session
`--session`	`-s`	Session ID to continue
`--fork`		Fork the session when continuing (use with `--continue` or `--session`)
`--model`	`-m`	Model to use in the form of provider/model
`--agent`		Agent to use
`--file`	`-f`	File(s) to attach to message
`--format`		Format: default (formatted) or json (raw JSON events)
`--title`		Title for the session (uses truncated prompt if no value provided)
`--attach`		Attach to a running hordecode server (e.g., http://localhost:4096)
`--password`	`-p`	Basic auth password (defaults to `HORDECODE_SERVER_PASSWORD`)
`--username`	`-u`	Basic auth username (defaults to `HORDECODE_SERVER_USERNAME` or `hordecode`)
`--dir`		Directory to run in, or path on the remote server when attaching
`--port`		Port for the local server (defaults to random port)
`--variant`		Model variant (provider-specific reasoning effort)
`--thinking`		Show thinking blocks
`--auto`		Auto-approve permissions that are not explicitly denied

serve

Start a headless hordecode server for API access. Check out the server docs for the full HTTP interface.

horde serve

This starts an HTTP server that provides API access to hordecode functionality without the TUI interface. Set HORDECODE_SERVER_PASSWORD to enable HTTP basic auth (username defaults to hordecode).

Flags

Flag	Description
`--port`	Port to listen on
`--hostname`	Hostname to listen on
`--mdns`	Enable mDNS discovery
`--mdns-domain`	Custom mDNS domain name
`--cors`	Additional browser origin(s) to allow CORS

session

Manage hordecode sessions.

horde session [command]

list

List all hordecode sessions.

horde session list

Flags

Flag	Short	Description
`--max-count`	`-n`	Limit to N most recent sessions
`--format`		Output format: table or json (table)

delete

Delete an hordecode session.

horde session delete <sessionID>

stats

Show token usage and cost statistics for your hordecode sessions.

horde stats

Flags

Flag	Description
`--days`	Show stats for the last N days (all time)
`--tools`	Number of tools to show (all)
`--models`	Show model usage breakdown (hidden by default). Pass a number to show top N
`--project`	Filter by project (all projects, empty string: current project)

export

Export session data as JSON.

horde export [sessionID]

If you don’t provide a session ID, you’ll be prompted to select from available sessions.

Flags

Flag	Description
`--sanitize`	Redact sensitive transcript/file data

import

Import session data from a JSON file.

horde import <file>

You can import from a local file.

horde import session.json

web

Start a headless hordecode server with a web interface.

horde web

This starts an HTTP server and opens a web browser to access hordecode through a web interface. Set HORDECODE_SERVER_PASSWORD to enable HTTP basic auth (username defaults to hordecode).

Flags

Flag	Description
`--port`	Port to listen on
`--hostname`	Hostname to listen on
`--mdns`	Enable mDNS discovery
`--mdns-domain`	Custom mDNS domain name
`--cors`	Additional browser origin(s) to allow CORS

acp

Start an ACP (Agent Client Protocol) server.

horde acp

This command starts an ACP server that communicates via stdin/stdout using nd-JSON.

Flags

Flag	Description
`--cwd`	Working directory
`--port`	Port to listen on
`--hostname`	Hostname to listen on
`--mdns`	Enable mDNS discovery
`--mdns-domain`	Custom mDNS domain name
`--cors`	Additional browser origin(s) to allow CORS

plugin

Install a plugin and update your config.

horde plugin <module>

Or use the alias.

horde plug <module>

Flags

Flag	Short	Description
`--global`	`-g`	Install in global config
`--force`	`-f`	Replace existing plugin version

pr

Fetch and checkout a GitHub PR branch, then run hordecode.

horde pr <number>

db

Database tools.

horde db [query]

Flags

Flag	Description
`--format`	Output format: `json` or `tsv`

path

Print the database path.

horde db path

debug

Debugging and troubleshooting tools.

horde debug [command]

horde debug config lists unknown config keys on stderr.
horde debug audit-verify [file] checks the hash chain of the permission audit log and reports the first line that does not match.

uninstall

Uninstall hordecode and remove all related files.

horde uninstall

Flags

Flag	Short	Description
`--keep-config`	`-c`	Keep configuration files
`--keep-data`	`-d`	Keep session data and snapshots
`--dry-run`		Show what would be removed without removing
`--force`	`-f`	Skip confirmation prompts

upgrade

Updates hordecode to the latest version or a specific version. When a newer version is released, hordecode shows an update notice; the update installs when you confirm the notice or run this command.

horde upgrade [target]

To upgrade to the latest version.

horde upgrade

To upgrade to a specific version.

horde upgrade 0.1.3

Flags

Flag	Short	Description
`--method`	`-m`	The installation method that was used; curl, npm, pnpm, bun

Global Flags

The hordecode CLI takes the following global flags.

Flag	Short	Description
`--help`	`-h`	Display help
`--version`	`-v`	Print version number
`--print-logs`		Print logs to stderr
`--log-level`		Log level (DEBUG, INFO, WARN, ERROR)
`--pure`		Run without external plugins

Environment variables

hordecode can be configured using environment variables.

Variable	Type	Description
`HORDECODE_GIT_BASH_PATH`	string	Path to Git Bash executable on Windows
`HORDECODE_CONFIG`	string	Path to config file
`HORDECODE_TUI_CONFIG`	string	Path to TUI config file
`HORDECODE_CONFIG_DIR`	string	Path to config directory
`HORDECODE_CONFIG_CONTENT`	string	Inline json config content
`HORDECODE_DISABLE_AUTOUPDATE`	boolean	Disable update checks
`HORDECODE_DISABLE_PRUNE`	boolean	Disable pruning of old data
`HORDECODE_DISABLE_TERMINAL_TITLE`	boolean	Disable automatic terminal title updates
`HORDECODE_PERMISSION`	string	Inlined json permissions config
`HORDECODE_DISABLE_DEFAULT_PLUGINS`	boolean	Disable default plugins
`HORDECODE_DISABLE_LSP_DOWNLOAD`	boolean	Disable automatic LSP server downloads
`HORDECODE_ENABLE_EXPERIMENTAL_MODELS`	boolean	Enable experimental models
`HORDECODE_DISABLE_AUTOCOMPACT`	boolean	Disable automatic context compaction
`HORDECODE_DISABLE_CLAUDE_CODE`	boolean	Disable reading from `.claude` (prompt + skills)
`HORDECODE_DISABLE_CLAUDE_CODE_PROMPT`	boolean	Disable reading `~/.claude/CLAUDE.md`
`HORDECODE_DISABLE_CLAUDE_CODE_SKILLS`	boolean	Disable loading `.claude/skills`
`HORDECODE_DISABLE_MODELS_FETCH`	boolean	Disable fetching models from remote sources
`HORDECODE_DISABLE_MOUSE`	boolean	Disable mouse capture in the TUI
`HORDECODE_FAKE_VCS`	string	Fake VCS provider for testing purposes
`HORDECODE_CLIENT`	string	Client identifier (defaults to `cli`)
`HORDECODE_ENABLE_EXA`	boolean	Enable Exa web search tools
`HORDECODE_SERVER_PASSWORD`	string	Enable basic auth for `serve`/`web`
`HORDECODE_SERVER_USERNAME`	string	Override basic auth username (default `hordecode`)
`HORDECODE_MODELS_URL`	string	Custom URL for fetching models configuration

OpenTelemetry

hordecode sends traces, logs and metrics over OTLP/HTTP when an endpoint is set. Nothing is sent without one.

Variable	Use
`OTEL_EXPORTER_OTLP_ENDPOINT`	The common endpoint. `/v1/traces`, `/v1/logs` and `/v1/metrics` are appended.
`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`	The full URL for traces, used as given.
`OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`	The full URL for logs, used as given.
`OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`	The full URL for metrics, used as given.
`OTEL_EXPORTER_OTLP_HEADERS`	Comma-separated `key=value` pairs sent with each request.
`OTEL_RESOURCE_ATTRIBUTES`	Comma-separated `key=value` resource attributes.
`OTEL_SDK_DISABLED=true`	Turns every signal off.

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

What is exported:

Traces: one chat <model> span per model step, with the gen_ai.* token usage attributes, the reasoning and cache token counts, hordecode.cost.usd, hordecode.latency_ms, hordecode.ttft_ms and the finish reason. Supervisor spawn spans carry supervisor.mode, agent.type, context.mode, session.id, parent.session.id and supervisor.background.
Logs: the hordecode log records.
Metrics, exported every 30 seconds: gen_ai.client.token.usage (by gen_ai.token.type), hordecode.chat.cost (US dollars) and hordecode.chat.duration (milliseconds). The attributes are the provider and the model only.

Prompt text, task text, file paths, tool arguments and error messages are never added to spans or metrics. The last span batch is sent before the CLI exits, so short commands such as horde run keep their final spans. In the TUI, View status lists the endpoints the server exports to.

Experimental

These environment variables enable experimental features that may change or be removed.

Variable	Type	Description
`HORDECODE_EXPERIMENTAL`	boolean	Enable the experimental umbrella flag
`HORDECODE_EXPERIMENTAL_ICON_DISCOVERY`	boolean	Enable icon discovery
`HORDECODE_EXPERIMENTAL_DISABLE_COPY_ON_SELECT`	boolean	Disable copy on select in TUI
`HORDECODE_EXPERIMENTAL_BASH_DEFAULT_TIMEOUT_MS`	number	Default timeout for bash commands in ms
`HORDECODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX`	number	Max output tokens for LLM responses
`HORDECODE_EXPERIMENTAL_FILEWATCHER`	boolean	Enable file watcher for entire dir
`HORDECODE_EXPERIMENTAL_OXFMT`	boolean	Enable oxfmt formatter
`HORDECODE_EXPERIMENTAL_LSP_TOOL`	boolean	Enable experimental LSP tool
`HORDECODE_EXPERIMENTAL_DISABLE_FILEWATCHER`	boolean	Disable file watcher
`HORDECODE_EXPERIMENTAL_EXA`	boolean	Enable experimental Exa features
`HORDECODE_EXPERIMENTAL_LSP_TY`	boolean	Enable TY LSP for python files
`OPENCODE_EXPERIMENTAL_PLAN_MODE`	boolean	Enable plan mode
`OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS`	boolean	Enable background subagent tasks
`OPENCODE_EXPERIMENTAL_EVENT_SYSTEM`	boolean	Enable experimental event system
`OPENCODE_EXPERIMENTAL_NATIVE_LLM`	boolean	Enable native LLM request path
`OPENCODE_EXPERIMENTAL_PARALLEL`	boolean	Enable parallel web search execution
`HORDECODE_EXPERIMENTAL_WORKSPACES`	boolean	Enable workspace support