@hack-dance/hack-cli

---
name: hack-cli
description: >
  Use the hack CLI for local runtime orchestration (compose, DNS/TLS, logs, sessions, tickets) and agent setup.
  Trigger when asked to run/start/stop services, inspect logs, manage lifecycle/session workflows, or update
  agent integrations. Prefer CLI over MCP when shell access is available.
---

# hack CLI

Use `hack` as the primary interface for local development.

## Operating Rules

- Prefer `hack` over raw `docker` / `docker compose`.
- Do not start/stop project services from Docker Desktop UI for `hack`-managed repos.
- Treat `.hack/.internal` and `.hack/.branch` as hack-managed artifacts; avoid hand-editing generated files.
- Use MCP only when shell access is unavailable.
- Run `hack doctor` (and `hack doctor --fix`) before manual runtime/network repair.

## Config + Schema

- Project config: `.hack/hack.config.json`
- Global config: `~/.hack/hack.config.json`
- Schema URL: `https://schemas.hack/hack.config.schema.json`
- Prefer CLI config edits via `hack config get/set`.

## Hostname Routing

- Primary host is `dev_host` (default: `<project>.hack`).
- Subdomains use `<sub>.<dev_host>` (for example: `api.myapp.hack`).
- OAuth alias can add `<dev_host>.<tld>` and `<sub>.<dev_host>.<tld>` (default: `gy`).
- Only HTTP services with Caddy labels and `hack-dev` network attachment are routable.
- Required labels: `caddy`, `caddy.reverse_proxy`, `caddy.tls=internal`.
- Quick checks: `hack open`, `hack open <sub>`, `hack open --json`.

## TLS + OAuth Host Rules

- Caddy internal PKI provides HTTPS for routed hosts; trust CA with `hack global trust`.
- `.hack` is local-first and not a public suffix.
- Use alias hosts like `*.hack.gy` when provider callback validation rejects non-public-suffix hosts.
- Alias hosts are local routes unless you explicitly add remote ingress/tunnel plumbing.

## Managed Files

- Source-of-truth files: `.hack/docker-compose.yml`, `.hack/hack.config.json`, `.hack/hack.env.json`.
- Local-only files: `.hack/.env` and `.hack/.internal/` (gitignored; machine-specific state).
- Generated by hack: `.hack/.internal/compose.override.yml`, `.hack/.internal/compose.env.override.yml`, `.hack/.branch/compose.<branch>.override.yml`.
- Managed via CLI: `.hack/.internal/extra-hosts.json` using `hack internal extra-hosts ...` commands.
- Lifecycle runtime files: `.hack/.internal/lifecycle/state.json`, `.hack/.internal/lifecycle/*.log`.

## Advanced Networking

- Static host mappings: set `internal.extra_hosts` in `.hack/hack.config.json`.
- Dynamic mappings for local proxies/tunnels: `hack internal extra-hosts set <hostname> <target>`.
- List/remove mappings: `hack internal extra-hosts list` / `hack internal extra-hosts unset <hostname>`.
- Prefer `host-gateway` for host-local proxy targets when possible.
- Apply changes with `hack restart`; verify with `hack doctor`.

## Quick Start

- Bootstrap project config: `hack init`
- Start services: `hack up --detach`
- Alternate shorthand: `hack up -d`
- Restart services: `hack restart`
- Open app: `hack open --json`
- Tail logs (compose): `hack logs --pretty`
- Per-service logs: `hack logs <service>`
- Snapshot logs: `hack logs --json --no-follow`
- Loki history/query: `hack logs --loki --since 2h --pretty`
- Run commands: `hack run <service> <cmd...>`
- Stop services: `hack down`

## Global Infra

- Install once: `hack global install`
- Start/stop/status: `hack global up`, `hack global down`, `hack global status`
- Global logs: `hack global logs <service> --no-follow --tail 200`

## Remote Nodes + Dispatch

- Pair/register a node: `hack node pair ...`, then verify via `hack node list` and `hack node status --watch`.
- Repair SSH access for remote Git/mutagen: `hack node ssh setup --node <id>`.
- Inspect node workspace map on the node host: `ssh <user@host> 'hack node workspace list --json'`.
- Inspect/repair controller route bridge: `hack node routes status`, `hack node routes repair`.
- Dispatch command to remote workspace: `hack dispatch run --project <name|id> --node default --branch <branch> --runner generic -- "pwd"`.

## Lifecycle + Startup

- Put host setup in `.hack/hack.config.json` under `startup` / `lifecycle`.
- Use lifecycle processes for long-running host tasks, not ad-hoc terminals.
- Inspect via `hack projects --details` and `hack logs <service-or-process>`.

## Branch Instances

Use branch instances to run parallel environments:

- `hack up --branch <name> --detach`
- `hack open --branch <name>`
- `hack logs --branch <name>`
- `hack down --branch <name>`

## Sessions

- Picker: `hack session`
- Start/attach: `hack session start <project>`
- Isolated agent session: `hack session start <project> --new --name agent-1`
- Exec: `hack session exec <session> "<command>"`
- Stop: `hack session stop <session>`

## Tickets

- Create: `hack tickets create --title "..." --body-stdin`
- List/show: `hack tickets list`, `hack tickets show T-00001`
- Status/sync: `hack tickets status T-00001 in_progress`, `hack tickets sync`

## Project Targeting

- Run from repo root when possible.
- Otherwise use `--project <name>` or `--path <repo-root>`.
- List projects: `hack projects --json`.

## Agent Maintenance

- Project-level hack commands auto-check integration drift and attempt auto-sync.
- Set `HACK_SETUP_SYNC_MODE=warn` to warn-only, or `HACK_SETUP_SYNC_MODE=off` to disable.
- Refresh project + global integrations: `hack setup sync --all-scopes`
- Check generated integrations: `hack setup sync --all-scopes --check`
- Remove generated integrations: `hack setup sync --all-scopes --remove`
- After self-update: `hack update` then `hack setup sync --all-scopes`

## Agent Setup

- Cursor rules: `hack setup cursor`
- Claude hooks: `hack setup claude`
- Codex skill: `hack setup codex`
- Tickets skill: `hack setup tickets`
- Init prompt: `hack agent init` (use --client cursor|claude|codex to open)
- Init patterns: `hack agent patterns`
- MCP (no shell only): `hack setup mcp`
- MCP install (explicit): `hack mcp install --all --scope project`