# Core Docs Core docs are the default path through `hack`. This section stays focused on local project orchestration: initialize a repo, run it on an isolated network, reach it on stable local hostnames, manage env and lifecycle, and keep working sessions alive. You do not need gateway, remote nodes, or extension setup to use this path. ## Start here - [Initialize a project](/docs/v4/guides/init-project) — or let an agent drive it with `hack init --with claude|codex|both` (existing projects: `hack agent onboard`) - [Architecture](/docs/v4/architecture) - [Env & secrets](/docs/v4/env) - [Lifecycle](/docs/v4/lifecycle) - [Sessions](/docs/v4/sessions) - [CLI overview](/docs/v4/cli) — supported command surface and agent/scripted ergonomics ## Day-to-day core workflows - Install + quick start: [root README](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/README.md) - Local runtime checks: - `hack up --detach` - `hack open` - `hack logs --pretty` - `hack status` / `hack ps` - `hack down` / `hack restart` - If runtime state looks wrong, run `hack doctor`, then `hack doctor --fix` before manual repair. - `hack up`/`down`/`restart`/`doctor` accept `--json` for a stable `{ok, data | error: {code, message}}` envelope with `E_*` error codes, and a global `--no-interactive` (or `HACK_NO_INTERACTIVE=1`) so scripted/agent runs never block on prompts. - In a linked git worktree, `hack up` defaults to a branch instance named after the worktree's git branch (`worktree.auto_branch`), and the secret key is inherited automatically from the primary checkout via the shared git common dir. A detached linked worktree has no branch name to derive; pass `--branch `, or set `worktree.auto_branch=false` when intentionally targeting the base instance. ## When to leave core Move to [Beta workflows](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/docs/beta.md) only when you intentionally want unsupported experimental: - gateway exposure - remote nodes - remote execution - remote supervisor jobs Move to [Extensions & reference](/docs/v4/reference) when you need the full command table, extension authoring details, or API-level reference material. --- # Initialize a project This sets up a repo so it can run under hack. ```bash cd /path/to/repo hack init hack up --detach hack open ``` Notes: - `hack init` writes `.hack/` files (Compose + config). - `hack init` also scaffolds `.hack/hack.env.default.yaml`. See `docs/env.md`. - `hack up` starts the stack on an isolated network. - `hack open` resolves the routed URL via the global proxy and prefers the OAuth alias when `oauth.enabled` is true. Set `open.prefer` or pass `--prefer auto|alias|dev` to override. Optional: - `hack logs --pretty` for log tailing. - `hack tui` for the interactive dashboard. - Configure log retention in `hack.config.json` via `logs.retention_period` (e.g. `7d`) and `logs.clear_on_down`. - Add startup hooks/host processes in `.hack/hack.config.json` under `lifecycle` (or `startup` shorthand). See `docs/lifecycle.md`. - For fixed-port host helpers such as SSM tunnels, add `singleton.ports` and usually `onConflict: "adopt"` so `hack up` reuses an already-running equivalent helper instead of starting duplicate tunnel stacks. Note: - Inside containers, `localhost` points at the container itself. Update any `localhost:PORT` references to: - HTTP services via `https://*.hack` hostnames (matching your Caddy labels) - non-HTTP services via Compose service hostnames (e.g. `db`, `redis`) ## What discovery checks (and what it can't) `hack init` (interactive and `--auto`) discovers dev scripts across a repo/monorepo and runs a validation pass over the results before writing `.hack/docker-compose.yml`. It catches common scaffolding mistakes automatically, but it is not a substitute for reviewing the generated compose file: - **Duplicate/aggregator script dedupe**: when a package defines both `dev` and `start` (or similar), only the best-scoring script becomes a service — no more `web` + `web-2`. Root-level "aggregator" scripts that just delegate to a workspace package's own dev script (e.g. `turbo run dev --filter=web`, or `dotnet run --project apps/backend`) are also dropped in favor of the package-local script. In the interactive wizard, the deduped set is pre-selected by default — you can still add a dropped script back manually. - **Port reassignment**: HTTP services that would collide on the same internal port are deterministically reassigned to the next free port (ascending from the collision), and the container command is rewritten to match. Each reassignment is logged as a warning. - **Runtime TODOs**: services whose dev script looks non-JS (`.csproj`/`.fsproj`, `go.mod`, `Cargo.toml`, `pyproject.toml`/`requirements.txt`, `mix.exs`, `Gemfile`, or a command like `dotnet run`/`go run`/`cargo`/`python`/`mix`) get an obviously-wrong placeholder image (`alpine:3`) plus a `TODO(hack-init): ...` comment above the service in the compose file — instead of silently getting the default Bun/Node image. You must replace the image and command by hand. - **Native file watching**: generated services use the container runtime's native file notifications. Hack does not force Chokidar or Watchpack polling because polling a bind-mounted monorepo can consume substantial CPU and disk I/O. Add `CHOKIDAR_USEPOLLING` or `WATCHPACK_POLLING` to an individual service only when its runtime has a demonstrated file-notification problem. - **Backing-service warnings**: dependencies (`pg`, `ioredis`, `@temporalio/*`, `kafkajs`, `amqplib`, `mongodb`/`mongoose`, `prisma`, ...) and `.env`/`.env.example` key names (never values) are scanned for signals of postgres, mysql, redis, temporal, kafka, rabbitmq, or mongodb. These are **not** auto-scaffolded — they show up as warnings and as a comment block at the top of the generated compose file with a one-line suggestion each. If a `docker-compose*.yml`/`compose*.yml` already exists at the repo root, it's flagged too ("treat it as ground truth for backing services and images") instead of being re-derived from scratch. None of this replaces reviewing the scaffold. Discovery is a best-effort heuristic pass, not ground truth — always inventory the generated `.hack/docker-compose.yml` against the real repo before running `hack up` (agents included; see the onboarding prompt for the inventory-first review step). When the local path is working and you intentionally want remote execution or gateway exposure, move to [Beta workflows](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/docs/beta.md). For full command lookup and extension docs, use [Extensions & reference](/docs/v4/reference). --- # Env & secrets Hack now uses repo-level env overlay files as the canonical project env model. The short version: - commit `.hack/hack.env.default.yaml` - optionally commit `.hack/hack.env..yaml` - use `.hack/hack.env.local.yaml` and `.hack/hack.env..local.yaml` for worktree-local overrides - keep `.hack.secret.key` out of git, or provide `HACK_ENV_SECRET_KEY` - let `hack up`, `hack run`, `hack restart`, `hack host exec`, `hack host shell`, and env-aware session flows inject values directly at runtime - use `hack env materialize` only when you explicitly need a compatibility `.hack/.env` ## Current model Canonical env state lives at the repo root: - `.hack/hack.env.default.yaml` - `.hack/hack.env..yaml` - `.hack/hack.env.local.yaml` - `.hack/hack.env..local.yaml` Legacy compatibility note: - if an older repo already tracks `.hack/hack.env.local.yaml` as the shared `--env local` overlay, Hack keeps reading that file as the shared overlay - in that compatibility case, worktree-local default overrides are written to `.hack/hack.env.default.local.yaml` so `--local` mutations do not overwrite tracked shared config Compatibility and local-only state still lives under `.hack/`: - `.hack/.env` - `.hack/.env.state.json` - `.hack/.internal/...` Encryption key material is local-only by default: - `.hack.secret.key` - or `HACK_ENV_SECRET_KEY` `hack init` now scaffolds `.hack/hack.env.default.yaml` by default. ## Ignore rules (committed `.hack/.gitignore`) Hack owns a committed `.hack/.gitignore` that keeps machine-local generated files out of git. Because the file is committed, fresh clones and linked git worktrees inherit the rules with zero setup. It covers (patterns relative to `.hack/`): - `.internal/` - `.branch/` - `.env` - `.env.state.json` - `hack.env.local.yaml` - `hack.env.*.local.yaml` - `tickets/` (retained only to contain retired machine-local ticket caches during upgrades) How it is maintained: - written by `hack init`, and self-healed by `hack up` and whenever hack writes `.hack/.internal/` overrides or `--local` env overrides - the entries live inside a marked, hack-managed block; anything you add outside the markers is preserved on every rewrite - the root `.gitignore` still gets a `.hack.secret.key` entry when the secret key is first generated (the key lives at the repo root, not under `.hack/`) - older repos that added `.hack/.internal/` to the root `.gitignore` keep working; the entries are equivalent and nothing is removed Leak detection and repair: - `hack doctor` runs a "generated files" check: it lists any of the paths above (including retired `.hack/tickets/` caches, plus `.hack.secret.key`) that are tracked in git, except a tracked `.hack/hack.env.local.yaml`, which is never flagged because older repos may intentionally track it as the shared `--env local` overlay (see the legacy compatibility note above) - a tracked `.hack.secret.key` is reported as an error — it is a committed secret; rotate it after untracking - `hack doctor --fix` untracks the offenders with `git rm --cached` (files stay on disk) and re-ensures `.hack/.gitignore`; commit the removal - `--fix` and `--migrate-env-config` cannot be combined with `--json`; run the repair and JSON audit separately so a mutating request is never silently ignored. run them separately from a JSON-mode invocation ## File format Each env file is YAML with: - `version: 1` - `environment` - `secretsprovider: project_key` - `values` `values` is split by scope: - `global`: values applied everywhere - ``: values applied only for that compose service - `host`: optional overrides applied to host execution (`hack host exec`, `hack host shell`, and lifecycle hooks/processes) Example: ```yaml version: 1 environment: default secretsprovider: project_key values: global: GLOBAL_FLAG: "true" API_BASE_URL: "https://api.example.com" api: PORT: "4000" SERVICE_TOKEN: secure: v1:... ``` Plaintext values are written as scalars. Secret values are written as `{ secure: ... }`. ## Merge rules Hack resolves env in this order: 1. load `.hack/hack.env.default.yaml` 2. if `--env=` is selected, load `.hack/hack.env..yaml` 3. load `.hack/hack.env.local.yaml` 4. if `--env=` is selected, load `.hack/hack.env..local.yaml` 5. merge `values.global` 6. if a service scope is requested, merge `values.` on top Worktree-local overrides win over shared repo overlays. Service values override global values. Host execution applies `host` values last. This includes `hack host exec`, `hack host shell`, and lifecycle hooks/processes, which all run on the host rather than in Compose. Projects can set a default overlay in `.hack/hack.config.json`: ```json { "env": { "defaultOverlay": "qa" } } ``` Use `--env=base` to bypass that default and read only `.hack/hack.env.default.yaml`. ## Runtime behavior Direct runtime injection is the default path. Hack reads the canonical YAML files and injects the resolved env directly into: - `hack up` - `hack run` - `hack restart` - lifecycle host processes - `hack host exec` - `hack host shell` - `hack session start --env ... --service ...` - `hack session exec --env ... --service ...` That means `.hack/.env` is no longer the primary runtime source of truth. `hack env materialize` is manual by design. Use it only when you need a compatibility file for an external tool that expects `.env` on disk. For host execution, `hack host exec`, `hack host shell`, and lifecycle hooks/processes use a host-local view. That means Hack prefers host-usable values when it can: - explicit `host` scope values override the normal `global` + `` merge - common container-only hostnames such as `host.docker.internal` and compose service hosts are rewritten to `127.0.0.1` Use `--target compose` if you explicitly want the container-oriented compose view instead. ## Choosing the right execution surface - `hack host exec` / `hack host shell`: run on your host machine with Hack-resolved env injected. - `hack run ...`: run a one-off command in the compose network with an ephemeral service container. - `hack exec ...`: run inside an already-running container when you specifically need that container's live filesystem or process context. For host execution, `--scope` means "which env scope should Hack inject", not "where should this run." For example, `hack host exec --scope api -- bun db:migrate` still runs on the host. ## Common commands Inspect resolved env: ```bash hack env list hack env list --env qa hack env list --env qa --service api hack env list --json hack env list --show-secrets hack env explain GITHUB_TOKEN --env runner --service installer --target compose ``` `hack env explain` never prints the value. It reports availability, secret classification, selected/effective scope, source file and precedence, and whether the value is delivered to host lifecycle code or Compose. Recreate just one service after an env change with: ```bash hack env apply --service api --env qa ``` `--show-secrets` prints secret values in plaintext instead of the masked default; use it deliberately. Add or update values: ```bash hack env add API_BASE_URL https://api.example.com hack env add SERVICE_TOKEN abc123 --service api --secret hack env add --env qa API_BASE_URL https://qa.example.com hack env add API_BASE_URL https://api.example.com --local ``` `hack env set` still works as a compatibility alias for `hack env add`, but `add` is the primary UX now. `--local` writes to the worktree-local override file (`.hack/hack.env.local.yaml` or `.hack/hack.env..local.yaml`) instead of the shared repo env file — use it for per-checkout values you don't want to commit. If you omit `key`, `value`, or `--service`, `hack env add` prompts for them interactively. Pass `--no-interactive` (or set `HACK_NO_INTERACTIVE=1`) for scripted/agent usage: the command applies documented defaults or fails fast with `E_INTERACTIVE_REQUIRED` instead of blocking on a prompt. `hack env unset` and `hack env set` accept `--local` and `--no-interactive` too. Remove a value: ```bash hack env unset API_BASE_URL hack env unset SERVICE_TOKEN --service api --env qa hack env unset API_BASE_URL --local ``` Materialize a compatibility `.hack/.env`: ```bash hack env materialize hack env materialize --env qa hack env materialize --env qa --service api ``` Run a host command with injected env: ```bash hack host exec -- bun db:migrate hack host exec --env qa --scope api -- bun db:migrate hack host exec --env qa --scope api --target compose -- bun test ``` Cancelling `hack host exec` or `hack env exec` with SIGINT or SIGTERM forwards the signal to the command. Commands run in an owned process group, so cancellation also stops their descendants, escalating to SIGKILL after two seconds if necessary. Hack returns 130 for SIGINT and 143 for SIGTERM. Interactive commands use a supervisor in their own foreground group on the same terminal, preserving stdin, separate output streams, and Ctrl-Z/foreground resume. Piped stdin also retains the controlling terminal, so commands can open `/dev/tty` for native authentication prompts. The supervisor holds group ownership until cancellation cleanup finishes. SIGKILL cannot be forwarded; supervisors must terminate the whole owned process tree when force-killing a wrapper. Commands have no implicit time limit, and normal completion preserves the command's exit status. When you want to inspect an injected value, avoid `hack host exec -- echo $VAR`. Your current shell expands `$VAR` before Hack starts the child process, so the command often sees an empty string. Use one of these instead: ```bash hack host exec -- printenv APPLE_TEAM_ID hack host exec -- sh -lc 'printf "%s\n" "$APPLE_TEAM_ID"' hack host exec --shell 'echo $APPLE_TEAM_ID' ``` Open a host shell with injected env: ```bash hack host shell hack host shell --env qa --scope api hack host shell --env qa --scope api --target compose ``` Example with an explicit host override: ```yaml version: 1 environment: default secretsprovider: project_key values: global: DATABASE_URL: secure: v1:... REDISHOST: redis host: REDISHOST: "127.0.0.1" ``` ## Sessions and env Session flows can now carry env selection too. Examples: ```bash hack session start my-project --env qa --service api --detach hack session exec my-project.env-qa.svc-api --env qa --service api "bun db:migrate" ``` When you pass `--env` or `--service`, Hack creates a stable scoped workspace name instead of reusing the plain default workspace. That prevents one shell from silently inheriting the wrong env selection. ## Secret key handling Secret values in the YAML files are encrypted with the project key. Default behavior: - generate `.hack.secret.key` the first time you add a secret - add `.hack.secret.key` to `.gitignore` - decrypt secrets from `.hack.secret.key` on the local machine - linked git worktrees can reuse the primary checkout's `.hack.secret.key` when the worktree copy is missing Linked worktree behavior: - when a repo uses linked git worktrees, Hack prefers a shared key under the git common dir - sibling worktrees can decrypt the same committed secrets without manually copying gitignored files - if a checkout-local `.hack.secret.key` exists, it still wins for that checkout - `hack up` in a linked worktree auto-selects a branch instance (`worktree.auto_branch`); that selection determines which instance's resolved env is the one actually injected, so keep the key readable from every checkout that runs `hack up` Full read order for decrypting secrets (first match wins): 1. checkout-local `.hack.secret.key` 2. shared key under the git common dir 3. the primary checkout's key, inherited automatically for a linked worktree that has neither of the above 4. `HACK_ENV_SECRET_KEY` Write-path guarantees in a linked worktree (first secret added from any checkout): - an existing checkout-local key is reused as-is - otherwise an existing shared key (git common dir) is reused - otherwise the primary checkout's key is adopted by copying it to the shared location, so sibling checkouts converge on one key - only then is a new key generated, and it is written to the shared location — never silently to the checkout - if the shared location cannot be resolved (git unavailable) or written, Hack falls back to a checkout-local key and prints a loud divergence warning - `hack doctor` flags divergent `.hack.secret.key` contents across checkouts with the exact paths CI and managed container fallback: - if `.hack.secret.key` is missing, Hack falls back to `HACK_ENV_SECRET_KEY` That makes this model usable in CI and portable container images without committing the key file. Published container paths: - slim managed-container base: `hackdance/hack:slim` — the supported CI / managed-container story - full remote runtime: `hackdance/hack:latest` — serves the remote/node surface, which is experimental and unsupported (hidden behind `hack help --all`); only relevant if you have explicitly opted into that surface In both cases, inject `HACK_ENV_SECRET_KEY` from the runtime or secret manager instead of copying `.hack.secret.key` into the image. ## Legacy repos and migration Older repos may still have: - `.hack/hack.env.json` - `.hack/.env` - `.hack/.env.` - configured secret backends via `hack env backend` Hack still detects and reads that legacy format, but the preferred migration path is: ```bash hack doctor --migrate-env-config ``` That migrates the repo into: - `.hack/hack.env.default.yaml` - `.hack/hack.env..yaml` - `.hack.secret.key` when needed `hack doctor` also warns when a repo still depends on the old format. For modern env repos, `hack doctor` also warns when materialized compatibility output in `.hack/.env` or `.hack/.env.state.json` is stale and points to `hack env materialize`. ## Compatibility notes The modern YAML env model is the canonical repo format today. Some older surfaces are still compatibility-oriented: - `hack env backend ...` remains relevant for legacy repos and older secret-store configurations - the daemon's env HTTP route (used by the macOS app) reads and writes the legacy dotenv-shaped contract (`source: 'plain_env'|'keychain'`, `resolvedFrom: 'dotenv'/'process'/'keychain'/'portable_backend'`), not the modern YAML `hack env list --json` shape; there is no web dashboard surface anymore If you are writing new docs or new project setup flows, document the YAML overlay model first and treat `.hack/hack.env.json` as legacy migration context. ## Recommended project policy - Commit `.hack/hack.env.default.yaml` - Commit `.hack/hack.env..yaml` when the overlay is team-shared - Never commit `.hack.secret.key` - Prefer `hack env add` over hand-editing encrypted values - Prefer direct runtime injection over materializing `.hack/.env` - Use `hack host exec` or env-aware sessions for host-side scripts like migrations, generators, and admin tasks ## Related docs - [Initialize a project](/docs/v4/guides/init-project) - [Sessions](/docs/v4/sessions) - [CLI reference](/docs/v4/cli) - [Pulumi-style env config design](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/docs/plans/2026-03-27-pulumi-style-env-config-design.md) ### Host command lifetime and diagnostics `hack host exec` and `hack env exec` record payload-free execution metadata under `$HACK_HOME/host-commands` (normally `~/.hack/host-commands`). Records contain the executable basename, project, process identities, owned process group, intended lifetime, elapsed time, exit/cancellation/timeout outcome, and final child CPU/RSS accounting. Arguments, shell strings, environment values and command output are not recorded. Completed records expire after seven days during later executions; interrupted records remain available for review. A diagnostic storage failure warns on stderr and preserves command execution and exit status. ```sh hack host exec --timeout 60 -- bun scripts/check.ts # Lifecycle (startup hooks + host processes) Many projects need host-side setup around `hack up` (auth, local proxies, tunnels). Lifecycle config lets you run short-lived commands and manage long-running host processes alongside the project runtime. Lifecycle is configured in `.hack/hack.config.json` under `lifecycle`. You can also use a shorthand `startup` array for common `hack up` startup flows. ## Why `singleton` exists Some lifecycle-managed helpers bind fixed local ports and are easy to start outside Hack: - AWS SSM port-forwarding tunnels - local API or database proxies - search/dashboard tunnels Without an ownership hint, `hack up` can only assume it should launch the configured command again. If a matching helper is already running manually, or a previous reconnect loop already restored it, that can create duplicate supervisors, partial port conflicts, or aggressive cleanup/restart churn. `singleton` exists to make those fixed-port helpers explicit. It gives Hack a conservative rule: - start the helper when none of its expected listeners exist - adopt the existing helper when the full listener set is already healthy and the config opts into reuse - fail fast on partial occupancy instead of trying to replace part of a live tunnel stack That keeps Hack local-first and predictable. It avoids turning "something equivalent is already running" into "kill and recreate it", which is especially important for brittle port-forwarding workflows. ## Config ```json { "$schema": "https://schemas.hack/hack.config.schema.json", "lifecycle": { "up": { "before": [ { "name": "aws sso login", "command": "aws sso login", "cwd": "." }, { "name": "aws-ssm-proxy", "command": "bun run proxy", "cwd": "packages/infra", "persistent": true, "singleton": { "ports": [3306, 9200, 9201, 8443, 8444, 8445], "onConflict": "adopt" } } ], "after": [] }, "down": { "before": [], "after": [] }, "processes": [ { "name": "aws-proxy", "command": "bun run dev:aws-proxy", "cwd": "." } ] } } ``` ## Startup shorthand `startup` is a concise alias for startup hooks/processes: - `persistent: false` (default) maps to `lifecycle.up.before` - `persistent: true` maps to `lifecycle.processes` ```json { "$schema": "https://schemas.hack/hack.config.schema.json", "startup": [ { "name": "aws sso", "run": "aws sso login", "persistent": false }, { "name": "aws-ssm-proxy", "run": "cd packages/infra && bun run proxy", "persistent": true, "singleton": { "ports": [3306, 9200, 9201, 8443, 8444, 8445], "onConflict": "adopt" } } ] } ``` Each startup item can be: - a string command (one-shot startup hook), or - an object with: - `run` (or `command`) required - `name` optional - `cwd` optional - `persistent` optional boolean (default `false`) - `singleton` optional object with `ports` and optional `onConflict` `cwd` is always resolved from the repo root (not from `.hack/`). A `persistent: true` startup entry with no `name` gets a generated name (`startup-1`, `startup-2`, ... in config order). That generated name is what shows up as the window name and what you pass to `hack logs `, so naming persistent entries explicitly makes logs easier to find. ### Hooks Hook lists live under: - `lifecycle.up.before` - `lifecycle.up.after` - `lifecycle.down.before` - `lifecycle.down.after` Each entry can be either: - a string (shell command), or - an object: - `name` (optional): label for logs - `command` (required): shell command - `cwd` (optional): working directory; relative paths are resolved from repo root - `persistent` (optional): `true` means "start this as a managed lifecycle process" - `singleton` (optional): local listener policy with: - `ports` required array of local TCP listener ports - `onConflict` optional `"adopt"` or `"fail"` (default `"fail"`) Hooks run on the host as `sh -c `. Failures stop the operation. Commands inherit the CLI process environment (including PATH), plus resolved project env vars. `persistent` behavior: - In `lifecycle.up.before`, `persistent: true` starts the command in the lifecycle mux session and immediately continues to the next hook. - Ordering is preserved: each persistent hook is started in sequence before moving to later hooks. - In other hook lists (`up.after`, `down.before`, `down.after`), `persistent` is ignored and the hook runs as a normal blocking command. `singleton` behavior: - Hack checks the configured local TCP listener ports before starting the lifecycle process. - If none of the configured ports are in use, Hack starts the process normally. - If all configured ports already have listeners and `onConflict` is `"adopt"`, Hack skips startup, records an adoption note, and leaves the external process alone on `hack down`. - If only some configured ports are already occupied, Hack fails fast instead of launching a competing partial replacement. - If all configured ports already have listeners and `onConflict` is omitted or `"fail"`, Hack stops with an explicit error so the operator can decide whether to stop or reuse the existing process. Important boundaries: - `singleton` is a listener-level guard, not a deep process identity check. - Adoption means "Hack observed the full expected local listener set and will not start another copy". It does not mean Hack now owns or can safely tear down that external process. - `hack down` only stops processes Hack actually launched inside the lifecycle session. Adopted external listeners are intentionally left alone. ### Processes Long-running processes live under `lifecycle.processes` and are objects with: - `name` (required): stable identifier (used for window naming) - `command` (required): shell command (run in a mux session shell) - `cwd` (optional): working directory (defaults to repo root) - `singleton` (optional): listener-ownership policy with `ports` and `onConflict` Processes receive the resolved env contract (see `env.md`) as their environment. ## Visibility Lifecycle output is now surfaced across CLI/runtime views: - `hack logs` includes lifecycle hook/process output alongside compose logs. - `hack logs ` supports lifecycle service names, including persistent process names. - `hack projects --details` includes a `Startup & lifecycle` section with hooks + persistent processes. - Runtime inventories include persistent lifecycle processes as synthetic services. - The macOS project detail view includes a `Startup & Lifecycle` section in the main project overview. ## Runtime behavior ### `hack up` 1. Resolve env contract (and optionally prompt for missing required env in interactive shells). 2. Run `lifecycle.up.before` hooks in order. 3. For `up.before` hooks with `persistent: true`, start each as a managed lifecycle process and continue immediately. 4. Start lifecycle processes (if any) inside the same dedicated lifecycle session. 5. Run `docker compose up` (or `up -d` when `--detach`). 6. Run `lifecycle.up.after` hooks. Before starting persistent work, Hack reconciles the expected lifecycle session with `.hack/.internal/lifecycle/state.json`: - A session whose mux ownership token, saved definition hash, and live process windows all match is adopted without starting duplicate processes. - A token-owned stale session is replaced. Pre-ownership tmux sessions are replaced only when saved state, checkout path, creation time, and window count provide deterministic legacy ownership proof. - A same-name session without matching ownership proof is left untouched and `hack up` fails with an actionable collision error. If the operation later fails in Compose or `up.after`, Hack removes only the lifecycle session created by that operation. The same exact-token cleanup runs for supported `SIGINT` and `SIGTERM` paths, including signals received while the mux session is still being initialized. ### `hack down` 1. Run `lifecycle.down.before` hooks. 2. Run `docker compose down`. 3. Stop lifecycle processes by killing the lifecycle session. 4. Run `lifecycle.down.after` hooks. If `lifecycle.down.before` fails, shutdown is aborted before Compose or lifecycle processes are stopped. `hack restart` preserves the same guard semantics during its down phase. ### `hack restart` `hack restart` runs the down lifecycle hooks and stops owned host processes, but preserves the current Compose runtime until preflight succeeds. It then force-recreates services and attempts a repair start if recreation fails. This avoids destroying a healthy stack before env and registry checks have passed. `hack restart ` is service-scoped: it skips project-wide lifecycle hooks, initializes declared shared dependency caches before replacing their selected consumers, uses `--no-deps`, and verifies only the selected services. Failed cache initialization leaves the existing consumers running. From the primary checkout, it targets only the base Compose/lifecycle instance. A linked worktree uses its isolated derived branch instance, and `--branch ` targets only that explicit branch. ### `--json` `hack up`, `hack down`, and `hack restart` accept `--json`. A lifecycle hook failure surfaces as `{ok: false, error: {code: 'E_LIFECYCLE_FAILED', message}}`; a `docker compose` failure surfaces as `E_COMPOSE_FAILED`. If Compose exits successfully but one or more containers remain `created`, exit non-zero, or enter another failed runtime state, Hack returns `E_STARTUP_INCOMPLETE`. Successful one-shot services (`exited` with code 0) are reported under `services.completed` and do not fail startup. Hack recognizes dependency installers, services labeled `hack.service.one-shot=true`, and services referenced by another service with Compose `condition: service_completed_successfully`. An unrelated service that merely exits zero is still treated as incomplete startup. Lifecycle failures are one of the primary consumers of the `--json` error envelope, since hook and process startup are common failure points around `hack up`. ## Sessions backend Lifecycle processes run inside the configured mux backend (tmux or zellij), using the same selection rules as `hack session`. Config: - Project: `.hack/hack.config.json` → `sessions.mux = auto|tmux|zellij|none` - Env override: `HACK_SESSIONS_MUX=auto|tmux|zellij|none` Lifecycle session name: - No branch: `--lifecycle` - With `--branch `: `--lifecycle-` Lifecycle hooks and processes run on the host. They receive the selected overlay's `global` values plus `host` overrides, with `host` taking precedence. Service-scoped values remain container-specific unless a host command explicitly selects that scope with `hack host exec --scope `. Notes: - If no mux backend is available, lifecycle process startup fails with an actionable error. - Teardown is implemented by killing the lifecycle session; anything running inside that session will be stopped. - Current lifecycle sessions carry the same random ownership token in mux metadata and persisted state. Cleanup requires an exact token match; deterministic names alone never authorize session teardown. - Healthy-session adoption also matches a stable SHA-256 fingerprint of the effective overlay and sorted lifecycle environment. Environment names, keys, and values are never persisted; changing an overlay or value replaces the owned session so host helpers cannot retain stale configuration. - For tmux-backed lifecycle sessions, Hack also persists the pane PID and the wrapped command's actual process-group metadata to `.hack/.internal/lifecycle/state.json`, with per-hook/process output logged to `.hack/.internal/lifecycle/*.log`. If tmux pane state disappears before teardown, `hack down` still uses that persisted metadata to clean up any live lifecycle process groups instead of leaving orphaned host processes behind. - `hack doctor` reports stale lifecycle state, leaderless process groups, ownership collisions, and ownership-proven sessions with no running Compose instance. Recently updated sessions are treated as possible in-flight startups for five minutes and stay untouched. `hack doctor --fix` reaps only established orphans after rechecking runtime liveness and mux ownership; unverified same-name sessions stay untouched. - Runtime hygiene also warns when regular Compose services are stuck in `Created`, including stacks left behind by an interrupted startup. This check is diagnostic only; inspect the explicit target with `hack ps --json` before deciding whether to retry or tear it down. ## Tips - For long-running setup commands, use either `lifecycle.processes` or `lifecycle.up.before` with `persistent: true`. - For local proxy/tunnel helpers that bind fixed ports, prefer `singleton.ports` with `onConflict: "adopt"` so `hack up` can reuse an already-running external tunnel instead of racing it. - Keep non-persistent hooks short and deterministic. - Store lifecycle secrets in `hack.env.*.yaml` as encrypted `secure:` values and prefer runtime injection over relying on `.hack/.env`. - If a hook requires interactive auth (e.g. browser-based SSO), it will still work; it runs with `stdin: inherit`. - Global `--no-interactive` (or `HACK_NO_INTERACTIVE=1`) affects only the env-prompt step in `hack up` (step 1 above): with prompting disallowed, missing required env is never prompted for — the run fails fast with an actionable error instead of blocking on a prompt, following the same `--no-interactive` convention used across the CLI (documented defaults or `E_INTERACTIVE_REQUIRED`). It does not change hook `stdin` behavior — a hook that itself blocks on interactive auth still blocks under `--no-interactive`. --- # Sessions Sessions are **persistent project workspaces**. They keep a repo-root shell alive across terminal restarts, SSH reconnects, and long-running agent work so you can return to the same context instead of rebuilding it each time. The guided default is **tmux**: - `hack session` opens a tmux-first interactive picker - `hack session start ` reuses the default project workspace unless you ask for an isolated one - `hack session start --env qa --service api` creates a stable env-scoped workspace when you need a specific overlay - `hack setup tmux` installs the recommended popup binding so the picker is easy to reach from tmux Other mux backends still exist. `sessions.mux=auto` prefers tmux and falls back to zellij when tmux is unavailable, and you can explicitly set `sessions.mux=zellij` if that is your preferred backend. The interactive onboarding and pane tooling are tmux-first today. ## Quick start ```bash # Interactive picker for existing workspaces and new project workspaces hack session # Reuse the default workspace for a project, or create it if needed hack session start # Create an env-scoped workspace for one overlay/service combination hack session start --env qa --service api --detach # List active workspaces hack session list # Attach to an existing workspace by name hack session attach # Queue a command in a running workspace hack session exec "bun test" # Queue a command with injected env for that run hack session exec --env qa --service api "bun db:migrate" # Stop a workspace hack session stop # Capture recent output (defaults to active pane) hack session capture # Tail workspace output for a short window (defaults to active pane) hack session tail # List panes in a workspace hack session panes ``` ## Core flows ### Interactive picker Running `hack session` without arguments opens an interactive picker showing: - **Active workspaces**: running workspaces from the configured mux backend(s), with attached status when the backend can report it - **Available projects**: registered projects that do not currently have a default workspace When selecting an attached session, you can choose to: - **Attach**: detach other clients and take over the workspace - **Create isolated**: start a separate long-running workspace such as `project--2` This is the recommended entry point when you want to resume a project context but do not remember the exact workspace name. `hack session` with no subcommand is inherently interactive (it prompts with a picker) and is not a scripted/agent entry point. For scripted or agent-driven runs, use `hack session start ` (optionally with `--detach`) or `hack session list --json` instead of the bare picker. ### Start and create ```bash # Reuse the default project workspace (creates it if needed) hack session start my-project # Force creation of an isolated numbered workspace hack session start my-project --new # Create an isolated workspace with a custom suffix hack session start my-project --name agent-1 # Creates: my-project--agent-1 # Prepare services before creating or attaching hack session start my-project --up # Create or reuse without attaching the current terminal hack session start my-project --detach # Create a stable env-scoped workspace hack session start my-project --env qa --service api --detach ``` Default behavior is deliberate: - The first workspace for a project is just the project name, for example `my-project` - Passing `--env` or `--service` creates a stable scoped workspace name such as `my-project.env-qa.svc-api` - `--new` or `--name` creates an isolated workspace for a second agent, experiment, or review lane - `--detach` keeps the workspace alive for another tool or terminal to attach later Workspaces are created at the project's repo root, not the `.hack/` directory. ### Attach ```bash # Attach to an existing workspace hack session attach my-project # From inside tmux, this switches clients instead of nesting tmux ``` Use `attach` when you already know which workspace you want. If you are already inside tmux, hack switches clients instead of nesting tmux inside tmux. When attaching, tmux detaches other clients to avoid terminal size conflicts across multiple devices. If the workspace is running in zellij, hack attaches to that named session directly instead. ### Stop ```bash hack session stop ``` `stop` kills the underlying mux session (`backend.killSession`) outright — anything still running inside it, including a long-lived dev server or an in-progress agent task, is terminated. There is no graceful shutdown step; if you need cleanup hooks to run first, do that before stopping. ### Exec ```bash # Send a command to a running workspace hack session exec my-project "bun test" # tmux: sends the command + Enter to the active pane # zellij: opens a new pane and runs the command because there is no active-pane equivalent # Inject a selected overlay/service into the queued command hack session exec my-project.env-qa.svc-api --env qa --service api "bun db:migrate" ``` Use `exec` when you want to drive a persistent workspace from another terminal, script, or agent without attaching interactively first. If you pass `--env` or `--service`, Hack resolves the selected project env and injects it into the queued command without materializing `.hack/.env`. ### Listing panes (tmux only) Use `hack session panes` to list panes with useful metadata (target, active flag, window/pane indices, command, path). ```bash # List panes (NDJSON start/log/end) hack session panes my-project # Explicit NDJSON output (same as the default) hack session panes my-project --json # Single JSON object output hack session panes my-project --pretty ``` `--json` and `--pretty` are mutually exclusive; passing both is an error. ### Capturing output (tmux only) `hack session capture` emits NDJSON events by default for machine parsing (start/log/end). By default it targets the active pane; use `--target` to select a specific pane. Use `--pretty` for raw pane output; `--json` and `--pretty` are mutually exclusive. ```bash # Capture last 200 lines (default) as NDJSON hack session capture my-project # Capture a specific pane target and line count (tmux pane targets use `:` and `.`) hack session capture my-project --target my-project:0.1 --lines 500 # Human-friendly raw output hack session capture my-project --pretty ``` ### Tailing output (tmux only) `hack session tail` also emits NDJSON events by default and stops after `--max-ms` (default 5000), polling every `--interval-ms` (default 500). By default it tails the active pane; use `--target` to select a specific pane. `--json` and `--pretty` are mutually exclusive. ```bash # Poll capture-pane and emit only new lines for 5s (default) hack session tail my-project # Customize polling interval and max duration hack session tail my-project --interval-ms 250 --max-ms 10000 # Human-friendly raw output hack session tail my-project --pretty ``` ## Remote access with SSH Use `hack ssh` to get connection info for remote access: ```bash # Interactive: choose Tailscale or direct SSH hack ssh # Use Tailscale SSH hack ssh --tailscale # Use direct SSH with hostname hack ssh --direct --host 192.168.1.100 # Specify user and port hack ssh --host example.com --user dev --port 2222 # Connect directly to a workspace hack ssh my-session ``` ### What `hack ssh` shows 1. **SSH command**: Copy-paste command to connect 2. **QR code**: Scan with mobile SSH apps (Blink, Termius) 3. **Active workspaces**: List of active workspaces on this machine, including the active mux backend when known 4. **Action picker**: Done or connect to a workspace When you connect to an existing workspace, hack uses that workspace's backend. When you create a new one from the SSH flow, hack uses the configured default backend (`sessions.mux`). ### Tailscale setup If Tailscale is stopped or not connected, `hack ssh` will prompt to start it: ``` Tailscale is stopped ? Turn on Tailscale? › yes Starting Tailscale... Tailscale connected! ``` ### Terminal size conflicts When multiple clients attach to the same tmux workspace, terminal size can get messed up. The session commands use `tmux attach -d` to detach other clients, avoiding this issue. If you're already in tmux and want to switch workspaces without detaching: ```bash # Inside tmux: prefix + s to open session switcher # Or use the tmux command: tmux switch-client -t ``` ## Configuration Project config: `.hack/hack.config.json` ```json { "sessions": { "mux": "auto" } } ``` Values: - `auto` (default): prefer tmux, fall back to zellij - `tmux`: require tmux - `zellij`: require zellij - `none`: disable sessions Env override: `HACK_SESSIONS_MUX=auto|tmux|zellij|none` Global default: ```bash hack config set --global sessions.mux zellij ``` Recommended onboarding: ```bash # Install the tmux popup binding that launches the picker hack setup tmux # Keep tmux as the guided default, but switch globally if your team prefers zellij hack config set --global sessions.mux zellij ``` ## Daemon sessions API > **Status: unsupported experimental.** This HTTP surface is served by the gateway, which the > codebase itself labels "the unsupported experimental gateway server." It is outside the > supported v3 product contract, hidden from default `hack --help` (see `hack help --all`), and > prints a warning when the underlying `hack remote`/`hack gateway`/`hack node`/`hack dispatch` > commands are invoked. `hackd` (the daemon) itself listens on a local unix socket for the CLI's own use (fast JSON status/ps, etc.) — it does not speak HTTP. The HTTP/WS surface described below, including the `127.0.0.1:7788` examples, is served by the separate **gateway** process and requires it to be explicitly enabled; it is not part of the daemon's normal listener. The gateway exposes REST endpoints for managing **tmux** workspaces programmatically. Session handlers shell out to `tmux` directly — there is no zellij code path in the gateway/daemon session routes, even though `sessions.mux` supports zellij for local `hack session` usage. This is useful for: - Remote workspace control via the gateway - Building automation tools - Agent orchestration When accessed over HTTP, this API is served by the **gateway** and requires authentication. See `docs/gateway-api.md` for token creation and the full security model. See the [Gateway API](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/docs/gateway-api.md) for authentication and endpoint details. ### Endpoints | Method | Path | Description | | --- | --- | --- | | GET | `/v1/sessions` | List all workspaces | | POST | `/v1/sessions` | Create a new workspace | | GET | `/v1/sessions/:id` | Get workspace details | | POST | `/v1/sessions/:id/stop` | Stop (kill) a workspace | | POST | `/v1/sessions/:id/exec` | Execute command in a workspace | | POST | `/v1/sessions/:id/input` | Send raw keystrokes | ### List workspaces ```bash curl -H "Authorization: Bearer $HACK_GATEWAY_TOKEN" \ http://127.0.0.1:7788/v1/sessions ``` Response: ```json { "sessions": [ { "name": "my-project", "attached": false, "path": "/Users/dev/my-project", "windows": 1, "createdAt": "2024-01-15T10:30:00.000Z" } ], "connection": { "tailscaleDnsName": "laptop.tail1234.ts.net", "tailscaleSshCommand": "ssh laptop.tail1234.ts.net", "tailscaleReady": true, "hostname": "laptop" } } ``` Session objects have no `backend` field — every session in this API is a tmux session. ### Create workspace ```bash curl -X POST http://127.0.0.1:7788/v1/sessions \ -H "Authorization: Bearer $HACK_GATEWAY_TOKEN" \ -H "Content-Type: application/json" \ -d '{"name": "agent-1", "cwd": "/path/to/project"}' ``` Request body: | Field | Type | Required | Description | | --- | --- | --- | --- | | `name` | string | yes | Workspace name (alphanumeric, dash, underscore) | | `cwd` | string | no | Working directory | Creation always uses tmux; there is no backend override. Response (201): ```json { "session": { "name": "agent-1", "attached": false, "path": "/path/to/project", "windows": 1, "createdAt": "2024-01-15T10:35:00.000Z" } } ``` ### Get workspace ```bash curl -H "Authorization: Bearer $HACK_GATEWAY_TOKEN" \ http://127.0.0.1:7788/v1/sessions/agent-1 ``` Response includes connection info for SSH access to the workspace: ```json { "session": { ... }, "connection": { "tailscaleDnsName": "laptop.tail1234.ts.net", "tailscaleSshCommand": "ssh laptop.tail1234.ts.net", "tailscaleReady": true, "hostname": "laptop" } } ``` ### Execute command ```bash curl -X POST http://127.0.0.1:7788/v1/sessions/agent-1/exec \ -H "Authorization: Bearer $HACK_GATEWAY_TOKEN" \ -H "Content-Type: application/json" \ -d '{"command": "bun test"}' ``` This sends the command followed by Enter to the session. Response: ```json { "status": "sent", "session": "agent-1" } ``` ### Send raw input ```bash curl -X POST http://127.0.0.1:7788/v1/sessions/agent-1/input \ -H "Authorization: Bearer $HACK_GATEWAY_TOKEN" \ -H "Content-Type: application/json" \ -d '{"keys": "C-c"}' ``` Send raw keystrokes without Enter. Useful for: - `C-c` (Ctrl+C) - `C-d` (Ctrl+D) - `Escape` - Arrow keys: `Up`, `Down`, `Left`, `Right` - `Tab` Note: - `keys` are passed directly to `tmux send-keys` — there is no zellij branch on this endpoint. Response: ```json { "status": "sent", "session": "agent-1" } ``` ### Stop workspace ```bash curl -X POST -H "Authorization: Bearer $HACK_GATEWAY_TOKEN" \ http://127.0.0.1:7788/v1/sessions/agent-1/stop ``` Response: ```json { "status": "stopped", "session": "agent-1" } ``` ### Error codes | Status | Error | Description | | --- | --- | --- | | 400 | `invalid_json` | Request body is not valid JSON | | 400 | `missing_name` | Workspace name not provided | | 400 | `invalid_name` | Workspace name contains invalid characters | | 400 | `missing_command` | Command not provided for exec | | 400 | `missing_keys` | Keys not provided for input | | 400 | `missing_session_id` | Session ID not in URL | | 404 | `session_not_found` | Session doesn't exist | | 409 | `session_exists` | Session already exists (on create) | | 500 | `create_failed` | Session create failed | | 500 | `stop_failed` | Session kill failed | | 500 | `exec_failed` | Session exec failed | | 500 | `input_failed` | Session input failed | ## Example: Remote agent workflow > **Status: unsupported experimental.** Like the Daemon sessions API above, this workflow depends > on the gateway, which is outside the supported v3 product contract and hidden behind > `hack help --all`. `gateway.example.com` below stands in for whatever tunnel/ingress you put in > front of the gateway yourself (Cloudflare, Tailscale, SSH port-forward) — hack does not provide > that ingress. 1. **Create a workspace from your remote client**: ```bash curl -X POST http://gateway.example.com/v1/sessions \ -H "Authorization: Bearer $TOKEN" \ -d '{"name": "agent-task-1", "cwd": "/home/dev/project"}' ``` 2. **Execute commands**: ```bash curl -X POST http://gateway.example.com/v1/sessions/agent-task-1/exec \ -H "Authorization: Bearer $TOKEN" \ -d '{"command": "git pull && bun install && bun test"}' ``` 3. **SSH in to check progress**: ```bash ssh laptop.tail1234.ts.net -t "hack session attach agent-task-1" ``` 4. **Clean up when done**: ```bash curl -X POST http://gateway.example.com/v1/sessions/agent-task-1/stop \ -H "Authorization: Bearer $TOKEN" ``` --- # Development runtime safety Hack's development defaults must preserve hot reload without manufacturing host-wide CPU, memory, or storage pressure. This guide records the runtime contract added after the 2026-07-30 OrbStack/Next investigation. ## Root cause and scope The generated Compose path used to inject both `CHOKIDAR_USEPOLLING=true` and `WATCHPACK_POLLING=true` into every discovered service. The injection was unconditional: Next and non-Next services, small repos and bind-mounted monorepos, and runtimes with working native file notifications all received the same polling policy. In the observed Apple Silicon workload, polling combined with an unnecessary `linux/amd64` override and multi-gigabyte persistent `.next` volumes. The result was sustained emulation/watcher CPU, very high cumulative writes, and a large set of stopped branch containers and cache volumes. The bounded comparison removed those project-level overrides without changing application code: the Next 16 development server ran as native arm64, hot reload remained available through native notifications, and idle container CPU settled near zero. A slow-filesystem warning remained for the `.next` volume, which identifies storage as a latency factor but does not justify forcing polling. Hack owns only two parts of that failure chain: 1. generated Compose defaults must not impose polling; 2. lifecycle targeting and optional cache cleanup must not silently abandon branch-owned resources. Image platform selection and application health-check cadence remain explicit project configuration. Hack does not rewrite them. ## File watching contract Generated services rely on the container runtime's native file notifications. Hack does not add Chokidar or Watchpack polling variables. A project can still set either variable on an individual service when a measured runtime requires it: ```yaml services: web: environment: CHOKIDAR_USEPOLLING: "true" WATCHPACK_POLLING: "750" ``` Keep polling service-scoped and measure CPU plus write activity after enabling it. Next's local development guidance notes that Docker filesystem access on macOS and Windows can be slower than host-local development; OrbStack likewise documents that bind mounts cross the macOS boundary while named volumes remain on the Linux side. Those storage tradeoffs are separate from watcher correctness. ## Branch rename contract An implicit `hack down` in a linked worktree uses Docker's Compose labels and exact `com.docker.compose.project.working_dir` evidence: - no owned runtime: use the current sanitized Git branch, preserving normal behavior; - exactly one owned runtime: target it, including when it is Created or stopped and the Git branch now has a different name; - multiple owned runtimes: fail before Compose mutation and require `--branch `; - explicit `--branch`: always target that branch without inference; - detached HEAD: continue to require an explicit branch; - primary checkout: continue to target the base instance by default. Canonical checkout paths prevent one worktree from stopping a sibling's runtime. ## Disposable cache cleanup contract Ordinary `hack down` preserves every named volume. `hack down --prune-caches` is a narrow, confirmation-gated addition for build caches. It removes only exact volume names observed on the target containers, then independently verifies the volume's Compose project and logical-volume labels. A named volume is eligible when every observed destination ends in `.next`, or when the top-level Compose volume explicitly declares `hack.cache.disposable: "true"`. The explicit label makes cleanup framework-agnostic without guessing whether destinations such as `.turbo`, `target`, `.gradle`, or a generic `cache` directory contain disposable output: ```yaml services: worker: volumes: - build-cache:/app/target volumes: build-cache: labels: hack.cache.disposable: "true" ``` Runtime inventory mount records now expose the Docker volume `name` separately from `source` (the engine storage path), so callers can inspect the same removal identity without guessing. The cleanup intentionally excludes: - bind mounts; - database, Redis, application-upload, and dependency volumes unless explicitly marked disposable; - external or unlabeled non-Next volumes; - volumes owned by another Compose project or checkout; - loose volume-name matches. Use `--yes` only after reviewing the same project-scoped evidence. Hack does not infer disposability from arbitrary volume names or mount paths because those signals cannot distinguish generated build output from durable application data. ## Doctor boundary This change does not add threshold-based doctor warnings for CPU, stopped-instance counts, volume size, or `linux/amd64` on arm64. Those signals can be legitimate and require image/platform or workload context that static configuration cannot prove. The generated-polling regression tests, branch-ownership resolution, and confirmation-gated cleanup are deterministic; policy guesses are left out of doctor until Hack can make them equally actionable. ## References - [Next.js local development](https://nextjs.org/docs/app/guides/local-development) - [Next.js Turbopack reference](https://nextjs.org/docs/app/api-reference/turbopack) - [OrbStack volumes and mounts](https://docs.orbstack.dev/docker/file-sharing) - [OrbStack efficiency](https://docs.orbstack.dev/efficiency) --- # Agent-first setup Let a coding agent (Claude Code, Codex) stand a project up under hack — or adopt an existing setup — instead of doing it by hand. One canonical onboarding prompt drives every entry point below; the content lives in the CLI, so it is always current for your installed version. ## Entry points (same prompt, four ways in) | You have | Use | | --- | --- | | A fresh repo + an agent CLI installed | `hack init --with claude\|codex\|both` | | An existing hack project | `hack agent onboard` (prints the prompt) | | An agent session with the hack skills installed | `/hack-init` | | A no-shell MCP client | the `hack-init` MCP prompt (`hack setup mcp`) | ## New repo: `hack init --with` ```bash cd /path/to/repo hack init --auto --with claude # or codex, or both ``` - Runs the normal init, then launches the agent CLI interactively with the full onboarding prompt (`claude ""` / `codex ""`). - If the agent CLI is not on PATH, the prompt is printed with copy-paste instructions instead. - If `.hack/` already exists, init is skipped and the handoff proceeds in existing-project mode. - With `--no-interactive` (or `HACK_NO_INTERACTIVE=1`, or no TTY) nothing is spawned — the prompt is always printed. ## Existing project: `hack agent onboard` ```bash hack agent onboard # prints the onboarding prompt for this project hack agent onboard | pbcopy # copy it for any agent session ``` The prompt picks up the project name and dev host from `.hack/hack.config.json` when present. ## Agent-side skill: `/hack-init` `hack setup claude` and `hack setup codex` install a thin `hack-init` skill (`.claude/skills/hack-init/SKILL.md` / `.codex/skills/hack-init/SKILL.md`). The skill tells the agent to run `hack agent onboard` (or fetch the `hack-init` MCP prompt) and follow it — the content stays in the CLI, so installed skills fetch guidance matching the installed CLI. ## What the prompt covers 1. Inventory — package manager, services, ports, backing services, and required variable names. Preserve the existing credential flow without copying secrets. 2. Setup — configure the requested container or host workflow, routing, and managed env injection. Verify replacements before removing any old env files. 3. Platform nuances — isolate Linux native dependencies from host installs when needed. Reuse existing tooling; add an ops container only when justified. 4. Running things — choose `hack run`, `hack exec`, or `hack host exec` for the target. 5. Verification — check expected long-running services, successful one-shot exits, actual routed URLs with normal TLS verification, and the requested host workflow. Preserve native trust approvals, ownership, and destructive-cleanup gates. Unrelated optional integration warnings do not block completion. ## Partial adoption (backing services only) Choose the shape that fits the requested workflow. Hack can run only the backing services — postgres, temporal, redis, and similar — while app dev servers (`bun dev`, `dotnet watch`, `vite`) stay on the host. **When to choose it:** - Heavy native toolchains (.NET, large native builds) develop faster on the host than in a container. - The hot-path dev server (the one you restart constantly) benefits from host-native file watching, debuggers, or hot reload that containers make slower or flakier. - The team already has a working host-based dev workflow and containerizing it is not worth the churn. **What hack still gives you in this shape:** - Stable hostnames and TLS for HTTP services and admin UIs via Caddy. Raw database protocols use their configured host ports or container-network addresses. - Branch instances for the containerized services (`--branch `), even though the host-run app processes are not branch-isolated on their own. - Managed environment configuration and secret injection. Commit only non-secret values; use the configured secret backend for credentials. - Lifecycle hooks (`startup`/`lifecycle` in `.hack/hack.config.json`) for host-side setup — tunnels, SSO bootstrap — that would otherwise be ad-hoc terminal steps. **How to wire it:** - Define only the backing services in `.hack/docker-compose.yml`; add Caddy labels where a stable hostname is useful (databases usually don't need one — connect by container port — but admin UIs, queues, or shared services often do). - Give host dev servers their connection info via `hack host exec --scope -- ` (injects the resolved env without touching `.env` files) without exposing secret values. - App URLs can stay on plain `localhost:` for the fast path, or get promoted to a routed compose service later if you want a stable `*.hack` hostname for them too — the two are not mutually exclusive and can be migrated incrementally. **Tradeoffs vs full containerization:** - No single `hack up` brings up the whole stack for a newcomer — they still need to start the host dev servers themselves (document that step). - Host-run app processes are not branch-isolated by hack; running two branches side by side means varying ports/env per worktree yourself. Partial adoption is a valid end state, not an incomplete migration — do not treat it as something to "finish" into full containerization unless the tradeoffs above actually bite. ## Copy-paste bootstrap Paste this into a fresh Claude Code / Codex session started at the repo root: ```text Set this repository up to run under the hack CLI. Run `hack agent onboard` (pass --no-interactive to hack commands) and follow the printed onboarding prompt for the requested scope. Preserve native approvals, existing credential flows, runtime ownership, and publishing gates. If the CLI is missing, report that blocker and continue independent setup work. Verify the chosen services and host workflows, and distinguish reachability from certificate trust. ``` --- # Local Helpers Hack no longer ships hosted or broker-backed integrations. What remains: - local env management and host/container injection - local sessions and runtime orchestration - optional coding-agent setup helpers: `hack init --with claude|codex|both`, `hack agent onboard` / `hack agent init` / `hack agent prime`, and scoped `hack setup` commands `hack setup sync` keeps interactive output compact: it summarizes each scope and only expands the path and reason for stale, missing, or failed artifacts. Exit status remains the automation contract, and the individual `hack setup cursor|claude|codex|agents|mcp --check` commands remain available when you need per-artifact detail. What does not ship: Hack Tickets, built-in GitHub or Linear integrations, hosted auth/account/org/team surfaces, and the web dashboard control plane. Recommended replacements: - GitHub: native `git` and `gh` - planning systems: keep them outside Hack and use the tracker selected by the project ## Agent integration freshness Hack maintains project instructions plus global Cursor, Claude, Codex, and shared `~/.ai/skills` surfaces. Generated guidance identifies the CLI version that rendered it. Run checks when Hack is relevant and there is evidence of drift; there is no mandatory startup audit. Plain `hack agent prime`, including installed SessionStart/PreCompact hooks, prints the current primer without scanning project or global integrations. Use `hack agent prime --check` for an explicit read-only inventory, or a targeted `hack setup ... --check` for per-artifact detail. Outside a Hack project, `hack agent prime --check` inventories global integrations only. Doctor classifies inventory commands as follow-up investigation and keeps scoped repair guidance separate. Inventory findings do not block unrelated work, and missing optional integrations need not be installed. Ordinary commands, `hack update`, and `hack doctor --fix` never modify these surfaces. Doctor may report freshness findings. Repair only the affected integration and scope covered by the request; `hack setup sync --all-scopes` remains available for an explicitly requested full refresh. Existing authorization for that action and scope is sufficient. After repair, read the updated guidance; restart only if the client cannot reload changed hooks or skills. ## Optional native plugins Hack also ships an optional native plugin for Codex, Claude Code, and Cursor in `plugins/hack`. It bundles the `hack-cli` and `hack-init` skills, the `hack mcp serve` server, Claude primer hooks, and a Cursor rule that the agent can select when relevant. Install the Hack CLI first and make `hack` available on the client's PATH. Choose either the native plugin or the existing standalone setup for each client. Installing a plugin does not migrate or remove existing rules, skills, hooks, or MCP configuration. If switching an existing installation, inspect the chosen client's project and user scopes, verify the plugin loads in a fresh session, then explicitly remove only duplicate Hack-owned entries in that scope. Preserve customized content. Do not use a broad sync or removal command as a migration step. If validation fails, disable the plugin and keep using the standalone integration. Codex: ```bash codex plugin marketplace add hack-dance/hack codex plugin add hack@hack-dance ``` Claude Code: ```bash claude plugin marketplace add hack-dance/hack --sparse .claude-plugin plugins/hack claude plugin install hack@hack-dance ``` Cursor: open Customize, find Hack in the configured marketplace, and choose the project or user installation scope. For local development, copy `plugins/hack` into `~/.cursor/plugins/local/hack` when that destination is unused, then reload Cursor and inspect the Hack plugin in Customize. Cursor 3.18.25 rejects symlinks to targets outside its local-plugin root; use a copy rather than weakening that boundary. See [Cursor's plugin documentation](https://cursor.com/docs/plugins) for marketplace and local development support in the installed client version. After installing, verify in a fresh session that both skills are discoverable, `hack mcp serve` can initialize, and the client's hooks or rule load. A successful marketplace registration alone does not prove those components loaded. The plugin's MCP fallback is for clients without shell access; use the Hack CLI when shell is available. Plugin updates are managed by the client. Ordinary Hack commands, `hack update`, `hack doctor --fix`, and primer hooks never install plugins or clean up integrations. A missing optional plugin is not a broken Hack installation. Model selection and global instruction, evolution, and writeback policy remain with the user's existing provider configuration; the Hack plugin adds only Hack-specific guidance. Contributors: change shared behavior in `src/agents/instruction-source.ts`, then run `bun run generate:agent-plugins`. The generation tests check bundled guidance against the canonical renderers. Release preparation regenerates all plugin content after the version bump and commits the complete bundle with the CLI release. --- # CLI Overview Hack is the local-first CLI surface. This page is a supported-surface overview with the running-things decision guide; for exhaustive per-command options and flags, see the generated [CLI reference](/docs/v4/reference/cli) (`bun run docs:cli-reference`, or `hack help ` in the terminal). ## Core commands - `hack init` — generate `.hack/` (compose + config); `--with claude|codex|both` also hands off to agent-assisted onboarding - `hack up` / `hack down` / `hack restart` - `hack open` — open/print the project URL - `hack logs` — tail logs (compose by default; Loki via `--loki`/`--query`) - `hack ps` / `hack status` — project status - `hack projects` — registry + running instances; `hack projects prune --project ` safely scopes stale registry/container cleanup to one project family (omit `--project` only for an intentional machine-wide prune) entries and stops orphaned containers - `hack env` — env values and local secrets - `hack host exec` / `hack host shell` — host commands/shells with Hack-resolved env injected - `hack run [cmd...]` — one-off command in a fresh service container - `hack exec -- ` — command in an already-running service container - `hack session` — persistent project workspaces (tmux-first) - `hack doctor` / `hack doctor --fix` — validate and repair local setup - `hack daemon` — optional local daemon for faster JSON status/ps - `hack agent onboard` — agent-assisted onboarding for existing projects - `hack setup` — install/refresh agent integrations (Cursor rules, Claude hooks, Codex skill, MCP) Interactive diagnostics use compact status rows: healthy groups stay on one line, while warnings and errors expand with wrapped detail and recovery guidance. `hack doctor --json` remains the stable, fully detailed automation surface. Generic macOS resolver setup is shown only when those resolver checks need attention. Run `hack help` for the full command list, or `hack help --all` to include hidden unsupported experimental commands. Every command and flag on this page is also in the generated [CLI reference](/docs/v4/reference/cli). Hosted auth/account/org/team, built-in GitHub and Linear workflows, and Hack Tickets are outside the CLI surface. Use native `git` and `gh` for repository collaboration. ## Unsupported experimental These commands remain source-available but are outside the supported v3 product contract. They are hidden from default `hack --help` (see `hack help --all`) and print a warning when invoked: - `hack remote` - `hack gateway` - `hack node` - `hack dispatch` See [Beta workflows](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/docs/beta.md) for guides on this surface. ## Agent/scripted ergonomics - `--json` on `hack up`/`down`/`restart`/`doctor` emits a `{ok, data | error: {code, message}}` envelope with stable `E_*` error codes. `--json` on `hack up` implies `--detach`. - `--no-interactive` (or `HACK_NO_INTERACTIVE=1`) is a global flag: commands never prompt — they apply documented defaults or fail fast with `E_INTERACTIVE_REQUIRED`. - `NO_COLOR` (or `HACK_NO_COLOR`) disables colored/decorated output. Generated agent docs, Cursor rules, Codex skills, and the shared `~/.ai/skills/hack-cli` skill carry the Hack CLI version that generated them. Plain `hack agent prime` prints current guidance without an integration scan. Use `hack agent prime --check` for an explicit project/global inventory or a targeted `hack setup ... --check` when diagnosing drift. Missing optional integrations do not require installation. Repair only affected targets within the authorized scope; use `hack setup sync --all-scopes` for an explicitly requested full refresh. Read updated guidance after repair; restart only if the client cannot reload changed hooks or skills. Ordinary commands, `hack update`, and `hack doctor --fix` never render, repair, remove, or otherwise mutate integration files. CLI upgrades do not trigger integration updates. ## First-run path ```bash hack global install hack init hack up --detach hack open ``` Agent-assisted alternative for a new repo: `hack init --with claude|codex|both`. For an existing project without `.hack/`, use `hack agent onboard`. See [Agent-first setup](/docs/v4/guides/agent-first-setup). ### Browser URL preference `hack open` keeps `dev_host` as the primary routing identity, but automatically opens the OAuth alias (for example, `myapp.hack.gy`) when `oauth.enabled` is true. Service shorthand and branch instances follow the same preference, so `hack open api --branch feature-x` resolves the branch-qualified alias URL. Set `open.prefer` in `.hack/hack.config.json` to `auto` (the default), `alias`, or `dev`. Override one invocation with `hack open --prefer `. Explicit URLs and fully qualified host targets are preserved. Selecting `alias` without an enabled OAuth alias fails with recovery guidance instead of silently opening the dev host. For a custom `dev_host` outside Hack's managed `.hack` namespace, `auto` keeps the development host because Hack does not synthesize a Caddy alias route for it. ## Running things (decision guide) - One-off command in a fresh service container (deps started as needed): `hack run `. - Command inside an already-running service container: `hack exec -- `. - Host script that needs hack-stored env: `hack host exec --env --scope -- ` — this is the way to run repo scripts; never read `.env` files directly. - Interactive host shell with injected env: `hack host shell --env --scope `. - Browser/host URL: use `hack open --json`; OAuth aliases are preferred when enabled. - Container-to-container traffic: use Compose DNS rather than routing back through Caddy. Service-scoped runtime changes do not run project-wide lifecycle hooks and do not start Compose dependencies implicitly, except declared shared-cache installers needed by the selected services: ```bash hack up api worker --env qa --detach hack restart api --env qa hack env apply --service api --env qa ``` Full detached startup and inspection are bounded. A timeout returns `E_STARTUP_TIMEOUT`, terminates the Compose process group, and leaves an explicit repair path instead of hanging indefinitely. `hack doctor --fix` starts exact project containers left in `Created`; it never removes those containers as part of this repair. ## Dependency bootstrap integrity Hack detects package-manager install services by their command or by the explicit `hack.dependencies.bootstrap=true` Compose label. Before such a service can mutate the runtime, Hack scans `.npmrc`, `.yarnrc.yml`, and `bunfig.toml` for `${VAR}` credential references and fails with `E_ENV_KEY_MISSING` when the selected Hack overlay cannot supply them. Values are never printed. To share dependency data only across worktrees with the same lockfile/runtime fingerprint, label the bootstrap service with a logical top-level Compose volume: ```yaml services: install-workspace: command: bun install --frozen-lockfile labels: hack.dependencies.bootstrap: "true" hack.dependencies.cache-volume: workspace-dependencies hack.dependencies.lockfiles: bun.lock,package.json hack.dependencies.runtime-files: .mise.toml volumes: - workspace-dependencies:/app/node_modules ``` Hack generates a content-addressed volume name from the declared inputs. Branch instances adopt an existing compatible volume automatically; a lockfile or runtime change selects a new volume. No service name such as `deps` is special. `hack run` resolves the same cache as `up` and `restart`. Before a scoped `up`, `restart`, or a consumer `run`, Hack executes each needed cache installer with the same Compose files and selected service environment, using `run --rm --no-deps`. Installers must be idempotent and coordinate concurrent writers (for example, a lock and a ready marker inside the volume). They run even for warm caches so an empty or interrupted cache cannot be mistaken for a ready one. No project lifecycle hook or unrelated dependency is started. A failed installer leaves existing consumer containers untouched; JSON lifecycle commands return `E_DEPENDENCY_BOOTSTRAP_FAILED`. Automatic initialization has a ten-minute process deadline. `hack exec` continues to use the existing container and its mounted cache until that container is explicitly recreated. ## Branch instances and linked worktrees `--branch ` on `hack up/down/restart/ps/logs/open/run/exec` targets a separate branch instance (compose project `--`, hostnames prefixed with the branch). In a linked git worktree, these commands default the branch instance to the sanitized current git branch when no `--branch` is passed (`worktree.auto_branch`), so two checkouts never fight over the same hostnames. A one-line notice is printed to stderr when the default kicks in, so captured stdout stays clean. Before `up` or `restart`, Hack also checks for a non-terminal instance previously started from the same worktree. If the worktree's current branch would auto-target a different Compose project, Hack prints a warning naming both the existing and new targets. Pass `--branch ` to make the target explicit. `hack down` applies a stricter ownership rule. When a linked worktree's Git branch was renamed and that exact checkout owns one differently named Compose runtime, implicit down targets the existing runtime instead of succeeding against an empty newly derived name. Running, Created, and stopped containers all count as ownership evidence. If the checkout owns multiple runtimes, implicit down fails and lists them; pass `--branch ` to select one. Exact checkout paths and Compose project families are required, so Hack never retargets to a sibling checkout. A detached linked worktree has no branch name to derive, so these commands fail instead of silently targeting the base instance. Pass `--branch ` to select an isolated instance, or set `worktree.auto_branch` to `false` only when intentionally opting into the base instance. Opt out: - pass `--branch ` explicitly (always wins), or - set `worktree.auto_branch` to `false` in `.hack/hack.config.json` to target the base instance. The primary checkout is unchanged: no `--branch` means the base instance. ### Disposable cache volumes Compose preserves named volumes on ordinary `down`, which is correct for application data but can leave branch-specific build caches behind. Use the explicit cleanup path when those caches are disposable: ```bash hack down --prune-caches # scripted: hack down --prune-caches --yes --json ``` Hack recognizes named volumes mounted only at `.next` destinations as disposable Next build caches. For any other framework, library, or language, mark the top-level Compose volume explicitly: ```yaml services: web: volumes: - turbo-cache:/app/.turbo volumes: turbo-cache: labels: hack.cache.disposable: "true" ``` The label applies to the exact volume, so the same contract works for Rust `target`, Gradle, Go, Python, or other generated caches without relying on names or destination guesses. Hack snapshots mounts before stopping the target and considers a volume removable only when all of these are true: - the container belongs to the exact targeted Compose project and checkout; - the mount type is a named volume; - `docker volume inspect` independently reports both the exact `com.docker.compose.project` label and a `com.docker.compose.volume` label; - every observed destination's final path segment is `.next`, or the volume itself has `hack.cache.disposable=true`. Interactive cleanup shows the exact volumes, services, and destinations and defaults to “no.” `--json` and other scripted use must add `--yes`; otherwise the command fails before down with `E_INTERACTIVE_REQUIRED`. Postgres, Redis, dependency, application-data, bind, external, unlabeled non-Next, and sibling-checkout volumes do not satisfy the removal contract unless a project author deliberately marks that exact Compose volume disposable. Hack deliberately does not run broad `docker volume prune` or `docker compose down -v`. ### Runtime host metadata Containers started by `hack up`, `hack restart`, and `hack run` receive the effective instance and public-route metadata. This keeps server-generated links, OAuth callbacks, webhooks, and other browser-facing URLs isolated when the same project runs in multiple worktrees. | Variable | Value | | --- | --- | | `HACK_BRANCH` | Effective branch slug, or an empty string for the base instance | | `HACK_COMPOSE_PROJECT` | Effective Compose project name | | `HACK_DEV_HOST` / `HACK_DEV_URL` | Effective root development host and HTTPS URL | | `HACK_ALIAS_HOST` / `HACK_ALIAS_URL` | Effective OAuth alias host and URL, when enabled and routed by Hack | | `HACK_SERVICE_NAME` | Current Compose service name | | `HACK_SERVICE_URL` | Current service's first public URL, when routable | | `HACK_SERVICE_URLS` | JSON array of every public URL for the current service | | `HACK_RUNTIME_METADATA` | Versioned JSON document containing the instance hosts and every routable service's URL list | Example `HACK_RUNTIME_METADATA` for a branch instance: ```json { "version": 1, "branch": "feature-x", "composeProject": "demo--feature-x", "hosts": { "dev": "feature-x.demo.hack", "alias": "feature-x.demo.hack.gy" }, "services": { "web": { "urls": ["https://feature-x.demo.hack"] }, "api": { "urls": ["https://api.feature-x.demo.hack"] } } } ``` The service map is derived from effective Caddy routes; unroutable services are omitted. Use Compose DNS names such as `http://api:3000` for container-to-container traffic and runtime metadata only when a public/browser-reachable URL is required. Explicit project env values retain precedence over generated metadata for backward compatibility. Existing containers receive the contract after their next `hack up` or `hack restart`; `hack exec` observes the values already stored in the running container. Hack materializes this contract in generated, machine-local Compose overrides. Do not edit or commit `.hack/.internal/compose.runtime.override.yml` or `.hack/.branch/compose..runtime.override.yml`; runtime commands refresh them and Hack's managed `.hack/.gitignore` covers them. Linked worktrees also inherit the project secret key automatically from the primary checkout through the shared git common dir, so you don't need to copy `.hack.secret.key` by hand. Set `HACK_ENV_SECRET_KEY` for CI or fully detached environments. `hack doctor` flags divergent secret keys and `dev_host` collisions across checkouts. ## Environment model Canonical env files: - `.hack/hack.env.default.yaml` - `.hack/hack.env..yaml` - `.hack/hack.env.local.yaml` (worktree-local override) - `.hack/hack.env..local.yaml` (worktree-local override) Use `hack env add`, `hack env unset`, `hack env list`, and `hack env materialize` to manage them. Use `hack host exec` and `hack host shell` when you want Hack-resolved env injected into host-side commands. Use `--local` on env mutations when you want to write to the worktree-local override file instead of the shared repo file. `hack env materialize` is only for compatibility output. `hack doctor` will tell you when the materialized `.hack/.env` or `.hack/.env.state.json` is stale and should be regenerated. ## Project files Hack owns a committed `.hack/.gitignore` (self-healing on `init`/`up`) that ignores machine-local generated files (`.internal/`, `.branch/`, `.env`, `.env.state.json`, `hack.env*.local.yaml`). The retired `tickets/` path remains ignored only so upgrades cannot recommit legacy machine-local caches. Keep `.hack/.gitignore` committed. If generated files ever leak into git, `hack doctor --fix` untracks them (the files stay on disk). Runtime metadata is written to `.internal/compose.runtime.override.yml` for the base instance and `.branch/compose..runtime.override.yml` for branch instances. See [Architecture](/docs/v4/architecture) for the full file map. The global config root defaults to `~/.hack`; override it with `HACK_HOME`. ## Lifecycle Use `.hack/hack.config.json` `lifecycle` or `startup` for host-side setup instead of ad-hoc terminal tabs. For fixed-port helpers such as AWS SSM tunnels or local proxies, declare `singleton.ports`. Use `onConflict: "adopt"` only when an existing full listener set is equivalent and should be reused. Adoption does not transfer process ownership: `hack down` leaves adopted external listeners running. See [Lifecycle](/docs/v4/lifecycle) for the full model. --- # hack CLI reference Run `hack help ` for the same content in the terminal. Global options: `--no-interactive` (or `HACK_NO_INTERACTIVE=1`); JSON shapes vary by command and backend. See [Command and output contracts](/docs/v4/reference/command-contracts) for envelopes, bare reports and streamed records. ## Project ## `hack project` Inspect or manage project metadata ### Usage ```bash hack project [options] ``` ### Subcommands | Command | Summary | | --- | --- | | `hack project owner` | Inspect project ownership | ### Options | Option | Description | | --- | --- | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack project owner` Inspect project ownership ### Usage ```bash hack project owner [options] ``` ### Subcommands | Command | Summary | | --- | --- | | `hack project owner show` | Show the local ownership metadata for the current project | ### Options | Option | Description | | --- | --- | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack init` Initialize a repo (generate .hack/ with compose + config) ### Usage ```bash hack init [options] ``` ### Options | Option | Description | | --- | --- | | `--path, -p ` | Run a project command against a repo path (overrides cwd search) | | `--manual` | Skip discovery and define services manually (or generate a minimal compose in --auto) | | `--auto` | Run non-interactive init with sensible defaults | | `--name ` | Project slug (default: repo name) | | `--dev-host ` | DEV_HOST override | | `--oauth` | Enable OAuth-safe alias host | | `--oauth-tld ` | OAuth alias TLD override (default: gy) | | `--no-discovery` | Skip discovery and generate a minimal compose | | `--with ` | After init, hand the onboarding prompt to an agent CLI (prints the prompt when the CLI is missing or the run is non-interactive) | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack up [services...]` Start project services (docker compose up) ### Usage ```bash hack up [services...] [options] ``` ### Arguments | Arg | Description | | --- | --- | | `services` | | ### Options | Option | Description | | --- | --- | | `--path, -p ` | Run a project command against a repo path (overrides cwd search) | | `--project ` | Target a registered project by name (from ~/.hack/projects.json) | | `--env ` | Apply an optional env overlay by name (use 'base' to bypass overlays) | | `--branch ` | Run against a branch-specific instance (compose name + hostnames) | | `--detach, -d` | Run in background (docker compose up -d) | | `--profile ` | Enable one or more compose profiles (comma-separated) | | `--target ` | Execution target routing (auto routes to remote when project execution mode requires it) | | `--json` | Output JSON (machine-readable) | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack down` Stop project services (docker compose down) ### Usage ```bash hack down [options] ``` ### Options | Option | Description | | --- | --- | | `--path, -p ` | Run a project command against a repo path (overrides cwd search) | | `--project ` | Target a registered project by name (from ~/.hack/projects.json) | | `--env ` | Apply an optional env overlay by name (use 'base' to bypass overlays) | | `--branch ` | Run against a branch-specific instance (compose name + hostnames) | | `--profile ` | Enable one or more compose profiles (comma-separated) | | `--target ` | Execution target routing (auto routes to remote when project execution mode requires it) | | `--prune-caches` | After down, remove confirmed Compose-owned disposable cache volumes | | `--yes` | Confirm --prune-caches without prompting | | `--json` | Output JSON (machine-readable) | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack restart [services...]` Restart the project or selected services ### Usage ```bash hack restart [services...] [options] ``` ### Arguments | Arg | Description | | --- | --- | | `services` | | ### Options | Option | Description | | --- | --- | | `--path, -p ` | Run a project command against a repo path (overrides cwd search) | | `--project ` | Target a registered project by name (from ~/.hack/projects.json) | | `--env ` | Apply an optional env overlay by name (use 'base' to bypass overlays) | | `--branch ` | Run against a branch-specific instance (compose name + hostnames) | | `--profile ` | Enable one or more compose profiles (comma-separated) | | `--target ` | Execution target routing (auto routes to remote when project execution mode requires it) | | `--json` | Output JSON (machine-readable) | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack ps` Show project status (docker compose ps) ### Usage ```bash hack ps [options] ``` ### Options | Option | Description | | --- | --- | | `--path, -p ` | Run a project command against a repo path (overrides cwd search) | | `--project ` | Target a registered project by name (from ~/.hack/projects.json) | | `--branch ` | Run against a branch-specific instance (compose name + hostnames) | | `--profile ` | Enable one or more compose profiles (comma-separated) | | `--json` | Output JSON (machine-readable) | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack tui` Open the project TUI (services + logs) ### Usage ```bash hack tui [options] ``` ### Options | Option | Description | | --- | --- | | `--path, -p ` | Run a project command against a repo path (overrides cwd search) | | `--project ` | Target a registered project by name (from ~/.hack/projects.json) | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack run [cmd...]` Run a one-off command in a service container (docker compose run --rm) ### Usage ```bash hack run [cmd...] [options] ``` ### Arguments | Arg | Description | | --- | --- | | `service` | | | `cmd` | | ### Options | Option | Description | | --- | --- | | `--path, -p ` | Run a project command against a repo path (overrides cwd search) | | `--project ` | Target a registered project by name (from ~/.hack/projects.json) | | `--env ` | Apply an optional env overlay by name (use 'base' to bypass overlays) | | `--branch ` | Run against a branch-specific instance (compose name + hostnames) | | `--workdir ` | Working directory inside the container (docker compose run -w) | | `--profile ` | Enable one or more compose profiles (comma-separated) | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack exec [cmd...]` Run a command in an already-running service container (docker compose exec) ### Usage ```bash hack exec [cmd...] [options] ``` ### Arguments | Arg | Description | | --- | --- | | `service` | | | `cmd` | | ### Options | Option | Description | | --- | --- | | `--path, -p ` | Run a project command against a repo path (overrides cwd search) | | `--project ` | Target a registered project by name (from ~/.hack/projects.json) | | `--env ` | Apply an optional env overlay by name (use 'base' to bypass overlays) | | `--branch ` | Run against a branch-specific instance (compose name + hostnames) | | `--workdir ` | Working directory inside the container (docker compose run -w) | | `--profile ` | Enable one or more compose profiles (comma-separated) | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack logs [service]` Tail logs (compose by default; Loki for queries/history via --loki/--query) ### Usage ```bash hack logs [service] [options] ``` ### Arguments | Arg | Description | | --- | --- | | `service` | | ### Options | Option | Description | | --- | --- | | `--path, -p ` | Run a project command against a repo path (overrides cwd search) | | `--project ` | Target a registered project by name (from ~/.hack/projects.json) | | `--branch ` | Run against a branch-specific instance (compose name + hostnames) | | `--follow, -f` | Follow logs (default for `hack logs`) | | `--no-follow` | Print logs and exit (do not follow) | | `--tail ` | Tail last N log lines (default: 200) | | `--pretty` | Pretty-print logs (best-effort JSON parsing + formatting) | | `--json` | Output JSON (machine-readable) | | `--profile ` | Enable one or more compose profiles (comma-separated) | | `--compose` | Read logs directly from docker compose (bypass Loki) | | `--loki` | Force Loki backend (do not fall back to docker compose logs) | | `--services ` | Filter Loki logs by service(s), comma-separated (e.g. api,www) | | `--query ` | Raw LogQL selector/query (overrides auto selector built from project + services) | | `--since ` | Start time for Loki logs (RFC3339 or duration like 15m) | | `--until ` | End time for Loki logs (RFC3339 or duration like 15m) | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack open [target]` Open a project URL (OAuth alias by default when enabled; otherwise dev host) ### Usage ```bash hack open [target] [options] ``` ### Arguments | Arg | Description | | --- | --- | | `target` | | ### Options | Option | Description | | --- | --- | | `--path, -p ` | Run a project command against a repo path (overrides cwd search) | | `--project ` | Target a registered project by name (from ~/.hack/projects.json) | | `--branch ` | Run against a branch-specific instance (compose name + hostnames) | | `--prefer ` | Browser host preference (auto uses the OAuth alias when enabled) | | `--json` | Output JSON (machine-readable) | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack branch` Manage branch aliases for a project ### Usage ```bash hack branch [options] ``` ### Subcommands | Command | Summary | | --- | --- | | `hack branch add ` | Register a branch alias for this project | | `hack branch list` | List registered branch aliases for this project | | `hack branch remove ` | Remove a branch alias for this project | | `hack branch open ` | Open the branch host in a browser | ### Options | Option | Description | | --- | --- | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack branch add ` Register a branch alias for this project ### Usage ```bash hack branch add [options] ``` ### Arguments | Arg | Description | | --- | --- | | `name` | | ### Options | Option | Description | | --- | --- | | `--path, -p ` | Run a project command against a repo path (overrides cwd search) | | `--project ` | Target a registered project by name (from ~/.hack/projects.json) | | `--note ` | Optional note for the branch entry | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack branch list` List registered branch aliases for this project ### Usage ```bash hack branch list [options] ``` ### Options | Option | Description | | --- | --- | | `--path, -p ` | Run a project command against a repo path (overrides cwd search) | | `--project ` | Target a registered project by name (from ~/.hack/projects.json) | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack branch remove ` Remove a branch alias for this project ### Usage ```bash hack branch remove [options] ``` ### Arguments | Arg | Description | | --- | --- | | `name` | | ### Options | Option | Description | | --- | --- | | `--path, -p ` | Run a project command against a repo path (overrides cwd search) | | `--project ` | Target a registered project by name (from ~/.hack/projects.json) | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack branch open ` Open the branch host in a browser ### Usage ```bash hack branch open [options] ``` ### Arguments | Arg | Description | | --- | --- | | `name` | | ### Options | Option | Description | | --- | --- | | `--path, -p ` | Run a project command against a repo path (overrides cwd search) | | `--project ` | Target a registered project by name (from ~/.hack/projects.json) | | `--prefer ` | Browser host preference (auto uses the OAuth alias when enabled) | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack config` Read/write hack.config.json values ### Usage ```bash hack config [options] ``` ### Subcommands | Command | Summary | | --- | --- | | `hack config get ` | Read a value from hack.config.json | | `hack config set ` | Update a value in hack.config.json | ### Options | Option | Description | | --- | --- | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack config get ` Read a value from hack.config.json ### Usage ```bash hack config get [options] ``` ### Arguments | Arg | Description | | --- | --- | | `key` | | ### Options | Option | Description | | --- | --- | | `--path, -p ` | Run a project command against a repo path (overrides cwd search) | | `--project ` | Target a registered project by name (from ~/.hack/projects.json) | | `--global` | Read/write global ~/.hack/hack.config.json | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack config set ` Update a value in hack.config.json ### Usage ```bash hack config set [options] ``` ### Arguments | Arg | Description | | --- | --- | | `key` | | | `value` | | ### Options | Option | Description | | --- | --- | | `--path, -p ` | Run a project command against a repo path (overrides cwd search) | | `--project ` | Target a registered project by name (from ~/.hack/projects.json) | | `--global` | Read/write global ~/.hack/hack.config.json | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack session` Manage persistent project workspaces with tmux-first onboarding ### Usage ```bash hack session [options] ``` Sessions keep a project workspace alive across terminal restarts, SSH reconnects, and long-running agent work. The guided default is tmux, including `hack setup tmux` for a popup picker. Other mux backends such as zellij still exist through `sessions.mux`, but the interactive session tooling is tmux-first today. ### Subcommands | Command | Summary | | --- | --- | | `hack session list` | List active workspaces | | `hack session start [project]` | Reuse the default project workspace or create an isolated one | | `hack session stop ` | Stop a workspace | | `hack session attach ` | Attach to an existing workspace | | `hack session exec ` | Send a command to a running workspace | | `hack session panes ` | List panes in a tmux workspace | | `hack session capture ` | Capture recent output from a tmux workspace | | `hack session tail ` | Tail output from a tmux workspace | ### Options | Option | Description | | --- | --- | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack session list` List active workspaces ### Usage ```bash hack session list [options] ``` ### Options | Option | Description | | --- | --- | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack session start [project]` Reuse the default project workspace or create an isolated one ### Usage ```bash hack session start [project] [options] ``` Reuse the default project workspace when it already exists, or create an isolated long-running workspace with --new or --name. Use --detach when another tool should keep the workspace alive without attaching your terminal. ### Arguments | Arg | Description | | --- | --- | | `project` | Project name or path | ### Options | Option | Description | | --- | --- | | `--up` | Run hack up -d before creating or attaching | | `--new` | Create an isolated workspace instead of reusing the default project workspace | | `--name ` | Suffix for an isolated workspace name (for example: agent-1 -> project--agent-1) | | `--detach, -d` | Create or reuse the workspace without attaching (for GUI/non-TTY use) | | `--env ` | Apply an optional env overlay by name (use 'base' to bypass overlays) | | `--service ` | Inject env for the selected scope (global or a service name) | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack session stop ` Stop a workspace ### Usage ```bash hack session stop [options] ``` ### Arguments | Arg | Description | | --- | --- | | `workspace` | Workspace name | ### Options | Option | Description | | --- | --- | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack session attach ` Attach to an existing workspace ### Usage ```bash hack session attach [options] ``` Attach to a running workspace by name. Tmux switches clients instead of nesting tmux inside tmux, while zellij attaches to the named session directly. ### Arguments | Arg | Description | | --- | --- | | `workspace` | Workspace name | ### Options | Option | Description | | --- | --- | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack session exec ` Send a command to a running workspace ### Usage ```bash hack session exec [options] ``` Queue a command in the workspace without opening a new interactive attach flow. Tmux sends it to the active pane; zellij opens a new pane for the command. This is useful for long-running agents, background checks, or remote follow-up work. ### Arguments | Arg | Description | | --- | --- | | `workspace` | Workspace name | | `command` | Command to execute in workspace | ### Options | Option | Description | | --- | --- | | `--env ` | Apply an optional env overlay by name (use 'base' to bypass overlays) | | `--service ` | Inject env for the selected scope (global or a service name) | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack session panes ` List panes in a tmux workspace ### Usage ```bash hack session panes [options] ``` ### Arguments | Arg | Description | | --- | --- | | `workspace` | Workspace name | ### Options | Option | Description | | --- | --- | | `--json` | Output JSON (machine-readable) | | `--pretty` | Pretty-print logs (best-effort JSON parsing + formatting) | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack session capture ` Capture recent output from a tmux workspace ### Usage ```bash hack session capture [options] ``` ### Arguments | Arg | Description | | --- | --- | | `workspace` | Workspace name | ### Options | Option | Description | | --- | --- | | `--target ` | Tmux pane target (default: active pane) | | `--lines ` | Number of lines to capture (default: 200) | | `--json` | Output JSON (machine-readable) | | `--pretty` | Pretty-print logs (best-effort JSON parsing + formatting) | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack session tail ` Tail output from a tmux workspace ### Usage ```bash hack session tail [options] ``` ### Arguments | Arg | Description | | --- | --- | | `workspace` | Workspace name | ### Options | Option | Description | | --- | --- | | `--target ` | Tmux pane target (default: active pane) | | `--lines ` | Number of lines to capture (default: 200) | | `--interval-ms ` | Polling interval in milliseconds (default: 500) | | `--max-ms ` | Stop tailing after N milliseconds (default: 5000) | | `--json` | Output JSON (machine-readable) | | `--pretty` | Pretty-print logs (best-effort JSON parsing + formatting) | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## Global infrastructure ## `hack global` Manage machine-wide infra (DNS/TLS, Caddy proxy, logs) ### Usage ```bash hack global [options] ``` ### Subcommands | Command | Summary | | --- | --- | | `hack global install` | Bootstrap ~/.hack and start Caddy + Grafana/Loki/Alloy | | `hack global up` | Start global infra containers | | `hack global down` | Stop global infra containers | | `hack global status` | Show status for global infra (containers + networks) | | `hack global logs [service]` | Tail global infra logs (caddy\|grafana\|loki\|alloy) | | `hack global ca` | Export Caddy Local CA cert (print path or PEM) | | `hack global cert ` | Generate local TLS certs via mkcert (for non-Caddy services) | | `hack global trust` | Trust Caddy Local CA (macOS) so https://*.hack is trusted | | `hack global logs-reset` | Wipe Loki/Grafana volumes (fresh logs + dashboards) | | `hack global authorize` | Authorize passwordless DNS recovery commands on macOS | ### Options | Option | Description | | --- | --- | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack global install` Bootstrap ~/.hack and start Caddy + Grafana/Loki/Alloy ### Usage ```bash hack global install [options] ``` ### Options | Option | Description | | --- | --- | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack global up` Start global infra containers ### Usage ```bash hack global up [options] ``` ### Options | Option | Description | | --- | --- | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack global down` Stop global infra containers ### Usage ```bash hack global down [options] ``` ### Options | Option | Description | | --- | --- | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack global status` Show status for global infra (containers + networks) ### Usage ```bash hack global status [options] ``` ### Options | Option | Description | | --- | --- | | `--json` | Output JSON (machine-readable) | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack global logs [service]` Tail global infra logs (caddy\|grafana\|loki\|alloy) ### Usage ```bash hack global logs [service] [options] ``` ### Arguments | Arg | Description | | --- | --- | | `service` | | ### Options | Option | Description | | --- | --- | | `--follow, -f` | Follow logs (default for `hack logs`) | | `--no-follow` | Print logs and exit (do not follow) | | `--tail ` | Tail last N log lines (default: 200) | | `--pretty` | Pretty-print logs (best-effort JSON parsing + formatting) | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack global ca` Export Caddy Local CA cert (print path or PEM) ### Usage ```bash hack global ca [options] ``` ### Options | Option | Description | | --- | --- | | `--print` | Print the CA cert PEM to stdout (instead of printing its path) | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack global cert ` Generate local TLS certs via mkcert (for non-Caddy services) ### Usage ```bash hack global cert [options] ``` Uses mkcert to generate a cert/key pair under ~/.hack/certs (or --out). ### Arguments | Arg | Description | | --- | --- | | `hosts` | | ### Options | Option | Description | | --- | --- | | `--install` | Run mkcert -install before generating certs | | `--out ` | Directory for generated cert/key (default: ~/.hack/certs) | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack global trust` Trust Caddy Local CA (macOS) so https://*.hack is trusted ### Usage ```bash hack global trust [options] ``` ### Options | Option | Description | | --- | --- | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack global logs-reset` Wipe Loki/Grafana volumes (fresh logs + dashboards) ### Usage ```bash hack global logs-reset [options] ``` ### Options | Option | Description | | --- | --- | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack global authorize` Authorize passwordless DNS recovery commands on macOS ### Usage ```bash hack global authorize [options] ``` ### Options | Option | Description | | --- | --- | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack status` Show project status (shortcut for `hack projects --details`) ### Usage ```bash hack status [options] ``` ### Options | Option | Description | | --- | --- | | `--project ` | Target a registered project by name (from ~/.hack/projects.json) | | `--include-global` | Include global infra projects under ~/.hack (e.g. logging stack) | | `--all` | Include unregistered docker compose projects (best-effort) | | `--meta` | Include git/worktree/session/env metadata (implies --details) | | `--json` | Output JSON (machine-readable) | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack usage` Show resource usage across running projects ### Usage ```bash hack usage [options] ``` ### Options | Option | Description | | --- | --- | | `--project ` | Target a registered project by name (from ~/.hack/projects.json) | | `--details` | Show per-container usage and mount types | | `--include-global` | Include global infra projects under ~/.hack (e.g. logging stack) | | `--watch` | Refresh usage continuously | | `--interval ` | Refresh interval (ms) for --watch | | `--no-host` | Skip host process metrics | | `--json` | Output JSON (machine-readable) | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack projects` Show all projects (registry + running docker compose) ### Usage ```bash hack projects [options] ``` ### Subcommands | Command | Summary | | --- | --- | | `hack projects prune` | Remove stale registry entries and stop orphaned containers | ### Options | Option | Description | | --- | --- | | `--project ` | Target a registered project by name (from ~/.hack/projects.json) | | `--details` | Show per-project service tables | | `--summary` | Return compact project counts with --json; load details with --project | | `--timings` | Write numeric listing phase timings to stderr (requires --json) | | `--no-daemon` | Read runtime directly instead of the daemon cache | | `--meta` | Include git/worktree/session/env metadata (implies --details) | | `--include-global` | Include global infra projects under ~/.hack (e.g. logging stack) | | `--all` | Include unregistered docker compose projects (best-effort) | | `--json` | Output JSON (machine-readable) | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack projects prune` Remove stale registry entries and stop orphaned containers ### Usage ```bash hack projects prune [options] ``` ### Options | Option | Description | | --- | --- | | `--project ` | Target a registered project by name (from ~/.hack/projects.json) | | `--include-global` | Include global infra projects under ~/.hack (e.g. logging stack) | | `--dry-run` | Report prune candidates without changing registry entries or containers | | `--json` | Output JSON (machine-readable) | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## Diagnostics ## `hack log-pipe` Read log lines from stdin and pretty-print them (best-effort JSON parsing) ### Usage ```bash hack log-pipe [options] ``` ### Options | Option | Description | | --- | --- | | `--format ` | How to parse incoming lines from stdin (default: auto) | | `--stream ` | Treat stdin as stdout or stderr (stderr forces ERROR level + writes to stderr) (default: stdout) | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack doctor` Validate local setup (docker, networks, DNS, global infra, project config) ### Usage ```bash hack doctor [options] ``` ### Options | Option | Description | | --- | --- | | `--path, -p ` | Run a project command against a repo path (overrides cwd search) | | `--fix` | Attempt safe auto-remediations (network + CoreDNS + CA) | | `--migrate-env-config` | Migrate legacy hack.env.json/.env state to the new env config files | | `--json` | Output JSON (machine-readable) | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack crash-capture` Capture OrbStack/system/docker diagnostics into .tmp for post-failure triage ### Usage ```bash hack crash-capture [options] ``` Collects structured snapshots after a runtime failure: hack status/logs, docker state, OrbStack process details, and filtered macOS unified logs. ### Options | Option | Description | | --- | --- | | `--path, -p ` | Run a project command against a repo path (overrides cwd search) | | `--since ` | Look-back window for system logs (for example: 30m, 2h) | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack daemon` Manage the local hack daemon (hackd) ### Usage ```bash hack daemon [options] ``` ### Subcommands | Command | Summary | | --- | --- | | `hack daemon start` | Start hackd (local daemon) | | `hack daemon stop` | Stop hackd | | `hack daemon restart` | Restart hackd | | `hack daemon status` | Show hackd status | | `hack daemon metrics` | Show hackd metrics | | `hack daemon logs` | Show hackd logs | | `hack daemon clear` | Clear stale hackd pid/socket files | | `hack daemon install` | Install hackd as a launchd service (macOS) | | `hack daemon uninstall` | Uninstall hackd launchd service (macOS) | ### Options | Option | Description | | --- | --- | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack daemon start` Start hackd (local daemon) ### Usage ```bash hack daemon start [options] ``` ### Options | Option | Description | | --- | --- | | `--foreground` | Run hackd in the foreground (debug) | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack daemon stop` Stop hackd ### Usage ```bash hack daemon stop [options] ``` ### Options | Option | Description | | --- | --- | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack daemon restart` Restart hackd ### Usage ```bash hack daemon restart [options] ``` ### Options | Option | Description | | --- | --- | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack daemon status` Show hackd status ### Usage ```bash hack daemon status [options] ``` ### Options | Option | Description | | --- | --- | | `--json` | Output JSON (machine-readable) | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack daemon metrics` Show hackd metrics ### Usage ```bash hack daemon metrics [options] ``` ### Options | Option | Description | | --- | --- | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack daemon logs` Show hackd logs ### Usage ```bash hack daemon logs [options] ``` ### Options | Option | Description | | --- | --- | | `--tail ` | Tail last N log lines (default: 200) | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack daemon clear` Clear stale hackd pid/socket files ### Usage ```bash hack daemon clear [options] ``` ### Options | Option | Description | | --- | --- | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack daemon install` Install hackd as a launchd service (macOS) ### Usage ```bash hack daemon install [options] ``` ### Options | Option | Description | | --- | --- | | `--run-at-load` | Start hackd automatically on login | | `--no-run-at-load` | Do not start hackd automatically on login | | `--gui-only` | Only run in GUI sessions (default) | | `--no-gui-only` | Run in all session types (including SSH) | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack daemon uninstall` Uninstall hackd launchd service (macOS) ### Usage ```bash hack daemon uninstall [options] ``` ### Options | Option | Description | | --- | --- | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack update` Update hack to the latest release ### Usage ```bash hack update [options] ``` Downloads and installs the latest stable hack release from GitHub. Notes: - Refuses to self-update when running from a Homebrew install, local dev wrapper, or symlink install. - Updates the current hack binary and refreshes assets. ### Options | Option | Description | | --- | --- | | `--check` | Check for updates (do not install) | | `--yes` | Apply update without prompting | | `--tag ` | Update to a specific release tag (e.g. v1.4.0) | | `--json` | Output JSON (machine-readable) | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack version` Print version ### Usage ```bash hack version [options] ``` ### Options | Option | Description | | --- | --- | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack help [path...]` Show help for a command (e.g. hack help global logs) ### Usage ```bash hack help [path...] [options] ``` ### Arguments | Arg | Description | | --- | --- | | `path` | | ### Options | Option | Description | | --- | --- | | `--all` | Include experimental (unsupported) commands in help output | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## Agents ## `hack mcp` Manage MCP server integrations for coding agents ### Usage ```bash hack mcp [options] ``` ### Subcommands | Command | Summary | | --- | --- | | `hack mcp serve` | Run the MCP server over stdio | | `hack mcp install` | Install MCP config for supported clients | | `hack mcp print` | Print MCP config snippets | ### Options | Option | Description | | --- | --- | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack mcp serve` Run the MCP server over stdio ### Usage ```bash hack mcp serve [options] ``` ### Options | Option | Description | | --- | --- | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack mcp install` Install MCP config for supported clients ### Usage ```bash hack mcp install [options] ``` ### Options | Option | Description | | --- | --- | | `--scope ` | Write MCP config to user or project scope (default: user) | | `--path, -p ` | Run a project command against a repo path (overrides cwd search) | | `--all` | Target all supported clients | | `--cursor` | Target Cursor MCP config | | `--claude` | Target Claude CLI MCP config | | `--codex` | Target Codex MCP config | | `--docs` | Update AGENTS.md and CLAUDE.md with hack usage | | `--agents-md` | Update AGENTS.md with hack usage | | `--claude-md` | Update CLAUDE.md with hack usage | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack mcp print` Print MCP config snippets ### Usage ```bash hack mcp print [options] ``` ### Options | Option | Description | | --- | --- | | `--scope ` | Write MCP config to user or project scope (default: user) | | `--path, -p ` | Run a project command against a repo path (overrides cwd search) | | `--all` | Target all supported clients | | `--cursor` | Target Cursor MCP config | | `--claude` | Target Claude CLI MCP config | | `--codex` | Target Codex MCP config | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack setup` Install integrations for coding agents ### Usage ```bash hack setup [options] ``` ### Subcommands | Command | Summary | | --- | --- | | `hack setup tmux` | Install the recommended tmux binding for hack workspaces | | `hack setup cursor` | Install Cursor rules for hack CLI usage | | `hack setup claude` | Install Claude Code hooks for hack CLI usage | | `hack setup codex` | Install Codex skill for hack CLI usage | | `hack setup agents` | Install AGENTS.md / CLAUDE.md snippets for hack CLI usage | | `hack setup sync` | Refresh project/global agent guidance | | `hack setup mcp` | Install MCP configs for hack CLI usage (no-shell only) | ### Options | Option | Description | | --- | --- | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack setup tmux` Install the recommended tmux binding for hack workspaces ### Usage ```bash hack setup tmux [options] ``` ### Options | Option | Description | | --- | --- | | `--check` | Check whether integration is installed | | `--remove` | Remove integration files/config | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack setup cursor` Install Cursor rules for hack CLI usage ### Usage ```bash hack setup cursor [options] ``` ### Options | Option | Description | | --- | --- | | `--path, -p ` | Run a project command against a repo path (overrides cwd search) | | `--global` | Use global (user) scope instead of project scope | | `--check` | Check whether integration is installed | | `--remove` | Remove integration files/config | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack setup claude` Install Claude Code hooks for hack CLI usage ### Usage ```bash hack setup claude [options] ``` ### Options | Option | Description | | --- | --- | | `--path, -p ` | Run a project command against a repo path (overrides cwd search) | | `--global` | Use global (user) scope instead of project scope | | `--check` | Check whether integration is installed | | `--remove` | Remove integration files/config | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack setup codex` Install Codex skill for hack CLI usage ### Usage ```bash hack setup codex [options] ``` ### Options | Option | Description | | --- | --- | | `--path, -p ` | Run a project command against a repo path (overrides cwd search) | | `--global` | Use global (user) scope instead of project scope | | `--check` | Check whether integration is installed | | `--remove` | Remove integration files/config | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack setup agents` Install AGENTS.md / CLAUDE.md snippets for hack CLI usage ### Usage ```bash hack setup agents [options] ``` ### Options | Option | Description | | --- | --- | | `--path, -p ` | Run a project command against a repo path (overrides cwd search) | | `--all` | Target all supported clients | | `--agents-md` | Target AGENTS.md | | `--claude-md` | Target CLAUDE.md | | `--check` | Check whether integration is installed | | `--remove` | Remove integration files/config | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack setup sync` Refresh project/global agent guidance ### Usage ```bash hack setup sync [options] ``` ### Options | Option | Description | | --- | --- | | `--path, -p ` | Run a project command against a repo path (overrides cwd search) | | `--global` | Use global (user) scope instead of project scope | | `--all-scopes` | Target both project and global (user) scopes | | `--check` | Check whether integration is installed | | `--remove` | Remove integration files/config | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack setup mcp` Install MCP configs for hack CLI usage (no-shell only) ### Usage ```bash hack setup mcp [options] ``` ### Options | Option | Description | | --- | --- | | `--path, -p ` | Run a project command against a repo path (overrides cwd search) | | `--global` | Use global (user) scope instead of project scope | | `--all` | Target all supported clients | | `--cursor` | Target Cursor integration | | `--claude` | Target Claude integration | | `--codex` | Target Codex integration | | `--check` | Check whether integration is installed | | `--remove` | Remove integration files/config | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack agent` Agent utilities ### Usage ```bash hack agent [options] ``` ### Subcommands | Command | Summary | | --- | --- | | `hack agent prime` | Print agent primer text | | `hack agent patterns` | Print agent init patterns guide | | `hack agent init` | Print agent init prompt | | `hack agent onboard` | Print the project onboarding prompt (agent-assisted setup) | ### Options | Option | Description | | --- | --- | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack agent prime` Print agent primer text ### Usage ```bash hack agent prime [options] ``` ### Options | Option | Description | | --- | --- | | `--check` | Include a read-only project and global integration inventory | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack agent patterns` Print agent init patterns guide ### Usage ```bash hack agent patterns [options] ``` ### Options | Option | Description | | --- | --- | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack agent init` Print agent init prompt ### Usage ```bash hack agent init [options] ``` ### Options | Option | Description | | --- | --- | | `--path, -p ` | Run a project command against a repo path (overrides cwd search) | | `--client, -c ` | Open init prompt in an agent client (or print) | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack agent onboard` Print the project onboarding prompt (agent-assisted setup) ### Usage ```bash hack agent onboard [options] ``` ### Options | Option | Description | | --- | --- | | `--path, -p ` | Run a project command against a repo path (overrides cwd search) | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## Secrets & env ## `hack secrets` Manage secrets in OS keychain (Bun.secrets) ### Usage ```bash hack secrets [options] ``` ### Subcommands | Command | Summary | | --- | --- | | `hack secrets set [name]` | Store a secret | | `hack secrets get [name]` | Print a secret (exit 1 if missing) | | `hack secrets delete [name]` | Delete a stored secret | ### Options | Option | Description | | --- | --- | | `--service ` | Override Bun.secrets service name (default: hack-cli) | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack secrets set [name]` Store a secret ### Usage ```bash hack secrets set [name] [options] ``` ### Arguments | Arg | Description | | --- | --- | | `name` | | ### Options | Option | Description | | --- | --- | | `--service ` | Override Bun.secrets service name (default: hack-cli) | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack secrets get [name]` Print a secret (exit 1 if missing) ### Usage ```bash hack secrets get [name] [options] ``` ### Arguments | Arg | Description | | --- | --- | | `name` | | ### Options | Option | Description | | --- | --- | | `--service ` | Override Bun.secrets service name (default: hack-cli) | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack secrets delete [name]` Delete a stored secret ### Usage ```bash hack secrets delete [name] [options] ``` ### Arguments | Arg | Description | | --- | --- | | `name` | | ### Options | Option | Description | | --- | --- | | `--service ` | Override Bun.secrets service name (default: hack-cli) | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## Integrations ## `hack env` Set project env vars and local secrets ### Usage ```bash hack env [options] ``` ### Subcommands | Command | Summary | | --- | --- | | `hack env list` | List resolved env values for the selected overlay | | `hack env explain ` | Explain a resolved env value without revealing it | | `hack env apply` | Recreate one service with its resolved env | | `hack env add [key] [value]` | Add or update an env value | | `hack env set [key] [value]` | Alias for env add | | `hack env materialize` | Write a compatibility .env file from the selected overlay | | `hack env exec [command...]` | Run a host command with project env injected | | `hack env shell` | Open a host shell with project env injected | | `hack env unset [key]` | Remove an env value from the canonical config | | `hack env backend` | Manage env/secret storage backend strategy | ### Options | Option | Description | | --- | --- | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack env list` List resolved env values for the selected overlay ### Usage ```bash hack env list [options] ``` ### Options | Option | Description | | --- | --- | | `--path, -p ` | Run a project command against a repo path (overrides cwd search) | | `--project ` | Target a registered project by name (from ~/.hack/projects.json) | | `--env ` | Apply an optional env overlay by name (use 'base' to bypass overlays) | | `--json` | Output JSON (machine-readable) | | `--show-secrets` | Print secret values (keychain) in plaintext | | `--service ` | Target scope (global or a discovered service name) | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack env explain ` Explain a resolved env value without revealing it ### Usage ```bash hack env explain [options] ``` ### Arguments | Arg | Description | | --- | --- | | `key` | | ### Options | Option | Description | | --- | --- | | `--path, -p ` | Run a project command against a repo path (overrides cwd search) | | `--project ` | Target a registered project by name (from ~/.hack/projects.json) | | `--env ` | Apply an optional env overlay by name (use 'base' to bypass overlays) | | `--json` | Output JSON (machine-readable) | | `--service ` | Target scope (global or a discovered service name) | | `--target ` | Env view for host commands (default: host rewrites container-oriented addresses for local host execution) | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack env apply` Recreate one service with its resolved env ### Usage ```bash hack env apply [options] ``` ### Options | Option | Description | | --- | --- | | `--path, -p ` | Run a project command against a repo path (overrides cwd search) | | `--project ` | Target a registered project by name (from ~/.hack/projects.json) | | `--env ` | Apply an optional env overlay by name (use 'base' to bypass overlays) | | `--json` | Output JSON (machine-readable) | | `--service ` | Target scope (global or a discovered service name) | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack env add [key] [value]` Add or update an env value ### Usage ```bash hack env add [key] [value] [options] ``` ### Arguments | Arg | Description | | --- | --- | | `key` | | | `value` | | ### Options | Option | Description | | --- | --- | | `--path, -p ` | Run a project command against a repo path (overrides cwd search) | | `--project ` | Target a registered project by name (from ~/.hack/projects.json) | | `--env ` | Apply an optional env overlay by name (use 'base' to bypass overlays) | | `--secret` | Store value as an encrypted secure entry | | `--local` | Write to the worktree-local env override file instead of the shared repo env file | | `--service ` | Target scope (global or a discovered service name) | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack env set [key] [value]` Alias for env add ### Usage ```bash hack env set [key] [value] [options] ``` ### Arguments | Arg | Description | | --- | --- | | `key` | | | `value` | | ### Options | Option | Description | | --- | --- | | `--path, -p ` | Run a project command against a repo path (overrides cwd search) | | `--project ` | Target a registered project by name (from ~/.hack/projects.json) | | `--env ` | Apply an optional env overlay by name (use 'base' to bypass overlays) | | `--secret` | Store value as an encrypted secure entry | | `--local` | Write to the worktree-local env override file instead of the shared repo env file | | `--service ` | Target scope (global or a discovered service name) | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack env materialize` Write a compatibility .env file from the selected overlay ### Usage ```bash hack env materialize [options] ``` ### Options | Option | Description | | --- | --- | | `--path, -p ` | Run a project command against a repo path (overrides cwd search) | | `--project ` | Target a registered project by name (from ~/.hack/projects.json) | | `--env ` | Apply an optional env overlay by name (use 'base' to bypass overlays) | | `--service ` | Target scope (global or a discovered service name) | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack env exec [command...]` Run a host command with project env injected ### Usage ```bash hack env exec [command...] [options] ``` Inject the selected Hack env overlay directly into a one-off host command without materializing .hack/.env. To inspect a value, prefer `printenv KEY` or `sh -lc 'printf "%s\n" "$KEY"'`; `echo $KEY` expands in your current shell before Hack injects env. ### Arguments | Arg | Description | | --- | --- | | `command` | | ### Options | Option | Description | | --- | --- | | `--path, -p ` | Run a project command against a repo path (overrides cwd search) | | `--project ` | Target a registered project by name (from ~/.hack/projects.json) | | `--env ` | Apply an optional env overlay by name (use 'base' to bypass overlays) | | `--service ` | Target scope (global or a discovered service name) | | `--target ` | Env view for host commands (default: host rewrites container-oriented addresses for local host execution) | | `--shell ` | Run a shell command string via /bin/sh -lc after env injection so `$VAR` expansion happens inside the child shell | | `--timeout ` | Bound a non-TTY host command; terminate its process group and return 124 on expiry | | `--lifetime ` | Declare intended lifetime for diagnostics (default: command; does not detach) | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack env shell` Open a host shell with project env injected ### Usage ```bash hack env shell [options] ``` Start an interactive host shell with the selected Hack env overlay injected into the process environment. ### Options | Option | Description | | --- | --- | | `--path, -p ` | Run a project command against a repo path (overrides cwd search) | | `--project ` | Target a registered project by name (from ~/.hack/projects.json) | | `--env ` | Apply an optional env overlay by name (use 'base' to bypass overlays) | | `--service ` | Target scope (global or a discovered service name) | | `--target ` | Env view for host commands (default: host rewrites container-oriented addresses for local host execution) | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack env unset [key]` Remove an env value from the canonical config ### Usage ```bash hack env unset [key] [options] ``` ### Arguments | Arg | Description | | --- | --- | | `key` | | ### Options | Option | Description | | --- | --- | | `--path, -p ` | Run a project command against a repo path (overrides cwd search) | | `--project ` | Target a registered project by name (from ~/.hack/projects.json) | | `--env ` | Apply an optional env overlay by name (use 'base' to bypass overlays) | | `--local` | Write to the worktree-local env override file instead of the shared repo env file | | `--service ` | Target scope (global or a discovered service name) | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack env backend` Manage env/secret storage backend strategy ### Usage ```bash hack env backend [options] ``` ### Subcommands | Command | Summary | | --- | --- | | `hack env backend status` | Show configured env/secret backend strategy | | `hack env backend use ` | Select env/secret backend strategy | ### Options | Option | Description | | --- | --- | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack host` Run host-side commands with project env injected ### Usage ```bash hack host [options] ``` Use hack host when a command should run on your host machine, not inside the compose network, but still needs Hack-resolved env and host-local rewrites. ### Subcommands | Command | Summary | | --- | --- | | `hack host ps` | Inspect host command lifetimes, CPU and lifecycle ownership (read-only) | | `hack host exec [command...]` | Run a host command with project env injected | | `hack host shell` | Open a host shell with project env injected | ### Options | Option | Description | | --- | --- | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack host ps` Inspect host command lifetimes, CPU and lifecycle ownership (read-only) ### Usage ```bash hack host ps [options] ``` ### Options | Option | Description | | --- | --- | | `--project ` | Target a registered project by name (from ~/.hack/projects.json) | | `--json` | Output JSON (machine-readable) | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack host exec [command...]` Run a host command with project env injected ### Usage ```bash hack host exec [command...] [options] ``` Run a one-off command on the host with the selected Hack env overlay injected. Use --scope when you want service-scoped values without running inside that service container. To inspect a value, prefer `printenv KEY` or `sh -lc 'printf "%s\n" "$KEY"'`; `echo $KEY` expands in your current shell before Hack injects env. ### Arguments | Arg | Description | | --- | --- | | `command` | | ### Options | Option | Description | | --- | --- | | `--path, -p ` | Run a project command against a repo path (overrides cwd search) | | `--project ` | Target a registered project by name (from ~/.hack/projects.json) | | `--env ` | Apply an optional env overlay by name (use 'base' to bypass overlays) | | `--scope ` | Resolve values for one env scope while still running the command on the host | | `--target ` | Env view for host commands (default: host rewrites container-oriented addresses for local host execution) | | `--shell ` | Run a shell command string via /bin/sh -lc after env injection so `$VAR` expansion happens inside the child shell | | `--timeout ` | Bound a non-TTY host command; terminate its process group and return 124 on expiry | | `--lifetime ` | Declare intended lifetime for diagnostics (default: command; does not detach) | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | ## `hack host shell` Open a host shell with project env injected ### Usage ```bash hack host shell [options] ``` Start an interactive host shell with the selected Hack env overlay injected. Use --scope when you want service-scoped values without running inside that service container. ### Options | Option | Description | | --- | --- | | `--path, -p ` | Run a project command against a repo path (overrides cwd search) | | `--project ` | Target a registered project by name (from ~/.hack/projects.json) | | `--env ` | Apply an optional env overlay by name (use 'base' to bypass overlays) | | `--scope ` | Resolve values for one env scope while still running the command on the host | | `--target ` | Env view for host commands (default: host rewrites container-oriented addresses for local host execution) | | `--no-interactive` | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | Show help | | `--version, -v` | Show version | --- ## System overview `hack` is a Bun CLI that writes per-project Compose files under `.hack/` and manages a machine-wide proxy, DNS helpers, and logging stack under `~/.hack/` (overridable via the `HACK_HOME` env var, which redirects all global state — registry, daemon, secrets — to another root). - **Caddy** (docker-proxy) routes `*.hack` based on container labels. - **CoreDNS** resolves `*.hack` inside containers to the Caddy IP, with `extra_hosts` mappings for resolver compatibility. - **Alloy + Loki + Grafana** capture logs and provide history. - **Schemas** are served by Caddy at `https://schemas.hack`. - **hackd (optional daemon)** caches Docker state for fast `hack projects --json` / `hack ps --json`. ```mermaid graph LR CLI["hack CLI (Bun)"] Browser["Browser"] subgraph Host["Developer machine"] subgraph Global["Global infra (~/.hack)"] Caddy["Caddy docker-proxy"] CoreDNS["CoreDNS"] Loki["Loki"] Grafana["Grafana"] Alloy["Alloy (Docker logs)"] end subgraph Project["Project repo (.hack)"] Compose["docker-compose.yml"] Services["Service containers"] end Hackd["hackd (optional daemon)"] end CLI -->|"hack global install/up"| Global CLI -->|"hack init/up"| Compose Compose -->|"docker compose"| Services CLI -->|"projects/ps --json"| Hackd Hackd -->|"docker events + ps"| Services Services -->|"Docker labels"| Caddy Services -->|"container logs"| Alloy Alloy --> Loki --> Grafana CoreDNS -->|"*.hack → Caddy IP"| Services Caddy -->|"https://*.hack"| Browser Grafana -->|"https://logs.hack"| Browser Caddy -->|"https://schemas.hack"| Browser ``` ## Global vs project scope - Global scope (`~/.hack`) - Caddy proxy on 80/443 (routes via Docker labels) - CoreDNS for container DNS (`*.hack` → Caddy) - macOS DNS helper: dnsmasq + `/etc/resolver` for `*.hack` → Caddy container IP - Logging stack (Alloy → Loki → Grafana) - Global config: `hack.config.json` (control plane defaults + extension settings) - Gateway bind/port/allowWrites - Schemas hosted under `https://schemas.hack` - Networks: `hack-dev` (ingress) and `hack-logging` - Project scope (`.hack`) - `docker-compose.yml` defines services + Caddy labels - `hack.config.json` stores project name, dev host, log preferences, OAuth alias, and browser launch preference (`open.prefer`) - `controlPlane.gateway.enabled` marks the project as gateway-capable - Optional overrides: - `.internal/compose.override.yml` (generated internal DNS/TLS injection) - `.internal/extra-hosts.json` — CLI-managed, not hand-edited (use `hack internal extra-hosts set/unset/list`) - `.branch/compose..override.yml` (branch builds) - Everything under `.hack/.internal` is a hack-managed artifact; do not hand-edit generated files there. ## Internal DNS + TLS (containers) When `internal.dns` / `internal.tls` are enabled, `hack up` writes a Compose override that: - sets each service’s DNS to the CoreDNS container - mounts Caddy’s local CA cert into each service, and — once `hack global trust` has generated it — the combined public+local trust bundle alongside it - points replace-semantics SSL env vars (`SSL_CERT_FILE`, `CURL_CA_BUNDLE`, `REQUESTS_CA_BUNDLE`, `GIT_SSL_CAINFO`) at the combined bundle, so OpenSSL-based tools (.NET/NuGet, git, python-requests) trust both public roots and `*.hack`; `NODE_EXTRA_CA_CERTS` appends the local CA for Node. Without the bundle, only the append-semantics vars are set — public TLS is never broken as a side effect of internal trust - injects `extra_hosts` mappings for `*.hack` → current Caddy IP (for runtimes that ignore custom DNS) - merges any repo-local `.hack/.internal/extra-hosts.json` entries (for host tunnels / dynamic domains) This lets containers use the same `https://*.hack` hostnames as the host machine. If Caddy’s IP changes, `hack status`, `hack doctor`, and the TUI will warn; `hack restart` refreshes the mapping. ```mermaid graph LR Service["Project container"] -->|"DNS query *.hack"| CoreDNS["CoreDNS (hack-dev)"] CoreDNS -->|"A record = Caddy IP"| Service Service -->|"HTTPS request"| Caddy["Caddy docker-proxy"] Caddy -->|"Routes by labels"| Upstream["Service upstream"] ``` ## Project env + secrets Projects can declare shareable env overlays and safely inject secrets into compose: - Canonical env: `.hack/hack.env.default.yaml` plus optional `.hack/hack.env..yaml` - Compatibility output: `.hack/.env` only when explicitly materialized - Secret key: checkout-local `.hack.secret.key`, or — in a linked git worktree — inherited automatically from the primary checkout through the shared git common dir; `HACK_ENV_SECRET_KEY` covers CI/detached environments. `hack doctor` flags divergent keys across checkouts. At runtime, hack resolves the selected overlay and injects the effective env directly into compose and host-side command flows. For service-scoped values, hack still generates `.hack/.internal/compose.env.override.yml` so compose services get the right per-service environment without requiring `.hack/.env` to exist. See `docs/env.md` for the current env model and migration notes. ## Project lifecycle hooks + host processes Projects can run host-side hooks around `hack up/down` and start managed host processes (auth steps, local proxies/tunnels). Processes are started inside a mux session (tmux or zellij) so they have a stable home and can be torn down on `hack down`. Lifecycle state is checkout-local at `.hack/.internal/lifecycle/state.json`. For tmux processes, the saved process group belongs to the wrapped user command rather than its mux pane shell. Each compose instance has its own entry, so starting a branch instance does not replace the base instance's entry in the same checkout. A random token mirrored in mux metadata and lifecycle state proves current session ownership; deterministic session names never authorize teardown. A versioned SHA-256 digest of the effective overlay and sorted lifecycle environment participates in session freshness without persisting environment names, keys, or values. Cleanup reconciles the saved process group with the live process table; if the group leader exited while members remain, `hack doctor` reports the orphan. `hack down` terminates the persisted leaderless group and descendant process groups only while a matching lifecycle mux session still proves ownership; without that session, cleanup stays non-destructive because the numeric PGID may have been reused. A live group leader without its saved pane PID is likewise not trusted as lifecycle ownership. Doctor also compares ownership-proven lifecycle sessions with live Compose instances. `doctor --fix` can remove a proven session only when its corresponding instance is absent and a second liveness and ownership check still agrees. Foreign or ambiguous same-name sessions remain non-destructive findings. For fixed-port helpers such as SSM/database/search tunnels, lifecycle config can also declare a `singleton` listener set. This lets Hack reuse an already-running equivalent helper or fail fast on partial conflicts instead of launching a competing duplicate supervisor. The intent is to reduce local port churn and keep external/manual tunnels from being mistaken for stale Hack-owned processes. See `docs/lifecycle.md` for config and behavior. ## Workflow (init → up → logs) ```mermaid sequenceDiagram participant User participant CLI as hack participant Docker participant Caddy participant Loki User->>CLI: hack init CLI->>Docker: create .hack/docker-compose.yml CLI-->>User: wrote .hack/ files User->>CLI: hack up CLI->>Docker: docker compose up Docker->>Caddy: read labels for routing Docker->>Loki: logs via Alloy User->>CLI: hack logs alt compose backend CLI->>Docker: docker compose logs else loki backend CLI->>Loki: query/tail LogQL end ``` ## Logging pipeline `hack logs` supports two backends: - **compose**: fast, direct `docker compose logs` - **loki**: searchable history + LogQL filters NDJSON streaming (`hack logs --json`) emits `start`, `log`, `error`, and `end` events for MCP/TUI consumers. Retention: - Loki retention is set in the global Loki config (`~/.hack/logging/loki.yaml`), default `168h` in the template. - Per-project overrides live in `hack.config.json` under `logs.retention_period` and apply when `hack down` prunes logs. ```mermaid graph LR Containers["Compose containers"] -->|"stdout/stderr"| Alloy Alloy -->|"push"| Loki Loki -->|"query"| CLI["hack logs --loki"] CLI -->|"NDJSON/pretty"| Terminal Loki -->|"Explore"| Grafana ``` Note: the daemon does not proxy logs yet; `hack logs` still talks directly to Docker Compose or Loki. ## Daemon (hackd) `hackd` is an optional local daemon that watches Docker events and maintains a cached view of running containers. It serves a small local API over a Unix socket at `~/.hack/daemon/hackd.sock` and powers: - `hack projects --json` - `hack ps --json` - streaming consumers (TUI/MCP) The event watcher ignores container actions such as health-check `exec_*` events that cannot change the cached runtime view. Relevant event bursts are debounced and rate-bounded. Event refreshes reuse inspect data for unchanged container IDs, while startup, watcher recovery, and the 30-second interval perform full inspection so missed events and mutable network data remain eventually consistent. If the daemon is not running (or version-mismatched), the CLI falls back to direct Docker calls. Daemon startup and `hack daemon clear` only terminate untracked daemon processes when `lsof` confirms they hold a socket in the target daemon state directory. Matching a process name is insufficient: a different `HOME` or `HACK_HOME` may own another daemon. If socket ownership cannot be established, automatic orphan termination is skipped. Scripted/noninteractive commands do not autostart the daemon; after an explicit stop, use `hack daemon start` to restore cached queries. Runtime health: - The daemon treats the container runtime as ephemeral; it fingerprints the engine (socket + engine id) and detects resets. - On reset detection, hackd performs one bounded cache refresh to stabilize its view before asking the user to repair anything manually. - When the runtime is unavailable, cached state is retained but marked stale; API responses include `runtime_*` metadata, including what changed, what hackd repaired, and the next step when manual recovery is still required. Project `status` becomes `unknown`. Why optional: - The CLI must keep working with zero background processes. - Not all users need cached JSON (especially if they only use interactive commands). - It stays off in minimal or constrained environments, but is available when you want faster status. ```mermaid graph LR CLI["hack CLI (JSON)"] -->|GET /v1/projects| Hackd["hackd"] CLI -->|GET /v1/ps| Hackd Hackd -->|"docker events"| Docker["Docker Engine"] Hackd -->|"docker ps"| Docker Hackd -->|"cached state"| Cache["In-memory cache"] ``` ## Control plane + extensions The control plane keeps the core CLI minimal while adding features as extensions. `hackd` loads extension manifests and exposes their APIs; the CLI dispatches extension commands via `hack x`. Builtin extensions: **Supervisor** (job execution + streaming for agents), **Gateway** (optional HTTP/WS access to `hackd`), **Cloudflare**, and **Tailscale** (exposure/tunnel helpers). > Gateway, remote, node, and dispatch surfaces are experimental and unsupported. They are hidden > from default `hack help` (use `hack help --all` to see them) and print a warning when invoked. > See [Beta workflows](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/docs/beta.md) and [Gateway API](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/docs/gateway-api.md) for details — this doc only > summarizes where they fit in the system. ```mermaid graph LR CLI["hack CLI"] --> Hackd["hackd"] Hackd --> ExtMgr["ExtensionManager"] ExtMgr --> Gateway["Gateway"] ExtMgr --> Supervisor["Supervisor"] ExtMgr --> Cloudflare["Cloudflare"] ExtMgr --> Tailscale["Tailscale"] Remote["Remote client"] -->|HTTP/WS| Gateway Gateway --> Hackd ``` ### Gateway API + remote workflows (unsupported experimental) Summary only — see `gateway-api.md` for full usage, security posture, and end-to-end examples: - `GET /v1/projects` with `project_id` for remote workflow routing - job execution + streaming (`/control-plane/projects/:id/jobs`) - PTY-backed shells (`/control-plane/projects/:id/shells`, WS stream) - One gateway instance is active per machine (global config); projects opt in with `controlPlane.gateway.enabled`; remote clients route by `project_id` in the API paths. ## Branch builds `--branch ` generates a per-branch Compose override that: - prefixes hostnames (e.g. `api.myapp.hack` → `api..myapp.hack`) - prefixes the Compose project name This enables parallel worktrees without port or hostname collisions. In a linked git worktree, `hack up` defaults to a branch instance named after the worktree's git branch instead of requiring an explicit `--branch` — opt out with config `worktree.auto_branch=false` or pass an explicit `--branch`. The secret key for a linked worktree is inherited automatically from the primary checkout through the shared git common dir (see "Project env + secrets" above), and `hack doctor` checks for divergent secret keys and `dev_host` collisions across checkouts sharing the same repo. If the linked worktree is detached, Hack refuses to silently target the base compose project because there is no branch name from which to derive an isolated instance. Pass `--branch ` to select one, or set `worktree.auto_branch=false` to opt into the base instance explicitly. ## Files and directories - `~/.hack/` (default; override the whole root with `HACK_HOME`) - `hack.config.json` (global config: control-plane defaults, gateway bind/port/allowWrites, extension settings) - `daemon/hackd.sock` - `daemon/hackd.pid` - `daemon/hackd.log` - `caddy/docker-compose.yml` - `caddy/Corefile` (CoreDNS config) - `logging/docker-compose.yml` - `logging/alloy.alloy` - `logging/loki.yaml` - `logging/grafana/...` - `schemas/hack.config.schema.json` - `schemas/hack.branches.schema.json` - `certs/` (mkcert output for non-Caddy services) - `projects.json` (best-effort registry; `hack projects prune` removes stale entries and stops orphaned containers) - `/.hack/` - `docker-compose.yml` - `hack.config.json` - `hack.branches.json` (optional) - `.gitignore` (committed, self-healing on `init`/`up`; covers machine-local generated files — `.internal/`, `.branch/`, `.env`, `.env.state.json`, and `hack.env*.local.yaml`. The retired `tickets/` path stays ignored only to contain legacy machine-local caches during upgrades. If generated files leaked into git, `hack doctor --fix` untracks them without deleting them from disk.) - `hack.env.default.yaml` plus optional `hack.env..yaml` (committed env) - `hack.env.local.yaml` / `hack.env..local.yaml` (worktree-local overrides) - `.env.state.json` - `.env` (optional, only when explicitly materialized) - `.internal/compose.override.yml` - `.internal/compose.env.override.yml` - `.internal/compose.runtime.override.yml` - `.internal/extra-hosts.json` - `.internal/lifecycle/state.json` and `.internal/lifecycle/*.log` - `.branch/compose..override.yml` - `.branch/compose..runtime.override.yml` ## Key design choices - Docker Compose is the execution substrate for predictability and portability. - Caddy routes by container label so there is no per-repo reverse proxy config. - CoreDNS gives containers the same `*.hack` namespace as the host. - Logs default to `docker compose logs` for speed; Loki is used for history and filtering. - The optional daemon keeps CLI JSON queries fast without making it a hard dependency. - Config lives alongside each repo in `.hack/` to keep repos isolated and portable. - Schemas are generated from templates and served locally for editor validation. --- # Reference ## CLI & architecture - [CLI overview](/docs/v4/cli) — supported command surface and the running-things decision guide - [CLI reference (generated, exhaustive)](/docs/v4/reference/cli) — every command and flag, rendered from the spec (regenerate: `bun run docs:cli-reference`) - [Architecture](/docs/v4/architecture) - [Core docs](/docs/v4/core) - [Docs information architecture](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/docs/docs-ia.md) ## Environment & sessions - [Environment model](/docs/v4/env) - [Lifecycle & startup](/docs/v4/lifecycle) - [Sessions](/docs/v4/sessions) - [Agent-first setup](/docs/v4/guides/agent-first-setup) ## Extensions - [Extensions](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/docs/extensions.md) - [Creating an extension](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/docs/guides/create-extension.md) - [Integrations](/docs/v4/integrations) - [SDK](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/docs/sdk.md) ## Experimental / beta - [Beta workflows](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/docs/beta.md) - [Experimental remote docs](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/docs/gateway.md) — remote/gateway/node/dispatch are unsupported experimental surfaces, hidden from default help behind `hack help --all` and warn on use; see the product-boundary notes in `src/agents/instruction-source.ts` - [Gateway API](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/docs/gateway-api.md) - [Supervisor](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/docs/supervisor.md) --- # Documentation Hack keeps the parts needed to run a project together: services, environment, secrets, local URLs, startup helpers and logs. The setup lives with your repository. v4 is the current stable line. v5, the next major version, is in prerelease. Choose v5 in the version selector for its docs and the upgrade guide. Start with [Install](/docs/v4/install), then [Getting started](/docs/v4/getting-started). ## Understand the project - [Core concepts](/docs/v4/core): projects, services and running instances. - [Environment and secrets](/docs/v4/env): share configuration and keep keys separate. - [Lifecycle](/docs/v4/lifecycle): start helpers with the project. - [Sessions](/docs/v4/sessions): persistent workspaces. ## Do a task - [Run and inspect a project](/docs/v4/guides/run-project) - [Choose where a command runs](/docs/v4/guides/run-commands) - [Work on another branch](/docs/v4/guides/parallel-work) - [Share environment and secrets](/docs/v4/guides/share-environment) - [Manage helpers and tunnels](/docs/v4/guides/project-helpers) - [Use a cloud agent or another host](/docs/v4/guides/cloud-environments) ## Work with an agent [Agent handoff](/docs/v4/agent-handoff) supplies this version's documentation exports and setup instructions. [Agent integrations](/docs/v4/integrations) describes the matching optional client setup. ## Find details or diagnose a problem Use the [CLI overview](/docs/v4/cli) to choose a command, the [command reference](/docs/v4/reference/cli) for flags, [contracts](/docs/v4/reference/overview) for schemas and agent interfaces, and [Architecture](/docs/v4/architecture) for the runtime model. Run `hack doctor` on the machine running Hack and follow the specific diagnosis. --- # Install ## Prerequisites Use a machine with a supported Hack release binary and a running Docker-compatible engine with Docker Compose. macOS users can install through Homebrew. Local DNS and certificate trust setup can require native approval. Check the engine before project startup: ```sh docker info docker compose version ``` The v4.2.4 README documents this stable-channel installation: ```sh brew tap hack-dance/tap brew install hack-dance/tap/hack hack version ``` Homebrew follows the current stable formula; it does not pin v4.2.4. For a historical binary, inspect the [v4.2.4 release](https://github.com/hack-dance/hack/releases/tag/v4.2.4) and choose the asset for your platform. Verify the installed version before following these archived docs. Continue with [Getting started](/docs/v4/getting-started). ## Set up local Compose routing Before starting a Compose project on a new development host: ```sh hack global install ``` Read the prompts. This configures shared local routing, DNS and certificate trust and can require native approval. Confirm the Docker-compatible engine is running. Do not expect a remote host's local names or trust to appear on your laptop automatically. Follow the matching project guide if setup reports a missing prerequisite. This documentation does not perform these host changes. --- # Getting started Complete [Install](/docs/v4/install) first. These examples use the Compose runtime in v4.2.4. Verify `hack version` before using the archived command reference. ## Prepare one repository Use a repository you own. Check its README, toolchain and required services before starting it. For an existing Compose app, review its Compose files and let [Project setup](/docs/v4/guides/init-project) guide the configuration. For a project without Compose, initialize Hack and define the services it needs; Hack does not guess an application deployment from source code alone. ```sh cd your-project hack init ``` Review the generated `.hack/` configuration. Keep keys and local machine state out of git. Set up shared local routing using the version's Install instructions before expecting HTTPS URLs to work. ## Start, inspect and stop ```sh hack up --detach hack open hack ps hack logs --no-follow --tail 50 ``` Expected: the declared services start, `open` finds the instance URL, and `ps` shows service state. Visit the app and run its normal health check; a URL or a running container alone does not prove the app works. If startup fails, read its error and run `hack doctor` before trying again. ```sh hack down ``` Stop releases project-owned runtime processes. It is not an instruction to delete application data or prune shared caches. See [Run and inspect](/docs/v4/guides/run-project) for selected services and log history. --- # Give an agent the right context Read this version's [LLM index](/v4/llms.txt) or [full corpus](/v4/llms-full.txt). They contain only the selected version's allowlisted public docs. Use these canonical URLs when the public site is deployed; for local review use the same paths on the preview host: ```text https://hack.foo/v4/llms.txt https://hack.foo/v4/llms-full.txt ``` A useful instruction to your agent: ```text Read the selected Hack documentation index and the repository AGENTS.md. Confirm the CLI version, execution host, project and intended instance. Follow Install and Getting started for that version. Inspect existing services before starting another instance. Keep secret values out of chat and command arguments. Verify the application's own health, not just CLI exit status. ``` [Agent integrations](/docs/v4/integrations) describes this version's optional client setup. Use the documented Codex/Claude/Cursor integration and MCP paths that exist in that version. A plugin on your laptop does not install tools in a cloud agent. Agents with shell access can use the CLI directly; MCP is a separate interface, not a prerequisite for ordinary project use. --- # Run and inspect a project Use this after [Getting started](/docs/v4/getting-started). These examples use the Compose runtime in v4.2.4. Verify `hack version` before using the archived command reference. ## Start or restart ```sh hack up --detach hack ps hack open hack restart web ``` Replace `web` with a declared service. A selected-service operation differs from a whole-project lifecycle; read the command reference before relying on hooks or implicit dependencies. Inspect the app after restart. ## Read logs ```sh hack logs web --no-follow --tail 100 hack logs web --compose hack logs --loki --since 2h --pretty ``` The first command is a finite snapshot. The second follows live Compose output; interrupt it with Ctrl-C. Loki history needs the global logging stack running on that host and is unavailable in slim environments. Read the matching [command reference](/docs/v4/reference/cli) for supported filters and formats. Native authored logs have a narrower finite-command contract; these Compose examples do not establish native flag parity. ```sh hack down ``` Use ordinary shutdown after review. Check reported failures rather than issuing broad cleanup commands. --- # Choose where a command runs These examples use the Compose runtime in v4.2.4. Verify `hack version` before using the archived command reference. Use `exec` when the target service is already running. Use `run` for a one-off command in a fresh service container. Use `host exec` for a command that must run on the current host with resolved project environment. ```sh hack exec web -- node --version hack run web node --version hack host exec --scope web -- node --version ``` Replace `web` and the command with your project's actual service and tool. These examples report the installed Node version in three different execution contexts; they do not install Node. The host path needs Node on the host. Inspect service prerequisites and the matching [reference](/docs/v4/reference/cli) before running migrations or other data-changing commands. An agent uses the same execution model. Ask it to read project instructions, select the intended host and instance, and inspect state before starting new work. --- # Work on another branch Start from a configured repository. Read [worktree behavior](/docs/v4/guides/development-runtime-safety) for this version before choosing shared or isolated files. ```sh git worktree add ../project-review -b review-work cd ../project-review hack up --detach hack open hack ps ``` Linked worktrees normally select a branch instance automatically. Confirm the selected instance and URL in the output; detached worktrees need an explicit `--branch` choice. Stop the instance from its owning checkout when finished. A separate branch environment does not automatically isolate external databases, shared bind-mounted files or credentials. Coordinate with people and agents: name the checkout/branch, assign service and file ownership, and keep one owner for lifecycle operations against an instance. --- # Share environment and secrets Read [Environment and secrets](/docs/v4/env) before choosing a backend. Commit shareable configuration; keep decryption keys and local overrides separate. ```sh hack env list hack env explain API_URL --service web --target compose ``` Inspect masked values and provenance rather than printing credentials. Scope values to the intended service/overlay. A linked worktree can inherit the primary checkout's key; a separate host needs its own approved runtime delivery mechanism. For encrypted-file storage, possession of the project key grants decryption of values encrypted with it. Keep an approved backup separate from the repository. Git access and secret access are different grants. Removing someone's repository access does not erase keys or values already copied to their machine. Follow the implemented backend's rotation/revocation procedure; do not assume a universal `hack` revocation or secret-manager synchronization command exists. ## External secret managers Use the provider's approved authentication flow and the backend contract in the matching reference. An illustrative integration reads a single required value through the provider CLI and sends it directly into a supported hidden/standard- input path; do not put it in shell arguments, chat, logs or cached files. Exact write commands and provider support differ by version, so no generic sync command is implied here. Verify masked metadata, then the app's actual service access. --- # Manage helpers and tunnels Use a lifecycle process when the project needs a long-running host helper, such as a development tunnel or database proxy. Use an up-before hook for a finite setup or authentication check. This makes the dependency visible in project configuration instead of relying on an extra terminal tab. Read [Lifecycle](/docs/v4/lifecycle) for this version's concrete configuration schema and examples. Keep tool installation separate from login: a cloud SSO login may require the person to complete its browser flow, and credentials must not be committed or printed. Check the approved CLI profile and target before starting a tunnel. A listener existing on a port does not prove it is the correct tunnel. Declare readiness and ownership using the supported lifecycle contract. Reuse an existing healthy listener only when the configuration explicitly supports adoption; shutdown must preserve externally owned processes. Confirm the helper's expected connection and the app's health after startup. No tunnel, public endpoint or cloud login is created by reading this guide. --- # Use a cloud agent or another host Choose the execution environment first: - **Your local machine:** Hack uses that machine's services, configuration and routing. - **A cloud coding-agent environment:** install and run Hack inside the provider's VM/container, subject to its runtime, persistence, secret and network rules. - **An existing remote development host:** Hack runs locally on that host; SSH or an agent is transport, not a built-in Hack fleet controller. - **An application hosting service:** deploying an app to ECS or an agent runtime is a separate workflow. Hack does not translate project configuration into a deployment there. Use [Managed environments](/docs/v4/guides/codex-managed-environments) for the version-specific installation contract. Verify OS/CPU architecture, matching release asset, project toolchain, Docker daemon and Compose (for that runtime), bind mounts, network access, task-time credentials and startup after snapshot restore. Installing a CLI does not supply a Docker daemon or laptop certificate trust. A macOS native bundle does not install on an Ubuntu cloud VM. ## Named platform compatibility These are documentation-based assessments, not successful Hack application tests: | Platform | Supported prerequisite evidence | Remaining verification | | --- | --- | --- | | [Cursor cloud agents](https://cursor.com/docs/cloud-agent) | Provider-managed Ubuntu; inspect current environment/Docker documentation | Nested Docker, mounts, startup and task-time secrets for your app | | [boat.dev](https://boat.dev) | Provider documents Linux VMs, SSH and Docker | Architecture, matching asset, persistence and app readiness | | [Google Jules](https://jules.google/docs/environment/) | Managed task VM; use its current tool/setup contract | Secret lifetime, daemon availability and app health | | [Google Cloud Workstations](https://cloud.google.com/workstations/docs/overview) | Managed workstation environment | Actual image, Docker access and persistent paths | | code.computer | Exact product documentation could not be retrieved during review | Identity and runtime contract unverified; no setup recipe claimed | | [Amazon ECS](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/Welcome.html) | App container hosting; Fargate is not a privileged Docker host | No verified Hack deployment adapter or full host-runtime integration | | Personal fleet | Ordinary CLI installation per compatible existing host | Per-host runtime, access, state and routing qualification | Use provider-approved secret injection at task time. Do not bake project keys into images or snapshots. Provider setup scripts, build snapshots and service startup may have different lifetimes. Test the actual application after every fresh task or resumed host. Remote/gateway/node/dispatch commands are outside the supported setup described here. --- # Managed environments A managed coding-agent container is a separate execution environment. Confirm its OS/architecture, writable paths, process/snapshot lifecycle, network policy, project toolchain and task-time secret delivery before installing tools. ## Install the portable CLI The v4.2.4 release includes a portable installer and a Linux x86_64 archive. Verify the provider's architecture and release assets; do not infer Linux ARM64 support from an installer branch. Download the script from the selected release, inspect it, then run it with the explicit tag: ```sh curl --fail --location --proto '=https' --tlsv1.2 \ https://github.com/hack-dance/hack/releases/download/v4.2.4/hack-codex-install.sh \ --output hack-codex-install.sh # Inspect this file before executing it. HACK_INSTALL_TAG=v4.2.4 bash ./hack-codex-install.sh hack version ``` Select a dedicated installation destination using the installer's documented options when another Hack channel exists. Verify the executable path and version. The portable/slim path supplies env resolution and host commands; it does not supply a Docker daemon, shared local DNS, certificate trust or a full app runtime. ## Prepare dependencies and services Use the repository's pinned toolchain and frozen lockfile. For a Bun project: ```sh bun install --frozen-lockfile ``` Do not silently fall back to changing the lockfile when installation fails. Other languages need their own declared tools. Full Compose execution additionally needs a working Docker daemon, Compose, compatible mounts and application network access. Run `docker info` and `docker compose version` inside the actual task environment; an installed client alone is insufficient. ## Deliver secrets at task time Provide `HACK_ENV_SECRET_KEY` through the provider's approved runtime injection mechanism only when encrypted-file decryption is required. The actual key must reach the Hack process. Do not bake it into a Dockerfile, setup snapshot or shell profile, and do not print the key or decrypted environment as a diagnostic. Provider setup and agent phases may have different secret lifetimes: verify the actual task phase instead of assuming setup exports survive. Inspect masked configuration, then exercise a harmless project command: ```sh hack env list hack host exec --scope api -- bun --version ``` This assumes the selected compatible CLI is `hack` on PATH and the project declares an `api` scope with Bun available on that host. Replace those details with the project's real tool and scope. Verify application access separately; a masked env listing does not prove credentials work. Set `HACK_NO_INTERACTIVE=1` for scripted work and inspect explicit failures rather than waiting for a terminal prompt. Restart required services after snapshot restore: disk snapshots do not preserve running processes. No provider resource, network exposure or account grant is created by these instructions. --- # Reference and contracts Start with the [CLI overview](/docs/v4/cli) to choose a command and the [generated command reference](/docs/v4/reference/cli) for usage and flags. [Command and output contracts](/docs/v4/reference/command-contracts) adds the deeper leaf sections, complete public flag inventory and command-specific JSON/log records. Read [Run and inspect](/docs/v4/guides/run-project) for a task sequence rather than using a flag list as an installation guide. A command being listed is not proof that every backend accepts it. Read the selected version's runtime limits alongside examples. Help's global flags and a parent command table are distinct from complete leaf-command option coverage. ## Environment and lifecycle configuration [Environment and secrets](/docs/v4/env), [Lifecycle](/docs/v4/lifecycle) and [Architecture](/docs/v4/architecture) explain the project configuration model. Do not infer schema defaults or cloud-provider support from a similarly named field in another version. ## Agent interface The [CLI reference](/docs/v4/reference/cli) and [integrations](/docs/v4/integrations) provide the v4 consumer interface. Public MCP implementation is preserved at the [pinned source revision](https://github.com/hack-dance/hack/tree/91b14bf0abb17602142425de0d02628a3e8a2615/src/mcp). Later v5 compiler schemas and MCP reference pages are not substitutes for the v4 contract. This archived corpus has no generated complete API/type catalog. ## Field references [Configuration fields](/docs/v4/reference/configuration-fields) lists the version-specific project JSON, environment YAML and branch registry. [MCP fields and results](/docs/v4/reference/mcp-fields) lists every registered tool's input declarations, result fields and log event types. [Project and env reports](/docs/v4/reference/project-env-reports) details the owned inventory, metadata, raw env-list and restart-wrapper projections. Raw CLI env reports are not value-free MCP projections. [Diagnostic and setup reports](/docs/v4/reference/diagnostic-reports) lists the owned doctor, setup, update and host telemetry types, plus the public candidate-report wrappers where present. Private compiler Plan internals are excluded. ## Coverage limits This first versioned pass preserves generated command documentation and separates public contracts from internal implementation types. Some deeper subcommands lack full generated usage/options sections. Dedicated per-flag and configuration-field coverage remains an explicit follow-up; neither a parent table nor a linked source file counts as a complete prose API specification. No internal DTO is promoted to a supported public API by appearing in the repository. --- # Configuration fields This reference describes v4.2.4. Use [Environment and secrets](/docs/v4/env) and [Lifecycle](/docs/v4/lifecycle) for workflows. Fields below come from the version-pinned schema and readers, not a newer checkout. ## Project JSON The legacy project file is `.hack/hack.config.json`. Requiredness below is relative to the containing schema object or union variant. An optional parent does not become required because a child is required. Repeated paths describe different variants. The schema requires `name` and `dev_host`; the reader has compatibility fallbacks. A schema constraint is not proof the reader validates it. No schema default is declared for these fields. | Field | Type | Within this variant | Constraints | Schema location | Evidence | | --- | --- | --- | --- | --- | --- | | `$schema` | `string` | Optional | — | `#/properties/$schema` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `name` | `string` | Required | — | `#/properties/name` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `dev_host` | `string` | Required | — | `#/properties/dev_host` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `defaultEnvConfig` | `string` | Optional | — | `#/properties/defaultEnvConfig` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `default_env_config` | `string` | Optional | — | `#/properties/default_env_config` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `logs` | `object` | Optional | `{"additionalProperties":true}` | `#/properties/logs` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `logs.follow_backend` | `string` | Optional | `{"enum":["compose","loki"]}` | `#/properties/logs/properties/follow_backend` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `logs.snapshot_backend` | `string` | Optional | `{"enum":["compose","loki"]}` | `#/properties/logs/properties/snapshot_backend` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `logs.clear_on_down` | `boolean` | Optional | — | `#/properties/logs/properties/clear_on_down` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `logs.retention_period` | `string` | Optional | — | `#/properties/logs/properties/retention_period` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `internal` | `object` | Optional | `{"additionalProperties":true}` | `#/properties/internal` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `internal.dns` | `boolean` | Optional | — | `#/properties/internal/properties/dns` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `internal.tls` | `boolean` | Optional | — | `#/properties/internal/properties/tls` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `internal.extra_hosts` | `object` | Optional | `{"additionalProperties":{"type":"string"}}` | `#/properties/internal/properties/extra_hosts` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `oauth` | `object` | Optional | `{"additionalProperties":true}` | `#/properties/oauth` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `oauth.enabled` | `boolean` | Optional | — | `#/properties/oauth/properties/enabled` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `oauth.tld` | `string` | Optional | — | `#/properties/oauth/properties/tld` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `open` | `object` | Optional | `{"additionalProperties":true}` | `#/properties/open` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `open.prefer` | `string` | Optional | `{"enum":["auto","alias","dev"]}` | `#/properties/open/properties/prefer` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `worktree` | `object` | Optional | `{"additionalProperties":true}` | `#/properties/worktree` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `worktree.auto_branch` | `boolean` | Optional | — | `#/properties/worktree/properties/auto_branch` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `sessions` | `object` | Optional | `{"additionalProperties":true}` | `#/properties/sessions` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `sessions.mux` | `string` | Optional | `{"enum":["auto","tmux","zellij","none"]}` | `#/properties/sessions/properties/mux` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `startup` | `array` | Optional | — | `#/properties/startup` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `startup[].name` | `string` | Optional | — | `#/properties/startup/items/anyOf/1/properties/name` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `startup[].run` | `string` | Optional | — | `#/properties/startup/items/anyOf/1/properties/run` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `startup[].command` | `string` | Optional | — | `#/properties/startup/items/anyOf/1/properties/command` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `startup[].cwd` | `string` | Optional | — | `#/properties/startup/items/anyOf/1/properties/cwd` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `startup[].persistent` | `boolean` | Optional | — | `#/properties/startup/items/anyOf/1/properties/persistent` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `startup[].singleton` | `object` | Optional | `{"additionalProperties":false}` | `#/properties/startup/items/anyOf/1/properties/singleton` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `startup[].singleton.ports` | `array` | Required | `{"minItems":1,"uniqueItems":true}` | `#/properties/startup/items/anyOf/1/properties/singleton/properties/ports` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `startup[].singleton.onConflict` | `string` | Optional | `{"enum":["adopt","fail"]}` | `#/properties/startup/items/anyOf/1/properties/singleton/properties/onConflict` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `lifecycle` | `object` | Optional | `{"additionalProperties":false}` | `#/properties/lifecycle` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `lifecycle.up` | `object` | Optional | `{"additionalProperties":false}` | `#/properties/lifecycle/properties/up` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `lifecycle.up.before` | `array` | Optional | — | `#/properties/lifecycle/properties/up/properties/before` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `lifecycle.up.before[].name` | `string` | Optional | — | `#/properties/lifecycle/properties/up/properties/before/items/anyOf/1/properties/name` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `lifecycle.up.before[].command` | `string` | Required | — | `#/properties/lifecycle/properties/up/properties/before/items/anyOf/1/properties/command` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `lifecycle.up.before[].cwd` | `string` | Optional | — | `#/properties/lifecycle/properties/up/properties/before/items/anyOf/1/properties/cwd` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `lifecycle.up.before[].persistent` | `boolean` | Optional | — | `#/properties/lifecycle/properties/up/properties/before/items/anyOf/1/properties/persistent` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `lifecycle.up.before[].singleton` | `object` | Optional | `{"additionalProperties":false}` | `#/properties/lifecycle/properties/up/properties/before/items/anyOf/1/properties/singleton` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `lifecycle.up.before[].singleton.ports` | `array` | Required | `{"minItems":1,"uniqueItems":true}` | `#/properties/lifecycle/properties/up/properties/before/items/anyOf/1/properties/singleton/properties/ports` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `lifecycle.up.before[].singleton.onConflict` | `string` | Optional | `{"enum":["adopt","fail"]}` | `#/properties/lifecycle/properties/up/properties/before/items/anyOf/1/properties/singleton/properties/onConflict` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `lifecycle.up.after` | `array` | Optional | — | `#/properties/lifecycle/properties/up/properties/after` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `lifecycle.up.after[].name` | `string` | Optional | — | `#/properties/lifecycle/properties/up/properties/after/items/anyOf/1/properties/name` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `lifecycle.up.after[].command` | `string` | Required | — | `#/properties/lifecycle/properties/up/properties/after/items/anyOf/1/properties/command` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `lifecycle.up.after[].cwd` | `string` | Optional | — | `#/properties/lifecycle/properties/up/properties/after/items/anyOf/1/properties/cwd` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `lifecycle.up.after[].persistent` | `boolean` | Optional | — | `#/properties/lifecycle/properties/up/properties/after/items/anyOf/1/properties/persistent` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `lifecycle.up.after[].singleton` | `object` | Optional | `{"additionalProperties":false}` | `#/properties/lifecycle/properties/up/properties/after/items/anyOf/1/properties/singleton` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `lifecycle.up.after[].singleton.ports` | `array` | Required | `{"minItems":1,"uniqueItems":true}` | `#/properties/lifecycle/properties/up/properties/after/items/anyOf/1/properties/singleton/properties/ports` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `lifecycle.up.after[].singleton.onConflict` | `string` | Optional | `{"enum":["adopt","fail"]}` | `#/properties/lifecycle/properties/up/properties/after/items/anyOf/1/properties/singleton/properties/onConflict` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `lifecycle.down` | `object` | Optional | `{"additionalProperties":false}` | `#/properties/lifecycle/properties/down` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `lifecycle.down.before` | `array` | Optional | — | `#/properties/lifecycle/properties/down/properties/before` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `lifecycle.down.before[].name` | `string` | Optional | — | `#/properties/lifecycle/properties/down/properties/before/items/anyOf/1/properties/name` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `lifecycle.down.before[].command` | `string` | Required | — | `#/properties/lifecycle/properties/down/properties/before/items/anyOf/1/properties/command` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `lifecycle.down.before[].cwd` | `string` | Optional | — | `#/properties/lifecycle/properties/down/properties/before/items/anyOf/1/properties/cwd` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `lifecycle.down.before[].persistent` | `boolean` | Optional | — | `#/properties/lifecycle/properties/down/properties/before/items/anyOf/1/properties/persistent` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `lifecycle.down.before[].singleton` | `object` | Optional | `{"additionalProperties":false}` | `#/properties/lifecycle/properties/down/properties/before/items/anyOf/1/properties/singleton` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `lifecycle.down.before[].singleton.ports` | `array` | Required | `{"minItems":1,"uniqueItems":true}` | `#/properties/lifecycle/properties/down/properties/before/items/anyOf/1/properties/singleton/properties/ports` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `lifecycle.down.before[].singleton.onConflict` | `string` | Optional | `{"enum":["adopt","fail"]}` | `#/properties/lifecycle/properties/down/properties/before/items/anyOf/1/properties/singleton/properties/onConflict` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `lifecycle.down.after` | `array` | Optional | — | `#/properties/lifecycle/properties/down/properties/after` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `lifecycle.down.after[].name` | `string` | Optional | — | `#/properties/lifecycle/properties/down/properties/after/items/anyOf/1/properties/name` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `lifecycle.down.after[].command` | `string` | Required | — | `#/properties/lifecycle/properties/down/properties/after/items/anyOf/1/properties/command` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `lifecycle.down.after[].cwd` | `string` | Optional | — | `#/properties/lifecycle/properties/down/properties/after/items/anyOf/1/properties/cwd` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `lifecycle.down.after[].persistent` | `boolean` | Optional | — | `#/properties/lifecycle/properties/down/properties/after/items/anyOf/1/properties/persistent` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `lifecycle.down.after[].singleton` | `object` | Optional | `{"additionalProperties":false}` | `#/properties/lifecycle/properties/down/properties/after/items/anyOf/1/properties/singleton` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `lifecycle.down.after[].singleton.ports` | `array` | Required | `{"minItems":1,"uniqueItems":true}` | `#/properties/lifecycle/properties/down/properties/after/items/anyOf/1/properties/singleton/properties/ports` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `lifecycle.down.after[].singleton.onConflict` | `string` | Optional | `{"enum":["adopt","fail"]}` | `#/properties/lifecycle/properties/down/properties/after/items/anyOf/1/properties/singleton/properties/onConflict` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `lifecycle.processes` | `array` | Optional | — | `#/properties/lifecycle/properties/processes` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `lifecycle.processes[].name` | `string` | Required | — | `#/properties/lifecycle/properties/processes/items/properties/name` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `lifecycle.processes[].command` | `string` | Required | — | `#/properties/lifecycle/properties/processes/items/properties/command` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `lifecycle.processes[].cwd` | `string` | Optional | — | `#/properties/lifecycle/properties/processes/items/properties/cwd` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `lifecycle.processes[].singleton` | `object` | Optional | `{"additionalProperties":false}` | `#/properties/lifecycle/properties/processes/items/properties/singleton` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `lifecycle.processes[].singleton.ports` | `array` | Required | `{"minItems":1,"uniqueItems":true}` | `#/properties/lifecycle/properties/processes/items/properties/singleton/properties/ports` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `lifecycle.processes[].singleton.onConflict` | `string` | Optional | `{"enum":["adopt","fail"]}` | `#/properties/lifecycle/properties/processes/items/properties/singleton/properties/onConflict` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `controlPlane` | `object` | Optional | `{"additionalProperties":true}` | `#/properties/controlPlane` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `controlPlane.tui` | `object` | Optional | `{"additionalProperties":true}` | `#/properties/controlPlane/properties/tui` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `controlPlane.tui.logs` | `object` | Optional | `{"additionalProperties":true}` | `#/properties/controlPlane/properties/tui/properties/logs` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `controlPlane.tui.logs.maxEntries` | `number` | Optional | — | `#/properties/controlPlane/properties/tui/properties/logs/properties/maxEntries` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `controlPlane.tui.logs.maxLines` | `number` | Optional | — | `#/properties/controlPlane/properties/tui/properties/logs/properties/maxLines` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `controlPlane.tui.logs.historyTailStep` | `number` | Optional | — | `#/properties/controlPlane/properties/tui/properties/logs/properties/historyTailStep` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `controlPlane.usage` | `object` | Optional | `{"additionalProperties":true}` | `#/properties/controlPlane/properties/usage` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `controlPlane.usage.watchIntervalMs` | `number` | Optional | — | `#/properties/controlPlane/properties/usage/properties/watchIntervalMs` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `controlPlane.usage.historySize` | `number` | Optional | — | `#/properties/controlPlane/properties/usage/properties/historySize` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `controlPlane.daemon` | `object` | Optional | `{"additionalProperties":true}` | `#/properties/controlPlane/properties/daemon` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | | `controlPlane.daemon.autoStart` | `boolean` | Optional | — | `#/properties/controlPlane/properties/daemon/properties/autoStart` | [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/templates.ts#L381) | ### Aliases and selection Prefer `env.defaultOverlay` for the default overlay. The reader checks `env.defaultOverlay` before `env.default_overlay`; nested env selection precedes legacy `defaultEnvConfig`, which in turn precedes `default_env_config`. These nested fields are read even though the legacy generated schema does not enumerate the `env` object. `worktree.autoBranch` is an alias of `worktree.auto_branch`; a non-null snake_case value is selected before the camelCase alias, then parsed as a boolean. Use one spelling rather than conflicting aliases. ### Effective fallbacks | Field | Fallback | Scope | | --- | --- | --- | | `logs.follow_backend` | `"compose"` | consumer fallback, not schema default | | `logs.snapshot_backend` | `"loki"` | consumer fallback, can fall back or be explicitly forced | | `startup[].persistent` | `false` | reader/workflow default documented in lifecycle | | `worktree.auto_branch` | `true` | reader/caller default; linked checkouts only | | `values.global` | `{}` | parser normalization | | `environment` | `null` | selected layer environment fallback, not a fixed literal | | `branchRegistry.branches` | `[]` | missing-file writer default, not proof invalid files are rewritten | Log preferences are not forced backend selection. Follow mode prefers Compose; snapshots prefer Loki, with consumer-specific fallback. `startup[].persistent` defaults false. Linked-worktree auto-branch selection defaults on in the legacy Compose path; an ordinary checkout remains the base instance. Follow the runtime-specific command guide. ### Hooks and processes `startup` accepts string shorthand or objects. Startup objects require at least one of `run` or `command`. The reader prefers `run` and drops entries whose selected command is empty. They accept optional `name`/`cwd`, and `persistent` (false by default). `lifecycle.up.before/after` and `lifecycle.down.before/after` are hook arrays; their command-object variants require `command`. Do not transfer the startup-only `run` spelling to every hook. `lifecycle.processes` names long-lived processes and requires `name` and `command`. `singleton.ports` contains unique positive ports; `singleton.onConflict` selects `adopt` or `fail`. Read [Lifecycle](/docs/v4/lifecycle) for working-directory origins, ordering, ownership and failure behavior. ### Scope exclusions Retained gateway, cluster, supervisor, shared/broker ownership and extension-manager fields are not a supported hosted product API. Legacy secret-backend strategy fields are separate from the managed YAML format below. Neither permissive unknown keys nor a retained schema field makes a backend qualified. Internal daemon, guest and compiler transport types are not public API specifications. ## Managed environment YAML Files such as `.hack/hack.env.default.yaml` use `values`, not the older JSON `vars` format. Use `hack env` to manage values and [Share environment and secrets](/docs/v4/guides/share-environment) for key handling. Examples must use placeholders, never real secret values. | Field | Type / requirement | | --- | --- | | `version` | literal 1; required | | `environment` | string; optional; reader falls back to selected file/layer environment | | `secretsprovider` | literal project_key; required | | `values` | scope-to-entry map; required object | | `values.{scope}` | key-to-value map; each scope must be an object; omitted global normalized to {} | | `values.{scope}.{KEY}` | string \| number \| boolean \| secure object; null rejected by parser; no tombstone support in this pinned format | | `values.{scope}.{KEY}.secure` | nonempty string; required for object-valued stored entry; ciphertext format is interpreted elsewhere | `version: 1`, `secretsprovider: project_key`, and an object `values` are required. Each scope is an object. Scope names match `^[a-z0-9][a-z0-9._-]*$`; keys match `^[A-Z_][A-Z0-9_]*$`. Missing `values.global` becomes an empty object. The environment falls back to the selected layer; an example containing `environment: default` does not establish a universal default. Secure values require a nonempty `secure` string; valid shape alone does not prove decryption or key availability. This version rejects YAML null values. Do not copy null-removal examples from v5. The parser selects recognized fields; this is not a closed JSON-schema promise. The legacy `hack.env.json` schema describes a different file format. ## Branch registry `.hack/hack.branches.json` records CLI-managed branch metadata, not live container ownership. Use branch commands rather than hand-editing runtime directories. | Field | Type | Schema requirement | Constraints | | --- | --- | --- | --- | | `$schema` | `string` | Optional | `{}` | | `version` | `integer` | Required | `{"const":1}` | | `branches` | `array` | Required | `{}` | | `branches[].name` | `string` | Required | `{"minLength":1}` | | `branches[].slug` | `string` | Required | `{"pattern":"^[a-z0-9][a-z0-9-]*$","minLength":1}` | | `branches[].note` | `string` | Optional | `{}` | | `branches[].created_at` | `string` | Optional | `{"format":"date-time"}` | | `branches[].last_used_at` | `string` | Optional | `{"format":"date-time"}` | `name` is the human/Git branch name; `slug` is its runtime-safe identifier. `note` is an annotation. Usage updates fill a missing `created_at` and refresh `last_used_at`; neither timestamp proves a running instance or permits deleting data. A missing registry starts empty. Invalid JSON is reported. The parser drops invalid entries and narrows recognized fields, so it does not enforce every schema pattern/date format/unknown-key constraint. --- # MCP fields and results Exact tool inputs for v4.2.4. Start with [Agent integrations](/docs/v4/integrations) for setup. These are MCP JSON input names, not CLI flag spellings. Registration does not establish backend compatibility. A successful command result is not application health or readiness. ## Input rules Schema-optional selectors can still have conditional requirements. `hack.project.init` requires `path` or `repoRoot`. Do not provide conflicting selectors. `service` and `services`, `compose` and `loki`, profiles and runtime selection interact through the command handler. The schema does not promise every combination succeeds. Run timeout defaults to 120000 ms. Init uses a 180000 ms child timeout and exposes no timeout input. Log tail collection defaults to 200 events and 5000 ms. These are handler fallbacks, not schema defaults. An omitted log `tail` can be forwarded to the CLI, which has its own default. Numeric input declarations use `z.number()` in this version. Do not assume the later positive-integer ceilings or typed pre-spawn errors from v5. ## `hack.projects.list` [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/mcp/server.ts#L161) | Input | Presence | Type / validation | Meaning | | --- | --- | --- | --- | | `filter` | Optional | `string` | Filter by project name | | `includeGlobal` | Optional | `boolean` | Include global infra projects | | `includeUnregistered` | Optional | `boolean` | Include unregistered compose projects | ## `hack.project.status` [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/mcp/server.ts#L204) | Input | Presence | Type / validation | Meaning | | --- | --- | --- | --- | | `projectName` | Optional | `string` | Registered project name (from ~/.hack/projects.json) | | `repoRoot` | Optional | `string` | Repo root path (absolute or relative) | | `path` | Optional | `string` | Path inside a repo (absolute or relative) | | `branch` | Optional | `string` | Branch/worktree name | | `profiles` | Optional | `string[]` | Compose profile names | ## `hack.project.up` [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/mcp/server.ts#L245) | Input | Presence | Type / validation | Meaning | | --- | --- | --- | --- | | `projectName` | Optional | `string` | Registered project name (from ~/.hack/projects.json) | | `repoRoot` | Optional | `string` | Repo root path (absolute or relative) | | `path` | Optional | `string` | Path inside a repo (absolute or relative) | | `branch` | Optional | `string` | Branch/worktree name | | `profiles` | Optional | `string[]` | Compose profile names | ## `hack.project.down` [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/mcp/server.ts#L283) | Input | Presence | Type / validation | Meaning | | --- | --- | --- | --- | | `projectName` | Optional | `string` | Registered project name (from ~/.hack/projects.json) | | `repoRoot` | Optional | `string` | Repo root path (absolute or relative) | | `path` | Optional | `string` | Path inside a repo (absolute or relative) | | `branch` | Optional | `string` | Branch/worktree name | | `profiles` | Optional | `string[]` | Compose profile names | ## `hack.project.restart` [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/mcp/server.ts#L320) | Input | Presence | Type / validation | Meaning | | --- | --- | --- | --- | | `projectName` | Optional | `string` | Registered project name (from ~/.hack/projects.json) | | `repoRoot` | Optional | `string` | Repo root path (absolute or relative) | | `path` | Optional | `string` | Path inside a repo (absolute or relative) | | `branch` | Optional | `string` | Branch/worktree name | | `profiles` | Optional | `string[]` | Compose profile names | ## `hack.project.run` [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/mcp/server.ts#L357) | Input | Presence | Type / validation | Meaning | | --- | --- | --- | --- | | `projectName` | Optional | `string` | Registered project name (from ~/.hack/projects.json) | | `repoRoot` | Optional | `string` | Repo root path (absolute or relative) | | `path` | Optional | `string` | Path inside a repo (absolute or relative) | | `branch` | Optional | `string` | Branch/worktree name | | `profiles` | Optional | `string[]` | Compose profile names | | `service` | Required | `string` | Compose service name | | `cmd` | Optional | `string[]` | Command arguments | | `workdir` | Optional | `string` | Working directory inside container | | `timeoutMs` | Optional | `number` | Command timeout in ms | ## `hack.project.logs.snapshot` [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/mcp/server.ts#L405) | Input | Presence | Type / validation | Meaning | | --- | --- | --- | --- | | `projectName` | Optional | `string` | Registered project name (from ~/.hack/projects.json) | | `repoRoot` | Optional | `string` | Repo root path (absolute or relative) | | `path` | Optional | `string` | Path inside a repo (absolute or relative) | | `branch` | Optional | `string` | Branch/worktree name | | `profiles` | Optional | `string[]` | Compose profile names | | `service` | Optional | `string` | Single service name | | `services` | Optional | `string` | Multiple service names | | `query` | Optional | `string` | Raw LogQL selector/query | | `loki` | Optional | `boolean` | Force Loki backend | | `compose` | Optional | `boolean` | Force docker compose backend | | `tail` | Optional | `number` | Tail last N log lines | | `since` | Optional | `string` | Start time (RFC3339 or duration) | | `until` | Optional | `string` | End time (RFC3339 or duration) | Tool-specific emitted data fields: | Field | Type | Presence | | --- | --- | --- | | `data.events` | `LogStreamEvent[]` | Present in source shape | | `data.count` | `number` | Present in source shape | ## `hack.project.logs.tail` [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/mcp/server.ts#L477) | Input | Presence | Type / validation | Meaning | | --- | --- | --- | --- | | `projectName` | Optional | `string` | Registered project name (from ~/.hack/projects.json) | | `repoRoot` | Optional | `string` | Repo root path (absolute or relative) | | `path` | Optional | `string` | Path inside a repo (absolute or relative) | | `branch` | Optional | `string` | Branch/worktree name | | `profiles` | Optional | `string[]` | Compose profile names | | `service` | Optional | `string` | Single service name | | `services` | Optional | `string` | Multiple service names | | `query` | Optional | `string` | Raw LogQL selector/query | | `loki` | Optional | `boolean` | Force Loki backend | | `compose` | Optional | `boolean` | Force docker compose backend | | `tail` | Optional | `number` | Tail last N log lines | | `since` | Optional | `string` | Start time (RFC3339 or duration) | | `until` | Optional | `string` | End time (RFC3339 or duration) | | `maxEvents` | Optional | `number` | Max events to collect | | `maxMs` | Optional | `number` | Max duration in ms | Tool-specific emitted data fields: | Field | Type | Presence | | --- | --- | --- | | `data.events` | `LogStreamEvent[]` | Present in source shape | | `data.count` | `number` | Present in source shape | | `data.stop_reason` | `string (collector stop reason)` | Present in source shape | | `data.duration_ms` | `number` | Present in source shape | ## `hack.project.open` [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/mcp/server.ts#L559) | Input | Presence | Type / validation | Meaning | | --- | --- | --- | --- | | `projectName` | Optional | `string` | Registered project name (from ~/.hack/projects.json) | | `repoRoot` | Optional | `string` | Repo root path (absolute or relative) | | `path` | Optional | `string` | Path inside a repo (absolute or relative) | | `branch` | Optional | `string` | Branch/worktree name | | `target` | Optional | `string` | Target host/subdomain or URL | ## `hack.project.init` [source](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/mcp/server.ts#L600) | Input | Presence | Type / validation | Meaning | | --- | --- | --- | --- | | `projectName` | Optional | `string` | Registered project name (from ~/.hack/projects.json) | | `repoRoot` | Optional | `string` | Repo root path (absolute or relative) | | `path` | Optional | `string` | Path inside a repo (absolute or relative) | | `name` | Optional | `string` | Project slug | | `devHost` | Optional | `string` | DEV_HOST override | | `oauth` | Optional | `boolean` | Enable OAuth alias host | | `oauthTld` | Optional | `string` | OAuth alias TLD | | `manual` | Optional | `boolean` | Skip discovery and generate a minimal compose | | `noDiscovery` | Optional | `boolean` | Skip discovery even if available | ## Prompt arguments `hack-init` is a prompt, separate from `hack.project.init`. Mode defaults to existing-project. Prompt hints do not become init tool inputs. | Argument | Presence | Declaration | | --- | --- | --- | | `arguments.mode` | Optional | `string` | | `arguments.projectName` | Optional | `string` | | `arguments.devHost` | Optional | `string` | ## Common result The emitted MCP transport subset is `content[]` with `type`/`text`, `structuredContent`, and `isError` on failure. The table describes the common structured payload, not every SDK extension. Optional `data` is declared unknown; it is not a machine-validated closed nested schema. | Field | Type | Presence | | --- | --- | --- | | `structuredContent.ok` | `boolean` | Required | | `structuredContent.command` | `string` | Required | | `structuredContent.exitCode` | `number` | Required | | `structuredContent.stdout` | `string` | Required | | `structuredContent.stderr` | `string` | Required | | `structuredContent.data` | `unknown` | Optional | Up/down/restart/init do not return a typed data status or readiness object. Open returns `data.url` without launching a browser. Status forwards the selected command JSON; a Compose result has project/branch/composeProject/items, and engine-specific item fields are open. Projects list forwards public CLI inventory JSON; consumers must tolerate version/runtime-specific metadata. Run has no data object. Snapshot returns events/count. Tail adds stop_reason/duration_ms. Its maxEvents limit counts collected parsed events, unlike v5's type:log-only counter. Refusals use the common failure payload/stderr; this version does not promise v5's typed error object. ## Log event fields These are source types, not a closed validator for every parsed JSON line. Event type is start/log/heartbeat/error/end. Labels and fields are application-owned string maps. Do not enumerate application log keys as Hack API fields. | Field | Type | Presence | | --- | --- | --- | | `data.events[].type` | `LogStreamEventType` | Required in declared source type | | `data.events[].ts` | `string` | Required in declared source type | | `data.events[].project` | `string` | Optional | | `data.events[].backend` | `LogStreamBackend` | Optional | | `data.events[].branch` | `string` | Optional | | `data.events[].services` | `readonly string[]` | Optional | | `data.events[].follow` | `boolean` | Optional | | `data.events[].since` | `string` | Optional | | `data.events[].until` | `string` | Optional | | `data.events[].entry` | `LogJsonEntry` | Optional | | `data.events[].message` | `string` | Optional | | `data.events[].reason` | `string` | Optional | | `data.events[].entry.source` | `"compose" \\| "loki"` | Required in declared source type | | `data.events[].entry.message` | `string` | Required in declared source type | | `data.events[].entry.raw` | `string` | Required in declared source type | | `data.events[].entry.stream` | `"stdout" \\| "stderr"` | Optional | | `data.events[].entry.project` | `string` | Optional | | `data.events[].entry.service` | `string` | Optional | | `data.events[].entry.instance` | `string` | Optional | | `data.events[].entry.labels` | `Record` | Optional | | `data.events[].entry.timestamp` | `string` | Optional | | `data.events[].entry.timestamp_ns` | `string` | Optional | | `data.events[].entry.level` | `LogLevel` | Optional | | `data.events[].entry.fields` | `Record` | Optional | ## Contract boundaries Nested engine/project/diagnostic variants and arbitrary application data remain open. Inspect the pinned public command source when handling a new variant; do not depend on private daemon/guest/compiler protocols. This field reference is source-reviewed and does not claim client-loading or cloud execution qualification. --- # Command and output contracts Pinned source: `91b14bf0abb17602142425de0d02628a3e8a2615`. This supplements the [generated command reference](/docs/v4/reference/cli). Command registration and document shape do not establish backend admission. ## Scope and coverage The recursive public inventory has **84 leaves**, **284 leaf-owned option occurrences**, and **536 effective option occurrences**, including three global/built-in flags per leaf. The three additional leaf sections below complete the pinned generated reference within this public scope. No declared effective flags or short aliases are missing from matching sections; generic value placeholders explain initial spelling-only differences. Counts are occurrences, not unique names. Parent namespaces are not leaves. Retired gateway/node/remote/dispatch, hosted account/team/Tickets, internal helpers, extension dispatch and fun commands are excluded. SSH remote access is excluded. Retained fields within local commands do not establish support for retired backends. ## Global flags and parsing Every leaf accepts `--no-interactive`, `--help, -h`, and `--version, -v`. The first also has `HACK_NO_INTERACTIVE=1`; it applies documented defaults or refuses required interaction. Help/version return early with status 0. These are the only inherited flags: parent options are not inherited. Omitted booleans parse false; omitted strings/numbers parse undefined. Handler/config fallbacks are separate. A nonboolean OptionSpec defaultValue supplies a value when the flag is present without its value; it is not an unconditional omitted-flag default. ## Additional command details ### `hack project owner show` Show the local ownership metadata for the current project. Arguments: none. | Option | Type | Meaning / declared fallback | | --- | --- | --- | | `--path, -p ` | string | Run a project command against a repo path (overrides cwd search) | | `--project ` | string | Target a registered project by name (from ~/.hack/projects.json) | | `--json` | boolean | Output JSON (machine-readable) | | `--no-interactive` | boolean | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | boolean | Show help | | `--version, -v` | boolean | Show version | Source: `src/commands/project-admin.ts:16 (ownerShowSpec)`. No command alias is declared. ### `hack env backend status` Show configured env/secret backend strategy. Arguments: none. | Option | Type | Meaning / declared fallback | | --- | --- | --- | | `--json` | boolean | Output JSON (machine-readable) | | `--no-interactive` | boolean | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | boolean | Show help | | `--version, -v` | boolean | Show version | Source: `src/commands/env.ts:375 (backendStatusSpec)`. No command alias is declared. ### `hack env backend use ` Select env/secret backend strategy. Arguments: `backend` — required. | Option | Type | Meaning / declared fallback | | --- | --- | --- | | `--provider ` | string | Cloud secret provider when backend is cloud | | `--store-path ` | string | Encrypted file path when backend is encrypted_file | | `--key-path ` | string | Stable key file path when backend is encrypted_file | | `--provision-key` | boolean | Provision a stable key file for encrypted_file backend | | `--secret-project ` | string | Optional cloud project/account identifier | | `--secret-prefix ` | string | Optional cloud secret name prefix | | `--json` | boolean | Output JSON (machine-readable) | | `--no-interactive` | boolean | Never prompt: apply documented defaults or fail with E_INTERACTIVE_REQUIRED (also via HACK_NO_INTERACTIVE=1) | | `--help, -h` | boolean | Show help | | `--version, -v` | boolean | Show version | Source: `src/commands/env.ts:384 (backendUseSpec)`. No command alias is declared. ## Complete public leaf and flag inventory “Present” means a matching usage section; flags were compared separately. It does not prove every handler default is described. All rows also accept the three global/built-in flags above. Arguments are exact spec names. | Leaf usage | Own flags (aliases and value hints) | Pinned generated section | | --- | --- | --- | | `hack global install` | none | Present | | `hack global up` | none | Present | | `hack global down` | none | Present | | `hack global status` | `--json` | Present | | `hack global logs [service]` | `--follow, -f`; `--no-follow`; `--tail `; `--pretty` | Present | | `hack global ca` | `--print` | Present | | `hack global cert ` | `--install`; `--out ` | Present | | `hack global trust` | none | Present | | `hack global logs-reset` | none | Present | | `hack global authorize` | none | Present | | `hack status` | `--project `; `--include-global`; `--all`; `--meta`; `--json` | Present | | `hack usage` | `--project `; `--details`; `--include-global`; `--watch`; `--interval `; `--no-host`; `--json` | Present | | `hack projects prune` | `--project `; `--include-global`; `--dry-run`; `--json` | Present | | `hack project owner show` | `--path, -p `; `--project `; `--json` | Missing; drafted above | | `hack init` | `--path, -p `; `--manual`; `--auto`; `--name `; `--dev-host `; `--oauth`; `--oauth-tld `; `--no-discovery`; `--with ` | Present | | `hack up [services...]` | `--path, -p `; `--project `; `--env `; `--branch `; `--detach, -d`; `--profile `; `--target `; `--json` | Present | | `hack down` | `--path, -p `; `--project `; `--env `; `--branch `; `--profile `; `--target `; `--prune-caches`; `--yes`; `--json` | Present | | `hack restart [services...]` | `--path, -p `; `--project `; `--env `; `--branch `; `--profile `; `--target `; `--json` | Present | | `hack ps` | `--path, -p `; `--project `; `--branch `; `--profile `; `--json` | Present | | `hack tui` | `--path, -p `; `--project ` | Present | | `hack run [cmd...]` | `--path, -p `; `--project `; `--env `; `--branch `; `--workdir `; `--profile ` | Present | | `hack exec [cmd...]` | `--path, -p `; `--project `; `--env `; `--branch `; `--workdir `; `--profile ` | Present | | `hack logs [service]` | `--path, -p `; `--project `; `--branch `; `--follow, -f`; `--no-follow`; `--tail `; `--pretty`; `--json`; `--profile `; `--compose`; `--loki`; `--services `; `--query `; `--since `; `--until ` | Present | | `hack open [target]` | `--path, -p `; `--project `; `--branch `; `--prefer `; `--json` | Present | | `hack branch add ` | `--path, -p `; `--project `; `--note ` | Present | | `hack branch list` | `--path, -p `; `--project ` | Present | | `hack branch remove ` | `--path, -p `; `--project ` | Present | | `hack branch open ` | `--path, -p `; `--project `; `--prefer ` | Present | | `hack log-pipe` | `--format `; `--stream ` | Present | | `hack doctor` | `--path, -p `; `--fix`; `--migrate-env-config`; `--json` | Present | | `hack crash-capture` | `--path, -p `; `--since ` | Present | | `hack daemon start` | `--foreground` | Present | | `hack daemon stop` | none | Present | | `hack daemon restart` | none | Present | | `hack daemon status` | `--json` | Present | | `hack daemon metrics` | none | Present | | `hack daemon logs` | `--tail ` | Present | | `hack daemon clear` | none | Present | | `hack daemon install` | `--run-at-load`; `--no-run-at-load`; `--gui-only`; `--no-gui-only` | Present | | `hack daemon uninstall` | none | Present | | `hack secrets set [name]` | `--service ` | Present | | `hack secrets get [name]` | `--service ` | Present | | `hack secrets delete [name]` | `--service ` | Present | | `hack env list` | `--path, -p `; `--project `; `--env `; `--json`; `--show-secrets`; `--service ` | Present | | `hack env explain ` | `--path, -p `; `--project `; `--env `; `--json`; `--service `; `--target ` | Present | | `hack env apply` | `--path, -p `; `--project `; `--env `; `--json`; `--service ` | Present | | `hack env add [key] [value]` | `--path, -p `; `--project `; `--env `; `--secret`; `--local`; `--service ` | Present | | `hack env set [key] [value]` | `--path, -p `; `--project `; `--env `; `--secret`; `--local`; `--service ` | Present | | `hack env materialize` | `--path, -p `; `--project `; `--env `; `--service ` | Present | | `hack env exec [command...]` | `--path, -p `; `--project `; `--env `; `--service `; `--target `; `--shell `; `--timeout `; `--lifetime ` | Present | | `hack env shell` | `--path, -p `; `--project `; `--env `; `--service `; `--target ` | Present | | `hack env unset [key]` | `--path, -p `; `--project `; `--env `; `--local`; `--service ` | Present | | `hack env backend status` | `--json` | Missing; drafted above | | `hack env backend use ` | `--provider `; `--store-path `; `--key-path `; `--provision-key`; `--secret-project `; `--secret-prefix `; `--json` | Missing; drafted above | | `hack host ps` | `--project `; `--json` | Present | | `hack host exec [command...]` | `--path, -p `; `--project `; `--env `; `--scope `; `--target `; `--shell `; `--timeout `; `--lifetime ` | Present | | `hack host shell` | `--path, -p `; `--project `; `--env `; `--scope `; `--target ` | Present | | `hack config get ` | `--path, -p `; `--project `; `--global` | Present | | `hack config set ` | `--path, -p `; `--project `; `--global` | Present | | `hack mcp serve` | none | Present | | `hack mcp install` | `--scope `; `--path, -p `; `--all`; `--cursor`; `--claude`; `--codex`; `--docs`; `--agents-md`; `--claude-md` | Present | | `hack mcp print` | `--scope `; `--path, -p `; `--all`; `--cursor`; `--claude`; `--codex` | Present | | `hack setup tmux` | `--check`; `--remove` | Present | | `hack setup cursor` | `--path, -p `; `--global`; `--check`; `--remove` | Present | | `hack setup claude` | `--path, -p `; `--global`; `--check`; `--remove` | Present | | `hack setup codex` | `--path, -p `; `--global`; `--check`; `--remove` | Present | | `hack setup agents` | `--path, -p `; `--all`; `--agents-md`; `--claude-md`; `--check`; `--remove` | Present | | `hack setup sync` | `--path, -p `; `--global`; `--all-scopes`; `--check`; `--remove` | Present | | `hack setup mcp` | `--path, -p `; `--global`; `--all`; `--cursor`; `--claude`; `--codex`; `--check`; `--remove` | Present | | `hack session list` | none | Present | | `hack session start [project]` | `--up`; `--new`; `--name `; `--detach, -d`; `--env `; `--service ` | Present | | `hack session stop ` | none | Present | | `hack session attach ` | none | Present | | `hack session exec ` | `--env `; `--service ` | Present | | `hack session panes ` | `--json`; `--pretty` | Present | | `hack session capture ` | `--target `; `--lines `; `--json`; `--pretty` | Present | | `hack session tail ` | `--target `; `--lines `; `--interval-ms `; `--max-ms `; `--json`; `--pretty` | Present | | `hack agent prime` | `--check` | Present | | `hack agent patterns` | none | Present | | `hack agent init` | `--path, -p `; `--client, -c ` | Present | | `hack agent onboard` | `--path, -p ` | Present | | `hack update` | `--check`; `--yes`; `--tag `; `--json` | Present | | `hack version` | none | Present | | `hack help [path...]` | `--all` | Present | ## Declared defaults and option semantics This table preserves declarations/descriptions that state defaults. Other handler/backend defaults are not implied by absence here. | Leaf / option | Source declaration | | --- | --- | | `hack global logs [service]` / `--follow, -f` | Follow logs (default for `hack logs`) | | `hack global logs [service]` / `--tail ` | Tail last N log lines Flag-present fallback: `200`. | | `hack global cert ` / `--out ` | Directory for generated cert/key (default: ~/.hack/certs) | | `hack init` / `--auto` | Run non-interactive init with sensible defaults | | `hack init` / `--name ` | Project slug (default: repo name) | | `hack init` / `--oauth-tld ` | OAuth alias TLD override (default: gy) | | `hack logs [service]` / `--follow, -f` | Follow logs (default for `hack logs`) | | `hack logs [service]` / `--tail ` | Tail last N log lines Flag-present fallback: `200`. | | `hack log-pipe` / `--format ` | How to parse incoming lines from stdin Flag-present fallback: `auto`. | | `hack log-pipe` / `--stream ` | Treat stdin as stdout or stderr (stderr forces ERROR level + writes to stderr) Flag-present fallback: `stdout`. | | `hack daemon logs` / `--tail ` | Tail last N log lines Flag-present fallback: `200`. | | `hack daemon install` / `--gui-only` | Only run in GUI sessions (default) | | `hack secrets set [name]` / `--service ` | Override Bun.secrets service name Flag-present fallback: `hack-cli`. | | `hack secrets get [name]` / `--service ` | Override Bun.secrets service name Flag-present fallback: `hack-cli`. | | `hack secrets delete [name]` / `--service ` | Override Bun.secrets service name Flag-present fallback: `hack-cli`. | | `hack env explain ` / `--target ` | Env view for host commands (default: host rewrites container-oriented addresses for local host execution) | | `hack env exec [command...]` / `--target ` | Env view for host commands (default: host rewrites container-oriented addresses for local host execution) | | `hack env exec [command...]` / `--lifetime ` | Declare intended lifetime for diagnostics (default: command; does not detach) | | `hack env shell` / `--target ` | Env view for host commands (default: host rewrites container-oriented addresses for local host execution) | | `hack host exec [command...]` / `--target ` | Env view for host commands (default: host rewrites container-oriented addresses for local host execution) | | `hack host exec [command...]` / `--lifetime ` | Declare intended lifetime for diagnostics (default: command; does not detach) | | `hack host shell` / `--target ` | Env view for host commands (default: host rewrites container-oriented addresses for local host execution) | | `hack mcp install` / `--scope ` | Write MCP config to user or project scope Flag-present fallback: `user`. | | `hack mcp print` / `--scope ` | Write MCP config to user or project scope Flag-present fallback: `user`. | | `hack session start [project]` / `--new` | Create an isolated workspace instead of reusing the default project workspace | | `hack session capture ` / `--target ` | Tmux pane target (default: active pane) | | `hack session capture ` / `--lines ` | Number of lines to capture Flag-present fallback: `200`. | | `hack session tail ` / `--target ` | Tmux pane target (default: active pane) | | `hack session tail ` / `--lines ` | Number of lines to capture Flag-present fallback: `200`. | | `hack session tail ` / `--interval-ms ` | Polling interval in milliseconds Flag-present fallback: `500`. | | `hack session tail ` / `--max-ms ` | Stop tailing after N milliseconds Flag-present fallback: `5000`. | ## Ownership inspection `project owner show` searches from cwd or `--path`, or selects a registered `--project`; do not combine path/project. Missing project and config parse failures refuse. JSON success is a bare object and exits 0: | Field | Type and meaning | | --- | --- | | `project_root` | string; resolved root | | `project_slug` | string or null; sanitized configured name, null if blank | | `ownership.mode` | local/shared | | `ownership.owner_type` | user/team/organization | | `ownership.owner_id` | string or null | | `ownership.managed_by` | local/broker | Defaults are local/user/null/local. These are retained local metadata, not hosted team/broker support. No owner mutation leaf exists here. ## Env backend strategy Status reads effective settings for cwd's project when found, global settings otherwise. It takes no project/path/env selectors. Use writes **global** settings and rereads global settings. It does not migrate YAML project-key values or establish cloud-provider qualification. Backend is required: exactly `keychain`, `encrypted_file` or `cloud`. Provider accepts exactly `aws|gcp|azure|vault` and is required for cloud even if a provider was previously configured. Invalid nonempty backend/provider is a usage error. Inputs are trimmed; empty optional paths/project/prefix are omitted. Store/key paths apply only to encrypted_file; cloud project/prefix apply only with cloud/provider. Omitted settings are retained. Provision-key defaults false and applies only to encrypted_file. Fresh schema defaults: keychain, allow_env_auth_refs true, store_plaintext_in_backend false; file path `~/.hack/secrets.enc.json`, key path `~/.hack/secrets-file.key`; cloud prefix `hack`, provider/project unspecified. These are config defaults, not flag defaults reapplied on every use. The key environment variable name is `HACK_SECRETS_FILE_KEY`. Providers describe retained compatibility strategies, not qualified cloud onboarding. Both JSON successes are bare objects and return 0: | Field | status | use | | --- | --- | --- | | `backend` | selected enum | selected enum | | `allow_env_auth_refs` | boolean | boolean | | `store_plaintext_in_backend` | boolean | boolean | | `encrypted_file` | object: string path/keyPath | same | | `encrypted_file_key_env` | string variable name | same | | `cloud` | object: optional provider/project strings, string secretPrefix; undefined properties omitted | same | | `status` | object below | absent | | `encrypted_file_key_provisioned` | absent | null or {keyPath:string, source:env/file/keychain/generated} | Status has string storage_mode/trust_model/portability/plaintext_compatibility and classification. Classification has string trust_model/custody/portability and shared_state (local_only/plaintext_compatible/portable_bundle/broker_managed). These descriptive names do not grant remote/team features. ## JSON results and exits The generated page's universal envelope claim is too broad. Decode by command and backend. The shared helper emits `{ok:true,data:T}` or `{ok:false,error:{code,message,detail?}}`; detail is unknown. Its mapper returns 0/1. Handlers can instead return child exit codes, bare objects, reports or JSON-lines. Thrown usage errors with an explicit `--json` token become E_USAGE; other thrown errors preserve HackCliError codes or become E_UNEXPECTED, with exit 1. Returning 1 directly does not automatically create an error envelope. Unknown command or namespace paths may print help and exit 1. Help/version return early with status 0, including when JSON was requested. Valid JSON alone proves neither success nor readiness. | Command | Output contract | Exit / open shape | | --- | --- | --- | | up/down/restart, retained Compose owner | shared envelope; data action (up/down/restart), project:string, branch:string/null, composeProject:string, services.{started,completed,stopped,failed}:sorted string arrays, durationMs:number; optional cacheVolumesRemoved:string[] | JSON up implies detach. Structured startup/lifecycle failures use error envelope. | | ps, Compose | bare {project,branch,composeProject,items}; branch nullable; items parsed engine records | daemon-assisted JSON may be forwarded; engine rows are open. Compose failure can return child nonzero with stderr and no success object. | | open | bare {url:string} | JSON reports URL; does not launch browser | | projects/status | bare listing below | runtime_ok false is report data, not necessarily command failure | | projects prune | shared envelope, preview/apply variants below | dry-run reports candidates; apply reports removals | | project owner show | bare ownership object above | success 0 | | env backend status/use | bare strategy objects above | success 0 | | env list | bare modern-YAML or legacy report below | raw report may include values | | env apply | forwards restart service --path repo with selected env/JSON flags | returns child restart output and exit code, not an env-list report; native subset/JSON limits still apply | | env explain | bare value-free explanation below | inspect available/scope; no value | | doctor | shared envelope with checks[], summary:string[], counts.{ok,warn,error}:numbers | can emit ok:true and exit 1 when checks contain errors | | usage | bare projects[], total nullable, host[], host_total nullable, runtime_ok:boolean, runtime_error nullable; details adds containers[] | failures exit 1; optional error string. No samples exits 0 with warning:no_usage_samples. Watch uses the interactive redraw path even with JSON selected; do not treat watch as a JSON report stream. | | global status | bare generated_at/caddy/logging/networks/gateway/summary | exits 0 even if summary health false; gateway is retained unsupported data, excluded from public contract | | daemon status | bare report below | running returns 0; starting/stale/unavailable may return 1 | | host ps | bare {generatedAt,snapshotAvailable,commands,lifecycle} | timestamp string, availability boolean; nested telemetry remains specialized | | setup sync | human status list; no JSON option at this pin | v5 JSON/target report and install-missing must not be backported | | session panes/capture/tail | JSON-lines events below | no shared envelope | | update | command-owned object with ok:boolean, string error on failure | error is not shared error.{code,message}; success varies by check/install outcome; exit follows ok | Config get has no JSON flag: non-string values serialize as JSON, strings print plainly. Daemon metrics prints retained metrics JSON without a JSON flag; nested internal transport data is not a supported general API. MCP serve speaks MCP; log-pipe formats a stream. Other leaves without JSON do not inherit it. ### Report details Direct projects/status fields: generated_at, filter, include_global, include_unregistered, include_meta, runtime_ok, runtime_error, runtime_checked_at, runtime_last_ok_at, runtime_reset_at, runtime_reset_count, runtime_reset_summary, runtime_reset_changes, runtime_last_repair_at, runtime_repair_action, runtime_repair_outcome, runtime_next_step, projects[]. Optional detail_level:summary selects summary projection. Project records use summary/full projections with optional meta. Nullable recovery metadata is not liveness proof; nested engine/meta variants remain open. Prune preview and apply are separate shapes. Apply includes runtimeOk/runtimeError, removedRegistryEntries[] (id/name/repoRoot/projectDir/reason), removedOrphanedProjects[] (project/workingDir/reason/containerCount), removedContainerCount. Preview includes dryRun:true, runtimeOk, registryCandidates[] (name/projectDir/reason), orphanedProjects[] and candidateContainerCount. It does not add runtimeError merely because apply has it. Orphan records are typed in the table below. Doctor checks contain id/status/detail/durationMs; status is ok/warn/error. summary is string[]; counts are numbers. Additional diagnostics depend on version/check and remain specialized shapes. Daemon status fields: status, running, api_ok, api_reachable, api_compatible, process_running, stale, stale_reason, issue, next_step, pid, socket_path, socket_exists, log_path, log_exists, launchd. Launchd is null or {installed,loaded,running,pid,exit_status,plist_path}. Unavailable/nullable observations must not be treated as proof of process absence or authority to signal a PID. Env explain: key:string, available/secret:boolean, format:project_env_config_v1/legacy_env_contract; environment/effective_scope/source:string|null; requested_scope:string, target:host/compose, delivered_to/precedence:string[]. It emits no value. Env list: project and env_selection (requested/default/effective selections, overlay_path, overlay_exists). Modern YAML adds format:project_env_config_v1, selected_scope, scopes, files, unknown_scopes, status/storage descriptions, vars[], missing_required. Legacy reports have storage/status, materialization and key projections. Rows in vars[] contain key/required/source/services/resolved_from/storage/value. Secret values are masked unless show-secrets is explicitly selected; ordinary plaintext is not thereby hidden. Modern reports include materialized when show-secrets is selected, otherwise materialized_keys. Legacy reports additionally contain warnings[] (kind/key/overlay_path/services/message). CLI reports differ from MCP's narrower value-free keys projection. Nested modern/legacy variants remain versioned report shapes; application values are not new stable reference keys. ## Compose/Loki log records Logs JSON is newline-delimited events, not an array or envelope. Finite snapshots and follow share vocabulary. Follow is default; no-follow requests finite output. Omitted tail falls back to 200. JSON conflicts with pretty; compose conflicts with explicit Loki selection (loki/services/query/since/until); follow with until refuses. | Event field | Presence / type | | --- | --- | | type | required start/log/heartbeat/error/end | | ts | required string; ISO generation time or log entry timestamp | | backend | optional in declared type; builders include compose/loki | | project/branch | optional strings, omitted without context | | services | optional string[], start context when supplied | | follow | optional boolean; start builder includes it | | since/until | optional strings, start context when supplied | | entry | optional LogJsonEntry; log includes it | | message | optional string; error includes it | | reason | optional string; end includes nonempty reason | Compose ends with eof or exit:. Loki finite snapshots can end without reason; handled query failure emits error/end(error), follow ends closed/error. Error can precede start. Heartbeat has a builder, but these emitters do not establish periodic delivery. End settles a stream, not a workload. | Entry field | Type / meaning | | --- | --- | | source | required compose/loki | | message/raw | required strings: parsed message/original line | | stream | optional stdout/stderr, Compose | | project/service/instance | optional strings from context/prefix/labels | | labels | optional string-to-string map, Loki | | timestamp | optional ISO string | | timestamp_ns | optional nanosecond timestamp string, not number | | level | optional debug/info/warn/error after normalization | | fields | optional string-to-string map of application fields | Optional fields are omitted, not declared nullable. Map keys are open application data. The TypeScript declaration is not a runtime-validated closed JSON schema. Global logs has no JSON option. ## Session JSON-lines Panes/capture/tail are tmux inspection surfaces and default to JSON unless pretty is selected. Capture/tail default to active target and 200 lines. Tail defaults interval-ms to 500 and max-ms to 5000. JSON and pretty together refuse. Panes snapshots emit start, log per pane, end(snapshot); capture emits log per captured line and end(snapshot). Tail emits changes and a finite budget ends with timeout. Refusals can precede event creation. All events have type start/log/error/end, ts:string (ISO), session:string. Pane logs add pane:{target:string,active:boolean,windowIndex:number,windowName:string,paneIndex:number,command:string,path:string|null}. Capture/tail events also have target:string, lines:number, follow:boolean, optional intervalMs/maxMs:number. Log adds line:string; error adds message:string; end may add reason:string. These are separate from project log entry/backend events. ## Remaining limits Leaf/flag presence is reconciled. Handler defaults outside the reviewed tables are not an exhaustive semantic audit. Engine rows, optional diagnostic subtypes, listing metadata, setup target results, update success variants, nested env variants and candidate reports remain bounded open/specialized shapes. No closed schema, backend parity, client-loading proof or installed runtime acceptance is claimed. Config-file/MCP field work remains in the separate audit. Private compiler/daemon/guest/provider protocols and retired APIs are excluded. V4 owner selection sanitizes a supplied registered name before lookup. V4 has no DNS leaves, authored-native contract, config validate/plan/import/adopt leaves or project task leaves. Do not copy v5 native limits or sensitive env-get error suppression into v4. ## Parent command sections These sections are also present in the pinned reference. Some parents handle direct invocation (for example projects/session); namespace options do not pass to children. Counts above count terminal leaves only. | Section | Own options; all also have global/built-ins | | --- | --- | | `hack project` | | | `hack project owner` | | | `hack branch` | | | `hack config` | | | `hack session` | | | `hack global` | | | `hack projects` | `--project `; `--details`; `--summary`; `--timings`; `--no-daemon`; `--meta`; `--include-global`; `--all`; `--json` | | `hack daemon` | | | `hack mcp` | | | `hack setup` | | | `hack agent` | | | `hack secrets` | `--service ` | | `hack env` | | | `hack env backend` | | | `hack host` | | ## Stable shared error codes `E_DOCKER_UNAVAILABLE`, `E_GLOBAL_INFRA_DOWN`, `E_CONFIG_PARSE`, `E_CONFIG_INVALID`, `E_PROJECT_NOT_FOUND`, `E_SERVICE_NOT_FOUND`, `E_COMPOSE_FAILED`, `E_STARTUP_INCOMPLETE`, `E_DEPENDENCY_BOOTSTRAP_FAILED`, `E_STARTUP_TIMEOUT`, `E_LIFECYCLE_FAILED`, `E_ENV_KEY_MISSING`, `E_PERMISSION`, `E_INTERACTIVE_REQUIRED`, `E_USAGE`, `E_UNEXPECTED`. Optional error.detail is unknown; direct-return failures need not use this envelope. Update success fields: ok:true, current/latest:string, updateAvailable/installed:boolean, target:{platform:string,arch:string}, binaryPath/assetsDir:string, optional mutagen provisioning report. Handled failure is {ok:false,error:string}. ## Typed corrections for generated value placeholders These were display-only mismatches, not missing flags. The generated `` placeholder means a value is required when the flag is used; none of these options has a short alias or an OptionSpec defaultValue. | Command / exact spelling | Type | Omission / handler behavior | | --- | --- | --- | | `hack usage --interval ` | number, milliseconds | Omitted: configured usage.watchIntervalMs. Finite positive input is floored and clamped to at least 250 ms; nonpositive/invalid resolved interval falls back to 2000 ms. Watch uses human redraw output. | | `hack session start [project] --name ` | string; workspace suffix | Omitted: reuse base workspace unless --new requests the next numeric suffix. A truthy supplied suffix is passed to the session-name builder; it is not a project selector. | ## Prune preview field types The preview uses the shared success envelope. Its data object is: | Field | Type / meaning | | --- | --- | | dryRun | literal true | | runtimeOk | boolean; whether runtime inventory succeeded | | registryCandidates | array of {name:string, projectDir:string, reason:string} | | orphanedProjects | array of {project:string, workingDir:string|null, reason:string, containerIds:readonly string[]} | | candidateContainerCount | number; sum of orphan container IDs | Preview omits runtimeError. A successful envelope describes a completed preview, not a guarantee that the runtime is healthy. Apply has the distinct removal fields already listed above. Neither form is permission to delete resources. --- # Project inventory and environment reports Public report shapes at `91b14bf0abb17602142425de0d02628a3e8a2615`. This page describes CLI projections, not private daemon/compiler/guest protocols. See [Command and output contracts](/docs/v4/reference/command-contracts) for envelope and exit semantics. v4 has no MCP env.keys/env.explain registrations. Use the version-specific CLI inspection contract rather than assuming v5 tools exist. ## Project inventory `hack projects --json` and status inventory emit a bare report. `--summary` selects the summary projection; `--meta` adds optional metadata. Missing or null observations mean unavailable/unknown, not proof that resources or processes do not exist. Runtime health in report data is separate from exit status. | Selection | Report effect | | --- | --- | | Default full listing | projects[] contains serialized project views, runtime observations, sessions, worktrees and lifecycle descriptions | | --summary | detail_level is summary; rows contain identity/status and counts instead of full nested runtime views | | --meta | meta is present on each row; it may be null | ### Project metadata types The following declarations are copied from the pinned public metadata producers. Optional properties may be omitted. Nullable properties are present but may be null. Raw metadata contains repository paths and command descriptions; it is not a redacted sharing format. Ownership shared/broker names are retained compatibility metadata, not hosted team management or an access-control API. [Pinned src/lib/project-meta.ts](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/lib/project-meta.ts). ```ts export type GitWorktreeMeta = { readonly path: string; readonly head: string | null; readonly branch: string | null; readonly detached: boolean; }; export type GitMeta = { readonly isRepo: boolean; readonly head: string | null; readonly branch: string | null; readonly detached: boolean | null; readonly dirty: boolean | null; readonly localBranchCount: number | null; readonly worktrees: readonly GitWorktreeMeta[] | null; readonly error: string | null; }; export type HackBranchesMeta = { readonly path: string; readonly parseError: string | null; readonly branches: readonly BranchEntry[]; }; export type EnvVarMeta = { readonly key: string; readonly required: boolean; readonly source: HackEnvSource; readonly services: readonly string[] | null; readonly description?: string; readonly resolvedFrom: | "dotenv" | "process" | "keychain" | "portable_backend" | null; readonly hasValue: boolean; }; export type EnvMeta = { readonly contractPath: string; readonly contractExists: boolean; readonly contractParseError: string | null; readonly vars: readonly EnvVarMeta[]; readonly missingRequired: readonly string[]; }; export type SessionsMeta = { readonly sessions: readonly MuxSession[]; }; export type ComposeBuildServiceMeta = { readonly service: string; readonly build: boolean; readonly context: string | null; readonly dockerfile: string | null; readonly dockerfilePath: string | null; readonly dockerfileExists: boolean | null; }; export type ComposeBuildMeta = { readonly services: readonly ComposeBuildServiceMeta[]; }; export type ProjectMeta = { readonly ownership: ProjectOwnershipConfig | null; readonly configError: string | null; readonly git: GitMeta; readonly hackBranches: HackBranchesMeta; readonly env: EnvMeta; readonly sessions: SessionsMeta; readonly composeBuild: ComposeBuildMeta; }; ``` [Pinned src/lib/branches.ts](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/lib/branches.ts). ```ts export type BranchEntry = { readonly name: string; readonly slug: string; readonly note?: string; readonly created_at?: string; readonly last_used_at?: string; }; ``` [Pinned src/mux/mux-backend.ts](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/mux/mux-backend.ts). ```ts export type MuxBackendName = "tmux" | "zellij"; export type MuxSession = { readonly backend: MuxBackendName; readonly name: string; readonly attached: boolean | null; readonly path: string | null; readonly windows: number | null; readonly createdAt: string | null; }; ``` [Pinned src/lib/hack-env.ts](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/lib/hack-env.ts). ```ts export type HackEnvSource = "plain_env" | "keychain"; ``` [Pinned src/lib/project.ts](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/lib/project.ts). ```ts export type ProjectOwnershipMode = "local" | "shared"; export type ProjectOwnershipOwnerType = "user" | "team" | "organization"; export type ProjectOwnershipManager = "local" | "broker"; export interface ProjectOwnershipConfig { readonly mode: ProjectOwnershipMode; readonly ownerType: ProjectOwnershipOwnerType; readonly ownerId: string | null; readonly managedBy: ProjectOwnershipManager; } ``` ### Serialized runtime observations The public runtime projection uses snake_case names and arrays, not the internal Map representation. It contains project:string, working_dir:string|null and services[]. Each service has service:string and containers[]. Container fields: id/state/status/name/ports:string; working_dir/image:string|null; labels:string-map|null; mounts[] and networks[]. Mount fields: type/source/destination/mode:string, name:string|null, rw:boolean|null. Network fields: name:string, ip_address/gateway:string|null, aliases:string[]. Labels and engine state strings remain open values. The raw ps items[] engine report is a different surface from this normalized projects[].runtime projection. Do not infer that an open engine report makes Hack-owned wrapper fields unknowable. ### Sessions and lifecycle in full project rows Full-row sessions[] uses name:string, backend:tmux|zellij, source:hack|external, attached:boolean, path:string|null, windows:number|null and created_at:number|null. This numeric creation observation is distinct from the metadata MuxSession.createdAt string|null above; do not silently convert one contract into the other. worktrees is null or an array of path:string, branch:string|null and last_seen_at:string. lifecycle is null or an object with up_before/up_after/down_before/down_after arrays and processes[]. Hook rows carry name:string|null, command:string, cwd:string|null and service:string; persistent:true is emitted only when true. Process rows require name/command/service:string and cwd:string|null. ## Environment list reports Raw CLI env reports can contain values. Default secret masking does not make an entire report value-free: plaintext values still appear. Use a value-free inspection interface for agent metadata, and avoid copying raw env reports into logs or messages. These examples describe shapes only and contain no real values. The legacy contract and managed YAML contract are separate variants. Both use vars[] in raw CLI output. MCP env.keys, where available, returns a narrower keys[] projection and withholds raw stdout/stderr. | Field | Legacy contract | Managed YAML | | --- | --- | --- | | project | string | string | | env_selection | requested/default/effective/overlay_path:string or null; overlay_exists:boolean | same public field names | | format | omitted in legacy list | project_env_config_v1 | | status | classification plus summary/detail strings | YAML classification plus summary/detail strings | | storage | legacy contract/local/portable compatibility report | canonical YAML/project-key report; contract member is not added by this builder | | warnings | array of warning records | not emitted by modern list builder | | vars | array of resolved variable records | array of selected-scope records | | missing_required | string[] | empty array in modern list builder | | files/scopes/unknown_scopes/selected_scope | omitted | string[]/string[]/string[]/string | | materialized_keys | omitted | sorted string[] unless values were explicitly requested | | materialized | omitted | string map only on explicit value-output path | ### Variable records | Field | Legacy | Managed YAML | | --- | --- | --- | | key | string | string | | required | boolean from contract | false | | source | plain_env or keychain | plain_env or keychain (secret marker) | | services | string[] or null | winning non-global scope as one-element array, otherwise null | | resolved_from | dotenv/process/keychain/portable_backend or null | project_env_config | | storage | HackEnvValueStorageJson | kind/plaintext-or-secret, backend/project_env_config, location:string, mode/yaml, trust_model:string, classification | | value | string or null; secret default mask is *** | string; secret default mask is *** | The source field is a compatibility label: keychain on a managed YAML record marks a secret; it does not mean that YAML ciphertext moved to OS keychain storage. Files and scopes are selected by the matching version parser. v4 rejects YAML null; v5 uses it as a removal marker. ### Legacy storage and classification types These type names describe serialized report metadata. A retained backend/classification value is not qualification of every backend or hosted shared-state feature. Modern YAML storage has its own concrete projection described above. ```ts export type HackEnvSharedState = | "local_only" | "plaintext_compatible" | "portable_bundle" | "broker_managed"; ``` ```ts export type HackEnvJsonClassification = { readonly trust_model: string; readonly custody: string; readonly portability: string; readonly shared_state: HackEnvSharedState; }; ``` ```ts export type HackEnvValueStorageJson = { readonly kind: "plaintext" | "secret"; readonly backend: string; readonly location: string; readonly mode: string; readonly trust_model: string; readonly classification: HackEnvJsonClassification; }; ``` ```ts export type HackEnvStorageJson = { readonly contract: { readonly path: string; readonly trust_model: string; readonly classification: HackEnvJsonClassification; }; readonly local_plaintext: { readonly path: string; readonly exists: boolean; readonly trust_model: string; readonly mirrored_to_backend: boolean; readonly fallback: { readonly enabled: boolean; readonly source: string; readonly trust_model: string; readonly classification: HackEnvJsonClassification; }; readonly classification: HackEnvJsonClassification; }; readonly local_secrets: { readonly backend: string; readonly location: string; readonly mode: string; readonly provider: string | null; readonly trust_model: string; readonly classification: HackEnvJsonClassification; }; readonly portable_state: { readonly status: string; readonly trust_model: string; readonly message: string; readonly classification: HackEnvJsonClassification; }; readonly compatibility_mode: { readonly plaintext_target: string; readonly secret_backend: string; readonly plaintext_mirrored_to_backend: boolean; readonly summary: string; }; }; ``` ```ts export type HackEnvAggregateStatusJson = HackEnvJsonClassification & { readonly summary: string; readonly detail: string; }; ``` ### Legacy warnings Warnings contain kind:overlay_plaintext_ignored_for_secret_contract, key:string, overlay_path:string, services:string[]|null and message:string. This is a report of contract/source mismatch; it is not a secret value. Missing-required names are reported separately. ## Scope and provenance [Project view serializer](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/lib/project-views.ts), [runtime serializer](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/lib/runtime-projects.ts), [env output builders](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/commands/env.ts), and [env storage serializers](https://github.com/hack-dance/hack/blob/91b14bf0abb17602142425de0d02628a3e8a2615/src/lib/hack-env-status.ts) are the authority for these projections. This documents public fields from source, not successful runtime, cloud or client qualification. Unknown application map keys and external engine values are intentionally open; owned report fields above are not treated as open merely because the JSON emitter returns `Record`. ## Applying environment changes `hack env apply` is a service restart wrapper. It does not return the env-list report above: it forwards restart, a concrete service, --path and selected env/JSON arguments, then returns the child exit code/output. Service/JSON forms remain subject to that version and backend admission. This is not an atomic multi-service env transaction. v4 trims the service and refuses an empty name or global; it forwards a truthy env option. next.5 uses stricter service/selection parsers rather than widening this contract. ## Listing field types --summary and --timings require --json. --summary cannot be combined with --meta or --details. Timings are a separate numeric diagnostic record on stderr; they do not change stdout into a timing envelope. | Top-level field | Type / presence | | --- | --- | | generated_at | string timestamp | | filter | string or null | | include_global/include_unregistered/include_meta | boolean | | detail_level | summary when summary selected; otherwise omitted | | runtime_ok | boolean | | runtime_error/runtime_checked_at/runtime_last_ok_at/runtime_reset_at/runtime_reset_summary/runtime_last_repair_at/runtime_repair_action/runtime_next_step | string or null | | runtime_reset_count | number | | runtime_reset_changes | string[] | | runtime_repair_outcome | stabilized, manual_action_required or null | | projects | project row array | Summary rows contain project_id:string|null; name:string; repo_root/dev_host:string|null; status:running/stopped/missing/unregistered/unknown; runtime_status below; defined_service_count:number|null; host_process_count/container_count/running_container_count/branch_count/session_count:number. Counts describe the gathered snapshot, not ongoing ownership or liveness. runtime_status is running/stopped/missing/unknown/not_configured in v4. Full and summary rows are separate projections. Full rows share project_id/name/repo_root/dev_host/status/runtime_status, but omit the summary-only defined_service_count, host_process_count, container_count, running_container_count, branch_count and session_count. Full rows contain project_dir:string|null; ownership:compatibility object|null with mode/owner_type/owner_id/managed_by; defined_services/extensions_enabled/features:string[]|null; service_hosts:string-to-string-array map|null; runtime_configured:boolean|null; normalized runtime|null; branch_runtime array of branch:string plus runtime; sessions/worktrees/lifecycle as described above; kind:registered/unregistered. The ownership data is descriptive, not authorization for hosted features. ## Managed YAML classification values Managed YAML does not use the legacy classification enum above. The exact classification groups emitted by the modern builder are: | Group | trust_model | custody | portability | shared_state | | --- | --- | --- | --- | --- | | YAML aggregate/portable state | repo_managed_env_config | repo_tracked_env_config | portable_with_out_of_band_key | repo_managed_overlay | | Compatibility plaintext | compatibility_output | local_plaintext_file | local_only | compatibility_only | | Local project key | local_secret_key | local_secret_key | local_only | local_only | --- # Diagnostic and setup reports Pinned source: `91b14bf0abb17602142425de0d02628a3e8a2615`. Consumer-visible JSON projections only. R = required; optional means omitted, never implicitly null. A listed null union is emitted as null. Arrays may be empty unless stated otherwise. Source admission is not runtime/provider qualification. All examples are synthetic; paths and values are placeholders. ## Report and exit rules Doctor emits the shared `{ok:true,data:DoctorJsonData}` envelope even when a completed check has status error; those checks make the command exit 1. Warnings alone do not. Top-level thrown failures can instead use the shared failure envelope. A diagnostic report is not repair or deletion authority. Update JSON is its own UpdateOutput union. Handled ok:false has a string error and exits 1; ok:true exits 0. The optional mutagen report appears after a successful update installation. An already-available dependency yields available:true/installed:false/path:string; successful provisioning yields available:true and the actual installation result. Provisioning failure can still leave top-level ok:true/installed:true; inspect mutagen.warning/available. Path null means no dependency found. Omitted warning is distinct from an empty string. A synthetic provisioning fragment is `{"available":false,"installed":false,"path":null,"warning":""}`. Host ps emits a bare HostPsReport and returns 0 after gathering observations, including when the process snapshot is unavailable. It does not return an envelope. snapshotAvailable:false and nullable live metrics mean unknown observation, not proof of stopped processes. Command records carry no argv, environment or output. Record parsing strips unrecognized properties. All current serializer fields are documented below despite its broad inferred/Record return types. V4 setup sync has **no JSON flag and no targets[] payload**. It renders a status list. Its check exits 1 for missing/stale/deprecated/error entries; install/remove fail on error. Do not backport next.5 refresh-only statuses or installMissing/targets fields. V4 doctor has no supersededRoots/hackLocalRoute/envKey fields, and candidate validate/plan/import/adopt leaves are absent. ## Host telemetry interpretation All HostCommandObservation fields are emitted, including explicit nulls. Stored status is running/exited/cancelled/timed_out; the observer preserves completed statuses and can replace running with unknown/orphaned/interrupted. unknown means snapshot or wrapper birth identity unavailable. running requires the original wrapper identity; orphaned means wrapper absent but original child identified; interrupted means neither identified while an unfinished record remains. Identity is PID plus birth/start time, not PID alone. observedPids includes the observed child tree and proven owned-group members. unverifiedGroupPids is populated only when child identity is unavailable but matching numeric group members exist; it confers no signaling authority. Group-members attention takes precedence over wrapper-loss attention. Persistent orphaned commands use persistent_wrapper_lost; other orphaned commands use wrapper_lost; interrupted uses completion_unknown. elapsedMs on command rows is wall time from stored start to finish/now, clamped at zero. cpuTimeMs/maxRssBytes are stored child-completion metrics; liveCpuTimeMs/liveRssBytes sum current proven members or are null without child identity. cpuAccounting labels stored-finish versus live-snapshot mode; it does not make absent metrics non-null. Lifecycle rows come from registered projects/worktrees with persisted sessions. owned-healthy/owned-stale/legacy-owned allow proven group selection; absent/foreign/unknown do not. Unknown can mean missing backend or failed inspection. With owned state and an available snapshot, an empty member set gives live CPU/RSS 0, while elapsedMs is null. Without owned state/snapshot, live CPU/RSS are null. Absent sessions add session_absent_review_state; foreign adds ownership_unverified; other attention is null. Definition source is persisted, not proof current definitions were compared successfully. No private state-file/ownership-token schema is published. Millisecond metrics are durations/CPU time; RSS fields are bytes. ## Typed payload records Each numbered variant below is a distinct object alternative; nested named records are listed separately. Field counts count table rows, including repeated fields in distinct alternatives. Alias definitions and their literal choices are counted separately. ### DoctorResult Source: `src/commands/doctor.ts:680 (finishDoctorJson)`. | Field | Type | Presence | | --- | --- | --- | | `ok` | `true` | required | | `data` | `DoctorJsonData` | required | ### DoctorJsonData.counts Source: `src/commands/doctor.ts:644 (DoctorJsonData)`. | Field | Type | Presence | | --- | --- | --- | | `ok` | `number` | required | | `warn` | `number` | required | | `error` | `number` | required | ### DoctorJsonData Source: `src/commands/doctor.ts:644 (DoctorJsonData)`. | Field | Type | Presence | | --- | --- | --- | | `checks` | `DoctorJsonCheck[]` | required | | `summary` | `string[]` | required | | `counts` | `DoctorJsonData.counts` | required | ### DoctorJsonCheck Source: `src/commands/doctor.ts:637 (DoctorJsonCheck)`. | Field | Type | Presence | | --- | --- | --- | | `id` | `string` | required | | `status` | `CheckStatus` | required | | `detail` | `string` | required | | `durationMs` | `number` | required | ### UpdateOutput — variant 1.target Source: `src/commands/update.ts:406 (UpdateOutput)`. | Field | Type | Presence | | --- | --- | --- | | `platform` | `string` | required | | `arch` | `string` | required | ### UpdateOutput — variant 1 Source: `src/commands/update.ts:406 (UpdateOutput)`. | Field | Type | Presence | | --- | --- | --- | | `ok` | `true` | required | | `current` | `string` | required | | `latest` | `string` | required | | `updateAvailable` | `boolean` | required | | `installed` | `boolean` | required | | `target` | `UpdateOutput — variant 1.target` | required | | `binaryPath` | `string` | required | | `assetsDir` | `string` | required | | `mutagen` | `MutagenProvisionResult` | optional; omitted when absent | ### UpdateOutput — variant 2 Source: `src/commands/update.ts:406 (UpdateOutput)`. | Field | Type | Presence | | --- | --- | --- | | `ok` | `false` | required | | `error` | `string` | required | ### MutagenProvisionResult Source: `src/commands/update.ts:283 (MutagenProvisionResult)`. | Field | Type | Presence | | --- | --- | --- | | `available` | `boolean` | required | | `installed` | `boolean` | required | | `path` | `string \| null` | required | | `warning` | `string` | optional; omitted when absent | ### HostPsReport Source: `src/commands/host-ps.ts:33 (hostPsCommand)`. | Field | Type | Presence | | --- | --- | --- | | `generatedAt` | `string (ISO timestamp)` | required | | `snapshotAvailable` | `boolean` | required | | `commands` | `HostCommandObservation[]` | required | | `lifecycle` | `LifecycleObservation[]` | required | ### HostCommandObservation Source: `src/lib/host-command-observation.ts:242 (observeHostCommand)`. | Field | Type | Presence | | --- | --- | --- | | `version` | `1` | required | | `id` | `string (UUID)` | required | | `project` | `string` | required | | `projectRoot` | `string` | required | | `executable` | `string (basename only)` | required | | `wrapper` | `ProcessIdentity` | required | | `child` | `ProcessIdentity` | required | | `ownsProcessGroup` | `boolean` | required | | `processGroupId` | `positive integer \| null` | required | | `lifetime` | `"command" \| "persistent" \| "bounded"` | required | | `timeoutMs` | `positive number \| null` | required | | `startedAt` | `string (ISO timestamp)` | required | | `finishedAt` | `string (ISO timestamp) \| null` | required | | `status` | `"running" \| "exited" \| "cancelled" \| "timed_out" \| "unknown" \| "orphaned" \| "interrupted"` | required | | `exitCode` | `integer \| null` | required | | `cpuTimeMs` | `nonnegative number \| null` | required | | `maxRssBytes` | `nonnegative number \| null` | required | | `elapsedMs` | `nonnegative number` | required | | `observedPids` | `number[]` | required | | `unverifiedGroupPids` | `number[]` | required | | `liveCpuTimeMs` | `number \| null` | required | | `liveRssBytes` | `number \| null` | required | | `cpuAccounting` | `"reaped_child" \| "live_tree_snapshot"` | required | | `ownership` | `"pid_and_start_time" \| "unverified"` | required | | `attention` | `"group_members_require_review" \| "persistent_wrapper_lost" \| "wrapper_lost" \| "completion_unknown" \| null` | required | ### ProcessIdentity Source: `src/lib/host-command-observation.ts:13 (identitySchema)`. | Field | Type | Presence | | --- | --- | --- | | `pid` | `positive integer` | required | | `birth` | `string \| null` | required | ### LifecycleObservation Source: `src/commands/host-ps.ts:121 (observeLifecycleEntry)`. | Field | Type | Presence | | --- | --- | --- | | `project` | `string` | required | | `projectRoot` | `string` | required | | `branch` | `string \| null` | required | | `session` | `string` | required | | `backend` | `"tmux" \| "zellij"` | required | | `lifetime` | `"persistent"` | required | | `ownership` | `"absent" \| "owned-healthy" \| "owned-stale" \| "legacy-owned" \| "foreign" \| "unknown"` | required | | `definitionSource` | `"persisted"` | required | | `processGroupIds` | `number[]` | required | | `observedPids` | `number[]` | required | | `liveCpuTimeMs` | `number \| null` | required | | `liveRssBytes` | `number \| null` | required | | `elapsedMs` | `number \| null` | required | | `attention` | `"session_absent_review_state" \| "ownership_unverified" \| null` | required | ## Scalar, enum and collection aliases | Name | Exact type / choices | Pinned source | | --- | --- | --- | | `CheckStatus` | `"ok" \| "warn" \| "error"` | `src/commands/doctor.ts:134 (CheckStatus)` | ## Contract boundaries These are the v4 CLI report records only. The newer v5 diagnostic attachments, setup-sync JSON and candidate config report leaves are absent. Shared error.detail remains unknown by its public contract. A report shape is not runtime/provider/client qualification.