CLI Reference
-Huskies ships as a single binary. Most interaction happens through the web UI or chat transports, but the CLI is used for initial setup and server control.
- -huskies
-Start the huskies server.
-huskies [OPTIONS]Options
-| Flag | Default | Description |
|---|---|---|
| --port <PORT> | 3000 | HTTP port to listen on. Set the HUSKIES_PORT environment variable as an alternative. |
| --project <PATH> | current dir | Path to the project directory. Huskies looks for .huskies/ here. |
| --help | — | Print help and exit. |
| --version | — | Print version and exit. |
Examples
-# Start on the default port
-huskies
-
-# Start on a custom port
-huskies --port 3001
-
-# Specify project directory explicitly
-huskies --project /path/to/project --port 3000
-
-# Using environment variable
-HUSKIES_PORT=3002 huskiesHUSKIES_PORT to avoid conflicts when running several instances simultaneously.
- huskies init
-Initialise a project directory for use with huskies. Creates the .huskies/ directory structure, default configuration files, and .mcp.json.
huskies init [OPTIONS]Options
-| Flag | Default | Description |
|---|---|---|
| --port <PORT> | 3000 | Port written into .mcp.json for MCP tool discovery. |
| --project <PATH> | current dir | Directory to initialise. Must be a git repository. |
| --help | — | Print help and exit. |
What it creates
-| Path | Description |
|---|---|
.huskies/project.toml | Project-wide settings (QA mode, agent limits, timezone, etc.). |
.huskies/agents.toml | Agent definitions for coder, QA, and mergemaster roles. |
.huskies/work/1_backlog/ | Pipeline stage directories (1 through 6). |
.huskies/specs/00_CONTEXT.md | Placeholder project context file for the setup wizard. |
.huskies/specs/tech/STACK.md | Placeholder tech stack file for the setup wizard. |
.mcp.json | MCP server config so Claude Code discovers huskies' tools automatically. |
git init first if needed.
- huskies agent
-Spawn a single agent process directly from the command line. This is the command the server uses internally when you run start <number> in chat — you rarely need to invoke it manually.
huskies agent [OPTIONS]Options
-| Flag | Description |
|---|---|
| --story <ID> | Story ID slug to work on (e.g. 42_story_add_login). |
| --agent <NAME> | Agent name from agents.toml to use (e.g. coder-1, qa). |
| --worktree <PATH> | Path to the git worktree the agent should work in. |
| --port <PORT> | Huskies server port, so the agent can call MCP tools. |
| --help | Print help and exit. |
Environment variables
-| Variable | Description |
|---|---|
HUSKIES_PORT | Server port. Overrides the --port flag. |
ANTHROPIC_API_KEY | Anthropic API key for agent sessions. Can also be set via the web UI on first use. |
GITEA_TOKEN | Gitea API token used by the script/release script when publishing releases. |
Gateway event-push protocol
-Project nodes can push pipeline status events to the gateway in real time over a WebSocket connection. The gateway fans each event out to all connected local subscribers.
- -Connecting
--
-
- Obtain a one-time join token:
POST /gateway/tokens→{"token":"…"}
- - Open a WebSocket upgrade to
GET /gateway/events/push?token=TOKEN&project=PROJECT_NAME
- - The token is consumed on upgrade. The project name is attached to every event the server broadcasts downstream. -
Sending events
-Each message must be a JSON-encoded StoredEvent frame:
// Stage transition
-{"type":"stage_transition","story_id":"42_story_login","from_stage":"2_current","to_stage":"3_qa","timestamp_ms":1700000000000}
-
-// Merge failure
-{"type":"merge_failure","story_id":"42_story_login","reason":"conflict in src/main.rs","timestamp_ms":1700000001000}
-
-// Story blocked
-{"type":"story_blocked","story_id":"42_story_login","reason":"retry limit exceeded","timestamp_ms":1700000002000}The server does not send frames back. Any other frames received by the project node indicate an error or server restart — treat them as a disconnect signal.
- -Reconnect with exponential back-off
-Project nodes must reconnect on any disconnect. Use the following policy to avoid thundering herds after a gateway restart:
-| Parameter | Value |
|---|---|
| Initial delay | 1 s |
| Back-off multiplier | 2× per attempt |
| Maximum delay | 60 s |
| Jitter | ±10 % of the computed delay |
Pseudocode:
-delay = 1.0 // seconds
-max_delay = 60.0
-
-loop:
- token = POST /gateway/tokens
- connect ws:/gateway/events/push?token=TOKEN&project=NAME
- while connected:
- send StoredEvent frames
- // disconnected — wait and retry
- jitter = delay * (random(0.9, 1.1))
- sleep(min(jitter, max_delay))
- delay = min(delay * 2, max_delay)Building from source
-Standard release build
-cargo build --release
-# Output: target/release/huskiesStatic Linux binary (musl)
-Requires cross: cargo install cross.
cross build --release --target x86_64-unknown-linux-muslDocker image
-docker compose -f docker/docker-compose.yml buildRelease script
-Builds macOS arm64 and Linux amd64 binaries, bumps the version, tags the repo, and publishes a Gitea release with changelog and binaries attached.
-script/release 0.8.0
-