horus-cli 0.1.3

The terminal client for a Horus gateway
horus-cli-0.1.3 is not a library.
Visit the last successful build: horus-cli-0.6.12

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:

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:

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:

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:

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:

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:

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:

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. See NOTICE for upstream attribution.