Database Commands
The genie db command group manages the embedded PostgreSQL instance (pgserve) that backs Genie’s task store, agent registry, schedules, and more.
Genie requires pgserve >=1.1.10 (bumped 2026-04-20).
genie db status
Show pgserve health, port, data directory, and table counts.
Outputs connection info, running state, and a summary of how many rows exist in each core table.
genie db migrate
Run pending database migrations.
Applies any unapplied migrations in order. Safe to run multiple times — already-applied migrations are skipped.
genie db query
Execute arbitrary SQL and print results.
# Count tasks by stage
genie db query "SELECT stage, count(*) FROM tasks GROUP BY stage"
# Check recent schedule runs
genie db query "SELECT * FROM schedule_triggers ORDER BY created_at DESC LIMIT 5"
# Inspect app store
genie db query "SELECT name, item_type, version FROM app_store"
This runs raw SQL against the Genie database. Write queries (INSERT, UPDATE, DELETE) will modify data directly — use with care.
genie db backup
Dump the database to a compressed snapshot file.
Creates a backup at ~/.genie/snapshot.sql.gz.
$ genie db backup
Dumping database to ~/.genie/snapshot.sql.gz...
✅ Backup complete (2.3 MB)
genie db restore
Restore the database from a backup snapshot.
genie db restore [file] [--yes]
| Option | Description |
|---|
--yes | Skip confirmation prompt |
~/.genie/snapshot.sql.gz.
# Restore from default snapshot
genie db restore
# Restore from a specific file
genie db restore ~/backups/genie-2026-03-30.sql.gz
This replaces the current database contents with the snapshot data. Make sure to back up first if you have unsaved state.
genie db url
Print the PostgreSQL connection URL for direct access with external tools.
| Option | Description |
|---|
--quiet | Print only the URL with no extra formatting |
$ genie db url
postgresql://genie:genie@localhost:19642/genie
# Use with psql
psql $(genie db url)
Danger zone
genie-wipe
Fresh-start local Genie state — wipes the embedded PostgreSQL data directory (and optionally worktrees, teams, state, logs, wishes, brainstorms, and/or user config) to emulate a new-user experience.
genie-wipe is a repo-local script, not a top-level genie subcommand. Invoke it with bun from a Genie checkout:
bun scripts/genie-wipe.ts [--apply] [--full] [--config]
This is destructive. Running with --apply permanently deletes ~/.genie/data/pgserve — the full database — and anything else covered by the flags you pass. There is no undo. Back up first with genie db backup if you need to preserve state.
| Flag | Description |
|---|
| (none) | Dry-run (default). Prints the wipe manifest with sizes; no writes. |
--apply | Actually wipe. Requires typing the interlock phrase I UNDERSTAND FRESH INSTALL at the prompt. |
--full | Also wipe ~/.genie/{worktrees,teams,state,spawn-scripts,logs,wishes,brainstorms}. |
--config | Also wipe ~/.genie/config.json, pgserve.port, serve.pid, and brain-version-check.json. |
--help, -h | Show the built-in help. |
- Always:
~/.genie/data/pgserve (full DB reset — migrations re-run on next connect).
- With
--full: ~/.genie/worktrees, teams, state, spawn-scripts, logs, wishes, brainstorms.
- With
--config: ~/.genie/config.json, pgserve.port, serve.pid, brain-version-check.json.
What is preserved (unless --config is passed): ~/.genie/config.json, tmux.conf, installer-owned scripts, shell history, and any repos outside ~/.genie/worktrees.
# Preview what would be wiped (DB only)
bun scripts/genie-wipe.ts
# Preview a full wipe (everything except config)
bun scripts/genie-wipe.ts --full
# Wipe just the database
bun scripts/genie-wipe.ts --apply
# Nuke everything back to post-install defaults
bun scripts/genie-wipe.ts --apply --full --config
genie <verb> call (e.g. genie serve start) auto-starts a fresh pgserve and re-runs all migrations. If --full was used, genie team ls and genie task list will come up empty — you are effectively a new user.
