# CLI Reference — Huskies Docs
Command-line reference for huskies, huskies init, and related subcommands.

# 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 huskies

Multiple instances: Each worktree or project can run its own huskies instance on a different port. Use `HUSKIES_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 required: The project directory must be a git repository. Run `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.

## Building from source

### Standard release build

    cargo build --release
    # Output: target/release/huskies

### Static Linux binary (musl)

Requires `cross`: `cargo install cross`.

    cross build --release --target x86_64-unknown-linux-musl

### Docker image

    docker compose -f docker/docker-compose.yml build

### Release 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