# 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. 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:
```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.