Docket

Docket is a local-first task manager for the terminal. Capture, plan, and finish work in one keyboard-driven outline. Your tasks live in readable Markdown files on your own disk.

The terminal is the core interface. Docket.app for macOS wraps it with quick capture, menus, and notifications; the native iPhone app uses the same Go engine. Optional file exchange keeps enrolled working copies in sync through a folder you provide, including iCloud Drive. There is no hosted server, account, or web interface.

There is no docket add: the command line is deliberately limited to diagnostics, conflict recovery, device sync, workspace relocation, project export, and shell completion. Run docket and the interface is the product.

Work is grouped into lanes and projects; Peek below the outline shows the selected task's details. The animation is recorded from the real app over fictional tasks; the key pressed is named in the title bar.

What using it looks like

Your first five minutes

Run docket after installing it. No project setup is needed:

1. Press a, type Try Docket, and press Enter. Your task lands in Inbox under Unfiled.
2. Move to its row with the arrow keys, then press w followed by t to plan it for Today. Press g followed by t to open Today.
3. With the task selected, press w followed by d to complete it. It leaves Today; press u to undo and bring it back.
4. Press /, type Terminal, and press Enter to search. Press Esc to clear the search.

Press ? whenever you want the keys for the surface you are on. Press F10 to browse menus; Task groups everyday actions under Plan, Status, and Details. In Outliner help, press /, search an action such as defer, and press Enter to run the selected result. Up/down choose another result; its shortcut and target remain visible.

Capture more in one line

Start with a title, then add one piece of metadata at a time. Create a project with slug web using P then a. In the Outliner, press a and build up this draft; each row below adds one instruction to the previous one:

Draft	Result
fix login redirect	A task in the current project, or Inbox under Unfiled when browsing all projects
fix login redirect %web	The task goes to web
fix login redirect %web @friday	It is due next Friday; the preview shows the exact date
fix login redirect %web @friday $today	It is also planned for Today

Press Enter when the draft is ready. Press b on the saved task to read its details. Today is a plan; the task's status is still Backlog until you start it with wg.

Later, add !1 for high priority or #auth for a tag. See capture syntax and date rules for the full reference, including literal examples and batch capture.

Mental model

Status says where the work stands. Each task has one of eight states:

inbox  backlog  doing  waiting  paused  someday  done  canceled

Today and Next are plans. A task can belong to one at a time. Completing it clears its plan. Use wt for Today, wn for Next, and wb for Backlog.

Projects organize tasks. Capture goes to the current project, or Unfiled when you are browsing all projects. Tasks can have subtasks within their project.

Modes choose what you see. Tab cycles All → Today → Inbox → Next → Backlog → Due → Recent; Shift+Tab reverses it. All is home. Press g to see shortcuts for jumping directly to a mode. Modes and lanes explains how each view groups your work.

Install and start

On macOS or Linux, install the release build with Homebrew:

brew install --cask sglavoie/tap/docket
docket

The cask installs docket, its short alias dkt, and bash, zsh, and fish completions for both; brew upgrade --cask docket takes new releases. On macOS (14 or later) it also installs the notarized Docket.app into /Applications, and docket and dkt are the binary that app bundles, so the app and the command line always run the same version.

With Go instead:

go install github.com/sglavoie/docket@latest
docket

That installs docket only; the dkt alias comes with the cask or with just install from a clone. It needs Go 1.26.10 or newer and $(go env GOPATH)/bin — usually ~/go/bin — on your PATH. To build from a clone instead:

go build -o docket .
./docket

On macOS, Docket.app runs the same program in its own window and adds a menu-bar shortcut, quick capture, and notifications. The cask installs it; from a clone, just mac-install builds and installs it instead, which requires the full Xcode app.

A new workspace starts locally in ~/.docket/. Use --data-dir, DOCKET_DATA_DIR, or docket workspace move to select a different location. Moving into iCloud Drive or another synced directory is an explicit choice; an existing selected iCloud workspace is preserved.

Launch opens Active Projects in All mode, or your last active saved lens. Press Esc to leave a restored lens. Search and lenses explains saved views and how to reveal tasks hidden by filters.

Platform support

Docket is developed and used daily on macOS. The full test suite also runs on Linux in CI on every push, so Linux is exercised but not daily-driven. Windows is not supported.

Your data

The Go engine makes no network calls and sends no telemetry. By default, the terminal workspace lives under ~/.docket/: a JSON catalog plus one readable Markdown file per project. You can read, grep, edit, and back it up with ordinary tools. An enrolled Mac or iPhone keeps its own local working copy and exchanges changes through the chosen folder; when that folder is in iCloud Drive, Apple’s file transport handles cloud delivery. See Storage for the working-copy layout and recovery instructions.

Before you upgrade

Keep a backup of your workspace before upgrading. Migrations save a snapshot first, but are one-way: older builds refuse a migrated workspace.

If something looks wrong, start with docket doctor for read-only diagnostics. See storage and recovery before using docket doctor --fix or restoring a backup.

