task-pigeon/docs/turso.md

Small SQLite task queue CLI for people and coding agents.

# Turso/libSQL Direct Database

Use Turso when multiple computers need one live Pigeon board without keeping a
Pigeon server online. Each Pigeon CLI connects directly to the same
SQLite-compatible libSQL database through Drizzle.

This is still one database, not a local-replica or conflict-resolution system.
Every computer needs the database URL and a database token. Keep that token
private and prefer user-level config for it.

## Create and Configure

Create a Turso database, then retrieve its connection URL and token:

```sh
turso db create pigeon
turso db show --url pigeon
turso db tokens create pigeon
```

Configure Pigeon on each computer with those values:

```sh
pigeon config --database-provider turso \
  --database-url libsql://<your-database>.turso.io \
  --database-token <database-token>
pigeon init
pigeon status
pigeon monitor --by andrew
```

Pigeon applies its included Drizzle migrations before the first command uses a
new database. Run `pigeon status` from the second computer to confirm it sees
the same board.

For a user-level credential instead of project-level config:

```sh
pigeon config --user --database-provider turso \
  --database-url libsql://<your-database>.turso.io \
  --database-token <database-token>
```

## Temporary Overrides

Environment values take precedence over config, which is useful for a short
session or secret manager integration:

```sh
PIGEON_DATABASE_PROVIDER=turso \
PIGEON_DATABASE_URL=libsql://<your-database>.turso.io \
PIGEON_DATABASE_TOKEN=<database-token> \
pigeon monitor --by codex
```

`PIGEON_LOCAL_ONLY=1` forces the current shell back to its local Bun SQLite
queue. Switch the configured default back permanently with:

```sh
pigeon config --database-provider bun-sqlite \
  --clear-database-url \
  --clear-database-token
```

## Scope

Turso is a direct database connection. It does not use `pigeon serve`, Elysia,
or Pigeon's HTTP RPC endpoint. Use the private HTTP server when a single
machine should own the SQLite file; use Cloudflare D1 when you specifically
want a Worker-owned fixed RPC endpoint.

Local snapshots and `pigeon db` merge tools intentionally continue to operate
on Bun SQLite. Set `PIGEON_LOCAL_ONLY=1` before using them while Turso is
configured.