Checklist Ledger

Checklist Ledger is a single-user hosted checklist app designed for two users:

• a human who wants a fast web checklist
• Codex, which should mutate the checklist through a stable CLI instead of manually editing database rows

The app deploys as one Cloudflare Worker. The Worker serves the Vite React UI from static assets and exposes token-protected API routes backed by D1.

Current deployment:

https://hosted-checklist.mutdashboard.workers.dev

Current D1 database:

checklist-ledger / 4094cd40-9c59-4434-915e-dd95cd63ab54

Local Setup

1. Install dependencies:

   npm install

2. Create local Worker secrets:

   Copy-Item .dev.vars.example .dev.vars

3. Apply local D1 migrations:

   npm run db:migrate:local

4. Build and run the Worker:

   npm run build
   npm run dev

5. Open the app:

   http://127.0.0.1:8787

Use the token from .dev.vars in the browser login screen.

CLI Usage

The CLI talks to the same API as the browser UI. This is the safe control layer for Codex because every mutation still passes through validation in the Worker.

Full CLI reference:

C:\Users\jfrie\Documents\Codex\2026-04-23\can-you-access-my-google-tasks\docs\CLI.md

After npm publish, install it on another machine with:

npm install -g checklist-ledger
checklist help

Until npm auth is configured and the first publish completes, install from this working copy or a tarball:

npm install -g C:\Users\jfrie\Documents\Codex\2026-04-23\can-you-access-my-google-tasks

On this machine, the command shim is installed at:

C:\Users\jfrie\bin\checklist.cmd

That means you can run commands directly:

checklist help
checklist ledgers
checklist list

Set the remote or local API target:

$env:CHECKLIST_API_URL = "http://127.0.0.1:8787"
$env:CHECKLIST_ADMIN_TOKEN = "local-dev-token"

Run commands:

checklist list
checklist list full
checklist list 1-4 --ledger Today
checklist list full 1-4 --ledger Today
checklist add "Write deployment notes" --details "Add D1 setup and custom domain steps."
checklist child 1 "Create the production D1 database"
checklist move 2 --before 1
checklist done 1
checklist finished
checklist reopen 1
checklist details --item 1

After npm run build, the compiled binary entrypoint is available at:

dist\cli\index.js

For a persistent production CLI config, copy this example to your home folder and edit the values:

Copy-Item checklist-ledger.config.example.json $HOME\.checklist-ledger.json
notepad $HOME\.checklist-ledger.json

This machine is currently configured for production CLI access at:

C:\Users\jfrie\.checklist-ledger.json

The generated production admin token is stored locally at:

C:\Users\jfrie\Documents\Codex\2026-04-23\can-you-access-my-google-tasks\.checklist-production-token.txt

Cloudflare Deployment Notes

1. Create the production D1 database:

   npx wrangler d1 create checklist-ledger

   If this fails with Authentication error [code: 10000], the active CLOUDFLARE_API_TOKEN can identify the account but does not have the D1 API permissions needed for database list/create/migration operations.

2. Put the returned database_id into wrangler.jsonc.

3. Set the production admin token:

   npx wrangler secret put ADMIN_TOKEN

4. Apply remote migrations:

   npm run db:migrate:remote

5. Deploy:

   npm run deploy

6. Point your custom domain at the Worker in Cloudflare.

7. Configure CLI access with the same token value you entered for the Worker ADMIN_TOKEN secret.

Verification Commands

Run these before deploying:

npm run check
npm test
npm run deploy:dry-run

The dry run validates that Wrangler can bundle the Worker, read static assets, and see the D1 and asset bindings without publishing a new Worker version.

For CLI use against production, set:

$env:CHECKLIST_API_URL = "https://your-custom-domain.example"
$env:CHECKLIST_ADMIN_TOKEN = "your-production-token"

Data Model

items is the source of truth for checklist rows:

• status = active rows appear in the active checklist
• status = finished rows appear in the Finished view
• ledger_id = <id> scopes items to one named ledger
• parent_id = null means top-level item
• parent_id = <id> means one-level child item

The Worker rejects grandchildren in v1 so the UI, CLI, and data model stay easy to reason about.

Ledgers and Dark Mode

The top toolbar supports:

• selecting a ledger
• creating a ledger
• toggling light/dark mode

The browser remembers the selected ledger and theme in localStorage. The CLI defaults to ledger 1, or another ledger when CHECKLIST_LEDGER_ID or defaultLedgerId is configured.

Ledger CLI examples:

checklist ledgers
checklist ledger add "Home"
checklist add "Pay electric bill" --ledger Home
checklist list --ledger Home

PowerShell treats unquoted #5 as a comment. Use 5 or quote the hash form:

checklist details --ledger slarmen --item 5
checklist details --ledger slarmen --item "#5"