Daily loop

The Outliner is the only primary task presentation:

1. a captures one or more tasks.
2. gi moves to Inbox for triage.
3. w opens the workflow chord over the ten destinations the $destination sigil names.
4. wb, wn, and wt organize work; wg starts it and wd completes it.
5. Direct metadata keys handle priority, dates, tags, and pin; state goes through the w chord above.
6. / searches for a task.
7. Space opens the occasional task tools, Delete among them, which asks before it removes anything.
8. u undoes the last change and Ctrl+R redoes it.

Together, these operations form one capture, triage, plan, execute, and complete loop.

Useful once you know the basics

Leave a resume note with r before pausing a task; Peek (b) shows where to restart. During review, R acknowledges the task and advances to the next visible task needing attention. If a view seems unexpectedly narrow, Q explains its active restrictions and lets you remove them individually. Inside compact capture, Ctrl+N saves and keeps capture open for another task or batch; in the Outliner, that same key opens Notes.

Keys at a glance

One key is one act, on every surface. Space is reserved for the destructive and the rare.

Keys	Act
Tab g Enter Esc	cycle modes · go to a mode · zoom in · unwind one rung
a A e E Ctrl+E	capture · child · inline edit · description · external editor
w	the workflow chord: wi wb wn wt wg ww wp wm wd wc, and wh hide/unhide
! @ # *	priority · due, defer, and check-in · tags and context · pin
- +	step the deadline one day earlier · one day later
[ ] > < % ~	outdent · indent · set parent · adopt children · move project · dependencies
J/K Ctrl+J/Ctrl+K	reorder one step · reorder to the far end
/ f F o	search · row facets, fH the hidden tasks · which projects load · sort
P Ctrl+P \	project scope · pinned projects · named lenses
v V Ctrl+A	select one · select a range · select every visible row
& ; b O	attachments · comments · Peek · outline-edit the project
y/Y u/Ctrl+R Ctrl+N T	copy · undo and redo · Notes · theme
Space ? q/Ctrl+C	menu · the generated key reference for this surface · quit

? is always the honest answer: it is generated from the same operation descriptors that dispatch the keys, for whichever surface you are on. docs/guide/outliner-keys.md has the full table.

Maintenance CLI

docket [--no-advisories] [--no-mouse] [--notify] [--control PATH [--headless]]
docket doctor [--fix] [--json]
docket conflict list [--json]
docket conflict show <id> [--json]
docket conflict resolve <id> --use local|remote|file [--file PATH]
docket sync enroll --exchange DIR --working-copy DIR [--snapshot-dir DIR] [--force]
docket sync join --exchange DIR --working-copy DIR
docket sync status [--json]
docket sync exchange [--folder DIR] [--json]
docket sync doctor [--json]
docket sync conflicts [ID] [--json]
docket sync resolve ID --version N|--current|--file PATH [--json]
docket sync diagnostics [--output FILE]
docket workspace [location]
docket workspace move <destination> [--force]
docket workspace backup <backup-directory>
docket workspace verify-backup <snapshot-directory>
docket completion bash|zsh|fish
docket project export <slug-or-id> [--file PATH|-]
docket project export --all [--dir DIR]
docket --version

Global flags are --data-dir and --no-color. Run docket help <command> for per-command syntax.

For device sync, enroll once or join an existing exchange. Each device keeps a local working copy; the exchange folder carries changes between them. Enrollment preserves the original workspace.

Where to read more

Start with the everyday recipes, or look up a specific action in docs/guide/:

• docs/guide/outliner.md — the index to the four Outliner files: the modes, the chrome around the list, the full key table and task actions, and row indicators, checklists, Peek, and multi-select.
• docs/guide/capture.md — everyday capture and editing, with a linked syntax reference.
• docs/guide/search-and-lenses.md — finding work and saving views, with a linked search reference.
• docs/guide/projects-and-notes.md — project scope, Select Project, project tags including parked, All Notes.
• docs/guide/storage.md — working copies, file exchange, undo, backups, migration, and conflict recovery.
• docs/guide/retired-keys.md — every retired key, per surface, and what answers it now.

Mechanism — data boundaries, transaction mechanics, migration internals, platform support — is docs/architecture.md. Contributor invariants are CLAUDE.md, and the TUI scenario harness is docs/tui-testing/README.md.

Development

just test
./scripts/check_docs.sh
./scripts/run_tui_scenarios.sh
just search-bench
just ci
just readme-media

The scenario script replays the committed final-product TUI workflows plus the snapshot-first migration and interrupted-activation recovery scenarios. It re-selects tests just test and just ci already run, for a faster loop while authoring one.

just readme-media re-records the animation above from TestReadmeDemo (it needs uv); CI fails when the committed copy no longer matches what the app draws.

The daily-use polish review records presentation checks, search measurements, and allocation budgets. Run just search-bench --strict-time on an idle machine to enforce latency targets too.

License

MIT — see LICENSE.