Commands
Every KATforge workflow is hearth <command>. Run hearth --help for the live surface; the reference below mirrors the current CLI.
Lifecycle
hearth up # start the dev stack (default: dev stage)
hearth up --stage qa -d # qa stage, detached
hearth up katforge api # only specific compose services
hearth up --build # rebuild images first
hearth down # stop the stack
hearth dev <service> # run a frontend dev server (katforge, stumper, ...)
hearth up ensures the shared katforge Docker network exists, creates hearth/certs/ if absent, and merges hearth/env/<stage>/*.yaml (plaintext + sops-decrypted) into the compose environment before invoking docker compose up. See Environments for the env-loading details.
Hostnames and routing
hearth urls # show every dev URL routed by Traefik
hearth hosts apply # add katforge entries to /etc/hosts (+ Windows on WSL)
hearth hosts show # see what's currently in your hosts file
hearth hosts remove # remove the katforge block
hearth hosts writes a marked block (# === BEGIN katforge === / # === END katforge ===) so it can update or remove its own entries without touching anything else.
On WSL, it edits both the Linux /etc/hosts and the Windows hosts file so browsers on the host resolve dev domains.
Deploy and observe
hearth status # deployed versions and pod health
hearth status --qa # check QA
hearth logs api # tail one service's logs
hearth ship api # → prod, watch CI run (~3 min)
hearth ship api --qa # → qa namespace (release marked prerelease)
hearth ship api --draft # build image, don't deploy
hearth ship api --no-version # re-release current tag without bumping
hearth ship api --no-watch # skip the CI tail
hearth promote api v0.0.28-rc.1 # promote a qa prerelease to prod
hearth rollback api # revert to previous deployment
hearth ship runs pre-ship tests, ships the commit + tag, posts a GitHub Release, then tails the resulting CI run. See Shipping for the full pipeline.
hearth promote flips a prerelease's flag (prerelease=false, make_latest=true), which re-fires release.published and CI deploys the same image to prod — no rebuild.
Secrets
hearth secret list dev # list all keys per service
hearth secret edit dev api # decrypt → $EDITOR → re-encrypt
hearth secret get dev api OAUTH_DISCORD_ID
hearth secret diff dev prod # what differs between stages
hearth secret apply prod # push env/<stage>/* into k8s as Secret objects
hearth secret apply prod --dry-run # preview without writing
Edits round-trip through $EDITOR in plaintext; the file is re-encrypted on save. apply is the prod equivalent of dev's compose env injection: it reads hearth/env/<stage>/<service>.{yaml,enc.yaml}, builds a <service>-secrets Kubernetes Secret, and kubectl applys it (idempotent). See Secrets and Production-specific vars.
Team
hearth team list # who can decrypt what
hearth team whoami # this machine's age public key
hearth team add age1abc... # authorize someone (re-encrypts all files)
hearth team remove age1abc... # de-authorize (rotate secrets after!)
team add and team remove rewrite .sops.yaml and re-encrypt every secret file in one transaction. Removing a recipient does not rotate the secrets they could already see — do that explicitly after.
Run and test
hearth run stumper:challenge:reset # run a Symfony console command in the API container
hearth run list # list available console commands
hearth test # run the test suite
Anything after hearth run is forwarded verbatim to bin/console inside the API container.
Setup and install
hearth setup # idempotent: install missing tools + verify + init
hearth setup --ci # bootstrap GitHub Actions plumbing (one-time)
hearth setup --reinstall # re-download every hearth-managed tool
hearth setup --reinstall --only sops # re-download just one
hearth setup is the one-stop bootstrap and diagnostic. It downloads any missing hearth-managed tool (sops, age, kubectl, mkcert, yq), generates an age key if one isn't present, installs the local mkcert CA, generates dev certs, and verifies you can decrypt at least one secret. Run it whenever something feels off. --reinstall forces re-download of all tools; combine with --only <tool> to refresh just one.
hearth setup --ci is a one-time bootstrap for the deploy pipeline. It applies hearth/k8s/ci/rbac.yaml (creates the github-deployer SA + scoped RBAC), builds a kubeconfig from the SA token, and sets K3S_KUBECONFIG + KATFORGE_GITHUB_TOKEN as repo secrets across every shippable repo. Re-run when adding a new shippable service or rotating credentials. See Shipping → First-time CI setup.
Help
Every subcommand supports --help. The output mirrors the surface above:
$ hearth ship --help
Usage: hearth ship <service> [options]
Build, release, and deploy a shippable repo.
Arguments:
service e.g. api, katforge, stumper
Options:
--qa deploy to qa namespace (release marked prerelease)
--draft build image, don't deploy
--no-version re-release current tag without bumping
--no-watch skip the CI tail
-h, --help show this message