Horus CLI
horus-cli is the reference Ratatui client for a horus-gateway. The gateway owns agent
composition, providers, sessions, sandboxing, usage, and scheduled work.
Install the client
Download one horus-cli archive and checksum from
GitHub Releases:
- Apple Silicon macOS:
aarch64-apple-darwin - x86_64 Linux:
x86_64-unknown-linux-gnu
Verify with shasum -a 256 -c FILE.sha256, extract the included horus and
horus-gateway binaries into one directory, and put it on your PATH. Rust users and other
macOS or Linux architectures can install both commands with Rust 1.89 or newer:
If the earlier standalone gateway package is installed, run
cargo install --force --locked horus-cli once to transfer both commands to this package.
Gateway included
The CLI package installs its gateway beside horus; the core horus crate is linked into the
binaries. Run the CLI from the workspace for the chat you want to create:
With no explicit gateway endpoint or token, the first run initializes the machine-wide default
gateway with both a loopback listener and Cloudflare Quick Tunnel, provisions the CLI's local
credential, and starts horus-gateway in the background. A later horus-gateway connect
advertises the local TCP and public WSS endpoints with one pairing code that works through either
endpoint.
If no model provider is configured, the same three-page /login flow opens immediately. The
first configured model becomes the gateway default for new chats.
Each run creates a chat scoped to the current directory; /workspace <gateway-path> creates and
selects another chat without changing other running chats. For a source checkout, build both
commands from the CLI package:
Plaintext is restricted to loopback. A gateway reachable over the network must use a publicly trusted TLS certificate matching its public hostname. Initialize it once, then run the supervised connection flow while the gateway is stopped:
Then use the endpoint and one-time code it displays on the client machine:
horus pair saves and selects the endpoint together with the token returned by the gateway; no
environment variable is needed. A remote terminal opens an existing gateway chat, so create the
first gateway-host workspace chat from an Apple or local frontend.
If the gateway is already running, create another code with /pair from an authenticated terminal
or Gateway → Pair another device in an Apple client.
If local state already exists without a saved CLI token, stop the gateway and run the supervised pairing flow in another terminal:
Run one task file without the TUI:
# From a source checkout:
The selected chat workspace—not the CLI process—is the command and file boundary. An approval prompt aborts a headless run, so scheduled work that edits files or runs commands needs an appropriate chat approval policy.
Inside the TUI, /cron new [task] starts the model-assisted setup. The model asks for missing task
or frequency details, then an approval-required gateway tool saves and registers the final task.
Ordinary chat cannot create schedules. /cron also exposes list, reschedule, delete, run, and
history operations for the selected chat; every scheduled execution creates a separate durable
result chat.
/login is the single provider setup path. It opens the guided provider screen, where API keys
can be pasted into a masked field, the environment variable declared by the provider manifest is
used when the field is empty, and device-login providers show their login flow. There is no
separate environment-name setting. Setup covers the built-in manifests compiled into both the
gateway and CLI; injected ModelRouter entries are library-only. The final page confirms the
provider's model and reasoning choice. The gateway owns the complete configured-model catalog and
new-chat default; /model only changes the selected chat to one of those available routes.
/agent opens a one-page capability and approval-policy editor without changing the selected
provider or system prompt. Required gateway capabilities remain visible but cannot be deselected.
Secrets are sent directly to the gateway and never returned to the CLI.
/gateway lists saved endpoints and opens a second page to pair a new endpoint; reconnect and
delete act on the selected saved gateway. Explicit endpoint or token environment variables make
that screen read-only until they are unset.
API-key providers use their standard environment variables:
The CLI stores only an owner-readable selected endpoint and endpoint-token map at
~/.horus/gateway-tokens.json. HORUS_GATEWAY_TOKEN overrides the saved token explicitly;
HORUS_GATEWAY_TOKEN_FILE changes the account-file path.
Terminal contributions
The TUI is a thin subscriber to the framework capability catalog:
- Capabilities own their commands, status widgets, references, and capability-specific rendering.
/opens both CLI shell commands and commands contributed by framework capabilities.$references are contributed by skills middleware.@workspace-file completion is available for a local plaintext gateway; TLS gateways do not scan similarly named paths on the client machine.
The CLI owns only shell lifecycle and presentation commands: /help, /gateway, /agent,
/login, /pair, /profile, /artifacts, /new, /clear, /model,
/reasoning, /cron, /status, /interrupt, and /exit. The menu changes with the installed
gateway capabilities. The gateway always contributes /resume as the single saved-chat picker;
it lists chats across every workspace.
The Sora-themed TUI uses the full terminal. The mouse wheel and Page Up/Page Down scroll the chat; Ctrl-T opens a full-screen transcript view, releases mouse capture for native drag-to-copy, and scrolls with Arrow or Page Up/Page Down. Up/Down and Ctrl-P/Ctrl-N navigate composer history.
Sandboxing runs on the gateway host and fails closed when its platform sandbox is unavailable.
License
Licensed under Apache-2.0. See NOTICE for upstream attribution.