| name | setup |
| description | Interactive setup wizard for `config/hq.yaml`. Use when the user says "setup", "configure", "set up env", or when `config/hq.yaml` is missing. |
Setup Wizard
You are a thin wrapper around the built-in hq setup command. It does the real work
(writes config, detects UID/GID/TZ, checks reachability, and on Tier 2 bootstraps
Forgejo). Your job is to ask the human the questions it needs and run it for them.
config/hq.yaml is the gitignored, host-local config every hq command reads. The
tracked template is config/hq.example.yaml. There is no separate project.yaml and no
GitHub anymore — the backend is Forgejo, and forgejo_url is personal, so it lives in
hq.yaml too.
Pick the tier
- CLI only — a laptop that just talks to an existing Forgejo over the tailnet.
- Server stack — the always-on host running docker compose (forgejo + ollama +
hq-cron). This tier also bootstraps Forgejo (admin, repo, API token, GTD labels).
- Extra worker — another machine that claims collect jobs from the hub's Forgejo.
Run it
Interactive: ./bin/hq setup (prompts on stdin, prints the compose/ollama commands to
run afterwards). Ask the human for the values it needs and pass them as flags when you
already know them:
--tier {1,2,3}--username, --repo (Forgejo owner/name slug), --timezone (must contain /)--forgejo-url (base URL of the Forgejo instance)- Tier 2 only:
--bind-ip, --domain, --admin-user, --admin-password, and either
--forgejo-token (reuse an existing token) or --token-name (mint one).
hq setup never overwrites an existing config/hq.yaml/.env unless you pass --force
— confirm with the user before forcing.
After setup
- Fill any placeholders the wizard reported in
config/hq.yaml (e.g. per-account gws
config_dir and mail_url_index under google.accounts, working-hour blocks).
- Run
./bin/hq doctor — it checks binaries, config keys, token validity, Forgejo/ollama
reachability, and container/cron freshness, and prints a FIX line per failure. Walk the
user through anything red.
- Per-plugin scaffolding without the full wizard:
./bin/hq install <mail|cal|drive|discord|core|all>.
Docker / other hosts
Bind-mount the config: docker run -v /path/to/config/hq.yaml:/hq/config/hq.yaml:ro ….
Each host keeps its own hq.yaml (accounts and runners differ per host).
