Skip to content

Quickstart

Every command below was actually run against a fresh scratch project while writing this page — not guessed from reading code. Output is trimmed for length but not altered in substance. If your output looks different, the CLI has likely changed since — check gald3r <verb> --help, which is always authoritative.

1. Install gald3r

See Install for the full per-OS walkthrough. The short version:

# Windows, once you have any gald3r on PATH
gald3r install update

or download the signed installer/tarball for your OS directly from the latest GitHub release. No Python, no build step, no account required for the CLI itself.

2. Confirm the install is healthy

gald3r doctor

doctor checks your identity file, any installed IDE overlay, path resolution (flags a stale or shadowing copy of gald3r earlier on PATH), platform-spec parity, wired hooks, and the local task/bug database's consistency against the files on disk — all in one pass, and it never fabricates a green result. On a freshly installed signed release with no project scaffolded yet, most rows report skip (nothing to check yet) rather than fail; fail/warn rows always name the exact fix to run.

3. Scaffold a project

From inside the project directory you want gald3r-enabled (cd there first):

gald3r setup --dry-run   # see what would be created, writes nothing
gald3r setup             # actually create it

setup creates .gald3r/ — a fresh project gets the current v2 layout, which nests the per-project SDLC artifacts (tasks/, bugs/, PLAN.md, FEATURES.md, SUBSYSTEMS.md, PRDS.md, IDEA_BOARD.md, TO-DO_LIST.md, ADRS.md, DECISIONS.md, and more) under .gald3r/project/, alongside top-level .gald3r/.identity, PROJECT.md, CONSTRAINTS.md, and config/ (44 items total on a fresh project). Nothing outside .gald3r/ (plus a .gitignore and two policy files) is touched. Run gald3r layout show any time to print every resolved artifact path for the current project; older projects created before v2 keep their original flat layout (.gald3r/tasks/ directly, no project/ nesting) until you run gald3r layout migrate.

4. First useful command — a zero-configuration smoke test

Before wiring up any AI provider, you can confirm the agent-run plumbing works end to end with no network call and no API key:

gald3r run "hello gald3r" --backend dev-echo

[echo #0] r3dlag olleh

--backend dev-echo is a deterministic, offline stand-in session — useful for confirming the CLI, not for real agent work. It's the fastest way to prove the install works before touching any provider configuration.

5. Track real work: tasks

gald3r task add "Write the quickstart doc" -d "Draft it" --type docs --priority medium
gald3r task list

Created task 1: Write the quickstart doc

1        v5  medium     pending    Write the quickstart doc

gald3r task next shows the single next task to work; gald3r task update T1 --status in-progress claims it. See Verbs for the full task/bug verb surface.

Using an AI IDE instead of the bare CLI? Everything above also works as an in-IDE slash command once you've installed that platform's overlay (gald3r platform install claude / gald3r platform install cursor — see Install → Per-platform IDE integration): gald3r task add becomes /g-task-add in Claude Code or @g-task-add in Cursor, gald3r task update T1 --status in-progress becomes /g-task-upd, and so on — the CLI verb and the /g-/@g- command dispatch to the same underlying logic, just from inside your editor's chat instead of a terminal. See crash.md for how that dispatch actually works, or platform-usage.md for the full command/skill/rule/hook/agent tour from the IDE-user's perspective, including a per-platform quick-start matrix.

6. Optional: a real agent run with a provider

gald3r run without --backend dev-echo talks to a real provider. Generate a starter config first:

gald3r init-providers --dry-run   # preview without writing
gald3r init-providers             # write providers.yaml (wherever your gald3r home resolves)

The generated starter defaults to a local Ollama endpoint (http://localhost:11434/v1, model qwen3:4b) — no cloud account or API key required if you already have Ollama running locally. Edit providers.yaml to point at OpenAI/Anthropic/etc. instead if you'd rather use a cloud provider (api_key fields accept $ENV_VAR-style references). Once configured:

gald3r run "explain what this project does"

7. Where next

  • first-project.md — a deeper walkthrough: scaffold a project, run a task through its full lifecycle, real output at every step
  • concepts.md — CRASH, .gald3r/, and the database-vs-markdown state model
  • platform-usage.md — driving gald3r from inside Cursor, Claude Code, and the rest of the AI IDE roster
  • task-bug-workflow.md — the full task/bug command surface
  • autopilot.md — letting gald3r work the queue itself
  • verbs.md — the full CLI verb catalog
  • gald3r <verb> --help — always the authoritative source for any single verb's flags