task-pigeon/docs/plans/2026-08-14-pigeon-cli.md

Small SQLite task queue CLI for people and coding agents.

---
artifact_contract: ce-unified-plan/v1
artifact_readiness: implementation-ready
execution: code
created: 2026-08-14
product_contract_source: ce-plan-bootstrap
---

# Pigeon CLI Plan

## Problem Frame

Pigeon is a small personal task-claiming CLI backed by SQLite. It should make it easy to add work, list work, atomically claim the next available task, update task metadata, mark work blocked, and mark work done. The implementation should use modern TypeScript/Bun tooling while keeping the architecture conceptually simple:

CLI -> command functions -> Drizzle/SQL -> SQLite.

## Product Contract

### Requirements

- R1: Provide explicit commands: `pigeon init`, `pigeon add`, `pigeon list`, `pigeon claim`, `pigeon update`, `pigeon block`, and `pigeon done`.
- R2: Store tasks in a local SQLite database with stable IDs, title, optional URL, status, claimant, notes, timestamps, and claim timestamp.
- R3: Use Drizzle for typed schema definition and normal CRUD where it improves clarity.
- R4: Use raw SQL when it is simpler and more obviously correct, especially for atomic claim behavior.
- R5: Use a modern CLI parser for commands, args, flags, help, validation, errors, and aliases where useful.
- R6: Keep architecture deliberately flat. Do not add repositories, services, dependency injection, providers, adapters, plugins, event buses, or generic domain abstractions.
- R7: Use Bun as runtime, package manager, test runner, and build/compile tool.
- R8: Use Biome for formatting/linting and Bun test for behavior coverage.

### Scope Boundaries

- In scope: local CLI, local SQLite database, schema migrations, simple task lifecycle, focused tests, README usage.
- Out of scope: sync, multi-user accounts, daemon processes, remote servers, plugin systems, TUI, notification integrations, and complex scheduling.

## Key Technical Decisions

- KTD1: Use `commander` for CLI parsing. It is boring, widely understood, and handles the command surface without hand parsing.
- KTD2: Use `bun:sqlite` as the SQLite client and `drizzle-orm/bun-sqlite` for typed database access.
- KTD3: Keep database path resolution in one small helper. Default to `.pigeon/pigeon.db` in the current working directory, with `PIGEON_DB` as an override for tests and advanced use.
- KTD4: Use Drizzle Kit migrations in `drizzle/`, plus a runtime `init` command that applies embedded migration SQL. This keeps normal development aligned with Drizzle while making the CLI self-contained for personal use.
- KTD5: Implement `claim` with one atomic `UPDATE ... RETURNING` statement against pending tasks ordered by creation time.
- KTD6: Use simple status values: `pending`, `claimed`, `blocked`, `done`.

## Implementation Units

### U1: Project Scaffold and Tooling

Files:
- `package.json`
- `tsconfig.json`
- `biome.json`
- `drizzle.config.ts`
- `.gitignore`
- `README.md`

Work:
- Configure Bun scripts for `test`, `check`, `format`, `db:generate`, `db:migrate`, and `build`.
- Add dependencies: `commander`, `drizzle-orm`, `drizzle-kit`, `picocolors`, and a lightweight table renderer if useful.

Tests:
- Covered by later command tests and `bun run check`.

### U2: Schema and Database Helper

Files:
- `src/schema.ts`
- `src/db.ts`
- `drizzle/0000_initial.sql`

Work:
- Define `tasks` with Drizzle SQLite schema.
- Resolve database path.
- Open Bun SQLite database with Drizzle.
- Apply migrations idempotently from `init`.

Tests:
- `src/db.test.ts` verifies database initialization creates the expected table and supports insert/select.

### U3: Command Functions

Files:
- `src/commands.ts`
- `src/output.ts`

Work:
- Implement small task functions for add/list/claim/update/block/done.
- Keep command functions close to Drizzle/SQL calls.
- Render readable output for single task results and lists.

Tests:
- `src/commands.test.ts` covers add, list filters, atomic claim order/status transition, update, block, done, and invalid transitions.

### U4: CLI Entry Point

Files:
- `src/cli.ts`

Work:
- Wire Commander commands and flags to command functions.
- Provide explicit errors for invalid inputs.
- Export a `run` function so tests can exercise the CLI without spawning a process for every scenario.

Tests:
- `src/cli.test.ts` covers command parsing for core flows and help/error behavior where practical.

## Verification

- `bun test`
- `bun run check`
- `bun run build`
- Manual smoke flow against a temporary database:
  - `pigeon init`
  - `pigeon add "Write README" --url https://example.com`
  - `pigeon list`
  - `pigeon claim --by andrew`
  - `pigeon block 1 --note "waiting"`
  - `pigeon done 1`