# hyperguild CLI

A small Go binary for tier probing, brain HTTP REST access, and
`.mcp.json` mode bootstrap. Replaces the supervisor's `tier` MCP and
gives shell scripts a stable interface to the brain.

## Install

```bash
task hyperguild:install
# or: go install ./cmd/hyperguild
```

The binary lands at `$(go env GOBIN)/hyperguild` (typically
`~/go/bin/hyperguild`). Make sure that's on your PATH.

## Subcommands

### `hyperguild tier`

Probes Anthropic and LiteLLM and reports the current operating tier.

```bash
$ hyperguild tier
tier 1 (full-online) managed_agents=true

$ hyperguild tier --json
{
  "tier": 1,
  "label": "full-online",
  "available_models": null,
  "managed_agents": true
}
```

Probe URLs are read from environment:

| Var                   | Default                       |
|-----------------------|-------------------------------|
| `ANTHROPIC_PROBE_URL` | `https://api.anthropic.com`   |
| `LITELLM_BASE_URL`    | (empty → falls through to airplane) |

### `hyperguild brain query <topic>`

BM25 search over the brain's knowledge + wiki entries.

```bash
$ hyperguild brain query "find -H symlink"
knowledge/2026-05-03-find-h-not-l-symlinked-root.md  score=12  Use find -H, not find -L
...
```

Flags:

- `--limit N` — max results (default 5)
- `--json` — emit the raw response envelope

### `hyperguild brain write <wing> <hall> <slug>`

Reads markdown from stdin, writes it to `brain/wiki/<wing>/<hall>/<slug>.md`
with `wing`/`hall`/`created_at` frontmatter injected (there is no legacy
`brain/knowledge/` fallback — ADR-0012 / #79, both wing and hall are
required).

```bash
$ cat <<EOF | hyperguild brain write homelab facts example-lesson
# Example lesson

## Lesson
...
EOF
wiki/homelab/facts/example-lesson.md
```

### `hyperguild brain pass-rate <skill>`

Returns the pass rate for a skill over a lookback window. Computed
on-demand from `brain/sessions/*.jsonl`.

```bash
$ hyperguild brain pass-rate tdd
tdd: 47 / 50 = 94% (window: 7d)

$ hyperguild brain pass-rate tdd --window 30d --json
{
  "skill": "tdd",
  "window": "30d",
  "pass": 142,
  "fail": 8,
  "skip": 5,
  "total": 155,
  "pass_rate": 0.9467
}
```

Flags:

- `--window` — lookback window (default `7d`; accepts `Nh`, `Nd`)
- `--json` — emit the raw response envelope

Skills with no logged invocations return zero counts and `pass_rate: null`
(indicating "no data", distinct from "always passes").

### `hyperguild mode <cloud|client-local|sovereign>`

Writes a `.mcp.json` template for the chosen operating mode.

```bash
$ hyperguild mode cloud --out ./.mcp.json
wrote ./.mcp.json (mode: cloud)
```

Flags:

- `--out PATH` — output file (default `./.mcp.json`)
- `--force` — overwrite an existing file

Modes (all list **brain + gitea** — Gitea is the audit-trail invariant of the
consolidated single harness, #75):

- **cloud** — brain + gitea MCP.
- **client-local** — brain + gitea MCP. (The former `routing` entry pointing at
  `koala:30310/mcp` was removed — the routing pod is iceboxed, #75.)
- **sovereign** — brain + gitea, with a `_mode_note` explaining that this mode
  primarily uses Crush + LiteLLM and the `.mcp.json` is a Claude Code fallback
  for emergency offline use.

## Environment

| Var                   | Default                  | Used by             |
|-----------------------|--------------------------|---------------------|
| `BRAIN_URL`           | `http://koala:30330`     | `brain *`, `mode *` |
| `ANTHROPIC_PROBE_URL` | `https://api.anthropic.com` | `tier`           |
| `LITELLM_BASE_URL`    | (empty)                  | `tier`              |

Override `BRAIN_URL` if your brain pod is at a different Tailscale name
or port.

## See also

- `docs/superpowers/specs/2026-05-03-hyperguild-cli-design.md` — full spec
- `docs/superpowers/plans/2026-05-03-hyperguild-cli.md` — implementation plan