# Hack Dance Hack Hack CLI

> hack CLI

- Skill: `tomevault-io/hack-dance-hack-hack-cli` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/hack-dance-hack-hack-cli`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/hack-dance-hack-hack-cli/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/hack-dance-hack-hack-cli

---


# 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.default.yaml`, and optional `.hack/hack.env.<overlay>.yaml`.
- Local-only files: `.hack.secret.key`, optional `.hack/.env` compatibility output, `.hack/.env.state.json`, 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>`.

## Verification Loops

- For `hack run` / `hack exec` / env-resolution changes, verify the effective env transition matrix in
  `tests/project-run-command.test.ts`.
- Cover omitted env, explicit overlay, explicit `base`, default-overlay resolution, cached runtime-state env,
  and target-service running/not-running.
- For lifecycle or startup-process changes, verify `tests/project-lifecycle-processes.test.ts`.
- Preserve `sh -c` semantics, process-group cleanup, stale pane-metadata reconciliation, and interactive stdin
  behavior.
- When semantics change, update `docs/env.md` or `docs/lifecycle.md` in the same patch so future agent work starts
  from the current contract.

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

## Workspaces

- Picker: `hack session` for persistent project workspaces.
- Reuse/create: `hack session start <project>`
- Env-scoped workspace: `hack session start <project> --env qa --service api --detach`
- Isolated agent workspace: `hack session start <project> --new --name agent-1` (`<project>--agent-1`).
- Exec in workspace: `hack session exec <workspace> "<command>"`
- Exec in workspace with injected env: `hack session exec <workspace> --env qa --service api "bun db:migrate"`
- Stop workspace: `hack session stop <workspace>`

## Host-side env helpers

- One-off host command with injected env: `hack env exec --env qa --service api -- bun db:migrate`
- Interactive host shell with injected env: `hack env shell --env qa --service api`

## Tickets

- Create: `hack tickets create --title "..." --body-stdin`
- List/show: `hack tickets list`, `hack tickets show T-AB12CD34EF`
- Status/sync: `hack tickets status T-AB12CD34EF 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`

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/hack-dance) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->