Storage
The board, CLI, and Herdr plugin share ~/.tsk/tsk.json. The current store format is v5.
Location
Section titled “Location”| Setting | Default | Purpose |
|---|---|---|
TSK_STATE_DIR | ~/.tsk | Task data, backups, trash, and release-check cache. With neither this nor HOME set, tsk refuses to run rather than pick a directory |
--state-dir <dir> | State directory | Override storage for a data command |
Use a local disk. NFS and synced folders such as Dropbox or iCloud Drive are unsupported. Directory roots must be real directories, not symlinks.
Herdr’s plugin-specific state/config directories do not override these locations. Removing tsk leaves its task data intact.
Backups
Section titled “Backups”| File | Contains |
|---|---|
tsk.json | Current tasks and archived-project records |
tsk.json.1 | Previous valid task document |
tsk.json.v<N> | Backup made when migrating an older store format, such as tsk.json.v4 for the v4 → v5 migration |
delivery.json | Which starter tasks this install has received or dismissed, and the newest release note it has seen |
An older binary refuses a newer or unversioned store instead of rewriting it. Use a compatible tsk version to open it. On first save, v4 stores migrate to v5 so one undo entry can cover a marked completion or deletion; the original document is saved as tsk.json.v4. Earlier stores still run through each migration in order, including the v3 to v4 move from ready to open.
Archived tasks stay in the task document with their existing status. Archive and restore.
Starter guides and release notes
Section titled “Starter guides and release notes”The four starter tasks (N1… on your desk) are seeded once per state directory on the first board open. Mark one done, archive it, or delete it and it never returns. Deleting delivery.json seeds any starter catalog id the task document no longer holds.
After an upgrade, the first board open adds one What's new in tsk task to your desk (in review, under NEEDS YOU) when the new version bundles release notes you have not seen. That includes upgrading from a build that only had starter tasks. Every missed release lands in that one task, newest first, with its changelog link in the notes. The notes ship inside the binary; a blank first install records them as seen and shows none. Clear it like any starter task.
Deleted tasks
Section titled “Deleted tasks”Deleted tasks move to trash.jsonl once undo can no longer restore them, or after seven days. They are purged 30 days after deletion.
tsk list --deleted --alltsk trash restore T12The list includes both recently deleted tasks still in the main store and tasks in trash. Restore reads trash; use board undo for a recent deletion that has not moved there yet.
Update check
Section titled “Update check”On launch, tsk checks for a newer release if its cached check is older than 24 hours. A newer version appears on the board’s idle status row as vX.Y.Z available, run tsk update.
| Setting or file | Purpose |
|---|---|
TSK_NO_UPDATE_CHECK | Set to disable the check and notice |
TSK_UPDATE_CURL=/absolute/path/to/curl | Use a nonstandard, explicit curl path for the check and for tsk update (default /usr/bin/curl) |
update.json | Cached release check in the state directory |
The check requests the latest release tag from GitHub over HTTPS only. It does not upload task data. Failures are silent.