# 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](https://github.com/citizenhicks/horus/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:
```sh
cargo install --locked horus-cli
```
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:
```sh
cd /path/to/repository
horus
```
With no explicit gateway endpoint or token, the first run initializes the machine-wide default
loopback gateway, pairs the CLI, saves its token, and starts `horus-gateway` in the background.
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:
```sh
cargo build -p horus-cli
cargo run -p horus-cli --bin horus
```
Plaintext is restricted to loopback. A gateway reachable over the network must use TLS; point the
client at that exact endpoint before pairing and connecting. Explicit endpoint or token settings
disable automatic local management:
```sh
horus pair tls://gateway.example:443 <pairing-code>
export HORUS_GATEWAY_ENDPOINT=tls://gateway.example:443
horus
```
If local state already exists without a saved CLI token, stop the gateway and pair manually:
```sh
horus-gateway pair-code
horus-gateway serve # keep this running in another terminal
horus pair tcp://127.0.0.1:8741 <pairing-code>
```
Run one task file without the TUI:
```sh
horus run path/to/task.md
# From a source checkout:
cargo run -p horus-cli --bin horus -- run path/to/task.md
```
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. 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. 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:
```sh
export OPENAI_API_KEY=...
export MOONSHOT_API_KEY=...
export OPENROUTER_API_KEY=...
export ANTHROPIC_API_KEY=...
```
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](LICENSE). See [NOTICE](NOTICE) for upstream attribution.