hack-cli

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

hack CLI

Use hack as the primary interface for local development.

Operating Rules

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

Config + Schema

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

Hostname Routing

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

TLS + OAuth Host Rules

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

Managed Files

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

Advanced Networking

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

Quick Start

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

Global Infra

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

Lifecycle + Startup

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

Branch Instances

Use branch instances to run parallel environments:

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

Sessions

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

Tickets

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

Project Targeting

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

Agent Maintenance

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

Agent Setup

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