Skip to content

docs: backfill missing CLI documentation #165

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
marcus wants to merge 1 commit into
base: codex/lint-fix
Choose a base branch
from
Open

docs: backfill missing CLI documentation #165

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ A minimalist CLI for tracking tasks across AI coding sessions. When your context

**Key Features**: Query-based boards, dependency graphs, epic tracking, powerful query language (TDQ), session analytics, and state machine workflows.

![td](docs/td.png)
![td](website/static/img/td.png)

## Table of Contents

Expand Down Expand Up @@ -172,7 +172,7 @@ td/
2. Git integration captures snapshots at start/handoff
3. Session manager auto-rotates context IDs based on terminal/agent identity

See [SPEC.md](./SPEC.md) for detailed schemas and workflows.
See [SPEC.md](./docs/implemented/SPEC.md) for detailed schemas and workflows.

## Development

Expand Down Expand Up @@ -477,8 +477,6 @@ Shows current focus, activity log across sessions, and ready tasks. Useful for k

**Statistics Dashboard** — Press `s` to open the stats modal and see key metrics:

![td stats modal](docs/stats-modal.png)

The dashboard displays:

- **Status Breakdown** — Visual bar chart showing task distribution across statuses (open, in_progress, blocked, in_review, closed)
Expand Down Expand Up @@ -521,12 +519,14 @@ Full documentation is available at [marcus.github.io/td](https://marcus.github.i
- [Getting Started](https://marcus.github.io/td/docs/intro)
- [Core Workflow](https://marcus.github.io/td/docs/core-workflow)
- [AI Agent Integration](https://marcus.github.io/td/docs/ai-integration)
- [Notes](https://marcus.github.io/td/docs/notes)
- [Sync and Collaboration](https://marcus.github.io/td/docs/sync-collaboration)
- [Command Reference](https://marcus.github.io/td/docs/command-reference)

## Design Philosophy

- **Minimal** — Does one thing. Not a project management suite.
- **Local** — SQLite in `.todos/`. No server, no sync, no account.
- **Local-first** — SQLite in `.todos/` by default, with optional sync when teams need collaboration.
- **Portable** — Works with any AI tool that can run shell commands.
- **Opinionated** — Enforces handoffs. That's the point.

Expand Down
3 changes: 2 additions & 1 deletion docs/guides/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

This directory contains legacy and in-repo implementation guides.

The long-term direction is to keep **task workflow guidance** in skills and keep **project-specific architecture/design docs** in `docs/`.
The long-term direction is to keep **task workflow guidance** in skills, **user-facing guides** in the Docusaurus site under `website/docs/`, and **project-specific architecture/design docs** in `docs/`.

## Where Skills Live

Expand Down Expand Up @@ -52,5 +52,6 @@ None yet.
## Link Policy During Migration

- Active, authoritative workflow guidance should point to skill paths when a skill fully replaces a guide.
- User-facing notes, sync/collaboration, and system diagnostics guidance should point to `website/docs/notes.md`, `website/docs/sync-collaboration.md`, and `website/docs/system-diagnostics.md`.
- Historical/spec references should point to `docs/deprecated/guides/` **after** a covered guide is moved there.
- If a guide is not fully covered, keep links pointed at `docs/guides/`.
203 changes: 142 additions & 61 deletions website/docs/command-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,51 +4,69 @@ sidebar_position: 11

# Command Reference

Complete reference for all `td` commands.
Complete reference for the user-facing `td` CLI command surface.

Run `td <command> --help` for the exact flags accepted by your installed version.

## Core Commands

| Command | Description |
|---------|-------------|
| `td create "title" [flags]` | Create issue. Flags: `--type`, `--priority`, `--description`, `--description-file`, `--acceptance`, `--acceptance-file`, `--parent`, `--epic`, `--minor` |
| `td list [flags]` | List issues. Flags: `--status`, `--type`, `--priority`, `--epic` |
| `td show <id>` | Display full issue details |
| `td update <id> [flags]` | Update fields. Flags: `--title`, `--type`, `--priority`, `--description`, `--description-file`, `--acceptance`, `--acceptance-file`, `--labels` |
| `td delete <id>` | Soft-delete issue |
| `td restore <id>` | Restore soft-deleted issue |
| `td create "title" [flags]` | Create an issue. Aliases: `add`, `new`. Common flags: `--type`, `--priority`, `--description`, `--description-file`, `--acceptance`, `--acceptance-file`, `--parent`, `--epic`, `--minor`, `--defer`, `--due` |
| `td list [flags]` | List issues matching filters. Alias: `ls`. Common flags: `--status`, `--type`, `--priority`, `--epic`, `--json` |
| `td show <id...>` | Display full issue details. Aliases: `context`, `view`, `get` |
| `td update <id> [flags]` | Update fields on an issue. Alias: `edit`. Common flags: `--title`, `--type`, `--priority`, `--description`, `--description-file`, `--acceptance`, `--acceptance-file`, `--labels`, `--append`, `--defer`, `--due` |
| `td delete <id...>` | Soft-delete one or more issues |
| `td deleted [--json]` | Show soft-deleted issues |
| `td restore <id...>` | Restore soft-deleted issues |
| `td task ...` | Shortcuts for working with tasks |
| `td epic ...` | Shortcuts for working with epics |

## Workflow Commands

| Command | Description |
|---------|-------------|
| `td start <id>` | Begin work (status -> in_progress) |
| `td unstart <id>` | Revert to open |
| `td log "message" [flags]` | Log progress. Flags: `--decision`, `--blocker`, `--hypothesis`, `--tried`, `--result` |
| `td handoff <id> [flags]` | Capture state. Flags: `--done`, `--remaining`, `--decision`, `--uncertain` |
| `td review <id>` | Submit for review |
| `td reviewable` | Show reviewable issues |
| `td approve <id> [--reason "..."]` | Approve and close. Reason required for creator-exception approvals |
| `td reject <id> --reason "..."` | Reject back to in_progress |
| `td block <id>` | Mark as blocked |
| `td unblock <id>` | Unblock to open |
| `td close <id>` | Admin close (not for completed work) |
| `td reopen <id>` | Reopen closed issue |
| `td comment <id> "text"` | Add comment |

## Deferral & Due Dates
| `td start <id...>` | Begin work. Alias: `begin` |
| `td unstart <id...>` | Revert in-progress issues to open. Alias: `stop` |
| `td log "message" [flags]` | Append progress to the current issue. Flags include `--decision`, `--blocker`, `--hypothesis`, `--tried`, `--result` |
| `td handoff <id> [flags]` | Capture structured working state. Flags: `--done`, `--remaining`, `--decision`, `--uncertain` |
| `td review <id...>` | Submit issues for review. Aliases: `submit`, `finish` |
| `td reviewable [--include-approved]` | Show issues the current session can review; optionally include reviewed issues that can be closed |
| `td approve <id...> [flags]` | Approve and close, record-only review, or close using a recorded approval. Flags include `--reason`, `--record-only`, `--decision approved\|changes_requested`, `--all` |
| `td reject <id> --reason "..."` | Reject an issue and return it to open |
| `td block <id...>` | Mark issues as blocked |
| `td unblock <id...>` | Unblock issues back to open |
| `td close <id...>` | Admin close without review. Aliases: `done`, `complete` |
| `td reopen <id...>` | Reopen closed issues |
| `td comment <id> "text"` | Add a comment. Alias for `td comments add` |
| `td comments <id>` | List comments for an issue |
| `td comments add <id> "text"` | Add a comment to an issue |

## Review Flag Details

`td approve` can be used in delegated review flows:

| Invocation | Effect |
|------------|--------|
| `td approve <id>` | Direct reviewer-close. The caller must be an eligible reviewer when no active approval is already recorded |
| `td approve <id> --record-only --reason "..."` | Record an approval review without closing. The caller must be an eligible reviewer |
| `td approve <id> --record-only --decision changes_requested --reason "..."` | Record a non-approving review without closing |
| `td approve <id> --reason "..."` | Close using an existing recorded approval. Non-reviewer closes require a reason |

Use `td reviewable --include-approved` to find reviewed issues that can be closed after an independent approval has been recorded.

## Deferral and Due Dates

| Command | Description |
|---------|-------------|
| `td defer <id> <date>` | Defer issue until a future date |
| `td defer <id> --clear` | Remove deferral, make immediately actionable |
| `td due <id> <date>` | Set due date on an issue |
| `td due <id> --clear` | Remove due date |

Date formats: `+7d`, `+2w`, `+1m`, `monday`, `tomorrow`, `next-week`, `next-month`, `2026-03-15`
| `td defer <id> <date>` | Defer an issue until a future date |
| `td defer <id> --clear` | Remove deferral |
| `td due <id> <date>` | Set a due date |
| `td due <id> --clear` | Remove a due date |

The `--defer` and `--due` flags are also available on `td create` and `td update`.
Date formats include `+7d`, `+2w`, `+1m`, `monday`, `tomorrow`, `next-week`, `next-month`, and `2026-03-15`.

**List filters:** `--all` (include deferred), `--deferred`, `--surfacing`, `--overdue`, `--due-soon`
List filters include `--all`, `--deferred`, `--surfacing`, `--overdue`, and `--due-soon`.

## Agent-Safe Rich Text Input

Expand All @@ -62,16 +80,16 @@ td create "Document sync failure modes" \
cat docs/acceptance.md | td update td-a1b2 --append --acceptance-file -
```

## Query & Search
## Query and Search

| Command | Description |
|---------|-------------|
| `td query "expression"` | TDQ query |
| `td search "keyword"` | Full-text search |
| `td next` | Highest-priority open issue |
| `td ready` | Open issues by priority |
| `td query "expression"` | Search with the TDQ query language |
| `td search "keyword"` | Full-text search across issues |
| `td next` | Show the highest-priority open issue |
| `td ready` | List open issues sorted by priority |
| `td blocked` | List blocked issues |
| `td in-review` | List in-review issues |
| `td in-review` | List issues currently in review. Alias: `ir` |

## Dependencies

Expand All @@ -80,9 +98,10 @@ cat docs/acceptance.md | td update td-a1b2 --append --acceptance-file -
| `td dep add <issue> <depends-on>` | Add dependency |
| `td dep rm <issue> <depends-on>` | Remove dependency |
| `td dep <issue>` | Show dependencies |
| `td dep <issue> --blocking` | Show what it blocks |
| `td blocked-by <issue>` | Issues blocked by this |
| `td critical-path` | Optimal unblocking sequence |
| `td dep <issue> --blocking` | Show issues blocked by this issue |
| `td depends-on <issue>` | Show what an issue depends on. Aliases: `deps`, `dependencies` |
| `td blocked-by <issue>` | Show issues waiting on this issue |
| `td critical-path` | Show the sequence that unblocks the most work |

## Boards

Expand All @@ -95,53 +114,115 @@ cat docs/acceptance.md | td update td-a1b2 --append --acceptance-file -
| `td board edit <board> [flags]` | Edit board |
| `td board delete <board>` | Delete board |

## Epics & Trees
## Epics and Trees

| Command | Description |
|---------|-------------|
| `td epic create "title" [flags]` | Create epic |
| `td epic list` | List epics |
| `td tree <id>` | Show tree |
| `td tree <id>` | Show parent/child tree |
| `td tree add-child <parent> <child>` | Add child |

## Notes

| Command | Description |
|---------|-------------|
| `td note add <title> [--content "..."]` | Create a freeform note. Opens `$EDITOR` when content is omitted |
| `td note list [flags]` | List notes. Alias: `ls`. Flags include `--pinned`, `--archived`, `--all`, `--search`, `--limit`, `--json`, `--output table\|json` |
| `td note show <id> [--json]` | Display note details |
| `td note edit <id> [flags]` | Edit title or content. Flags: `--title`, `--content`; opens `$EDITOR` if neither is provided |
| `td note delete <id>` | Soft-delete a note |
| `td note pin <id>` | Pin a note |
| `td note unpin <id>` | Unpin a note |
| `td note archive <id>` | Archive a note |
| `td note unarchive <id>` | Unarchive a note |

## Sessions

| Command | Description |
|---------|-------------|
| `td usage [flags]` | Agent context. Flags: `--new-session`, `-q` |
| `td session [name]` | Name session |
| `td session --new` | Force new session |
| `td status` | Dashboard view |
| `td focus <id>` | Set focus |
| `td usage [flags]` | Generate optimized context for agents. Flags: `--new-session`, `-q` |
| `td session [name]` | Name the current session |
| `td session --new` | Force a new session at context start |
| `td status` | Show dashboard view. Alias: `current` |
| `td focus <id>` | Set current focus |
| `td unfocus` | Clear focus |
| `td whoami` | Show session identity |
| `td resume [id]` | Show context and set focus |
| `td check-handoff [flags]` | Exit nonzero when in-progress work needs handoff. Flags: `--json`, `--quiet` |
| `td whoami` | Show current session identity |

## Work Sessions

| Command | Description |
|---------|-------------|
| `td ws start "name"` | Start work session |
| `td ws start "name"` | Start a multi-issue work session. Alias: `worksession` |
| `td ws tag <ids...>` | Tag issues |
| `td ws log "message"` | Log to all tagged |
| `td ws current` | Show session state |
| `td ws handoff` | Handoff all, end session |
| `td ws log "message"` | Log to all tagged issues |
| `td ws current` | Show work session state |
| `td ws handoff` | Handoff tagged issues and end the work session |

## Files

| Command | Description |
|---------|-------------|
| `td link <id> <files...>` | Link files to issue |
| `td unlink <id> <files...>` | Unlink files |
| `td files <id>` | Show file status |
| `td link <id> <files...>` | Link files to an issue |
| `td unlink <id> <files...>` | Remove file associations |
| `td files <id>` | List linked files with change status |

## Sync and Collaboration

## System
| Command | Description |
|---------|-------------|
| `td auth login` | Log in to the sync server |
| `td auth logout` | Log out from the sync server |
| `td auth status` | Show authentication status |
| `td sync` | Push and pull local events with the linked remote project |
| `td sync --push` | Push only |
| `td sync --pull` | Pull only |
| `td sync --status` | Show sync status only |
| `td sync init` | Interactive guided sync setup |
| `td sync conflicts` | Show recent sync conflicts |
| `td sync tail` | Show recent sync activity |
| `td sync-project create <name> [--description "..."]` | Create and auto-link a remote sync project. Alias: `sp` |
| `td sync-project link <project-id> [--force]` | Link local project to a remote sync project |
| `td sync-project join [name-or-id]` | Join a remote sync project by name or ID |
| `td sync-project list` | List remote sync projects |
| `td sync-project members` | List project members |
| `td sync-project invite <email> [role]` | Invite a member. Valid roles: `owner`, `writer`, `reader`; default: `writer` |
| `td sync-project kick <user-id>` | Remove a member |
| `td sync-project role <user-id> <role>` | Change a member role. Valid roles: `owner`, `writer`, `reader` |
| `td sync-project unlink [--force]` | Unlink local project from remote sync |
| `td doctor` | Run sync setup diagnostics |

## System and Diagnostics

| Command | Description |
|---------|-------------|
| `td init` | Initialize project |
| `td init` | Initialize a project |
| `td monitor` | Live TUI dashboard |
| `td undo` | Undo last action |
| `td version` | Show version |
| `td export` | Export database |
| `td import` | Import issues |
| `td stats [subcommand]` | Usage statistics |
| `td serve` | Start the td HTTP API server |
| `td undo` | Undo the last action |
| `td last` | Show the last action performed |
| `td version [--short] [--check]` | Show version and optionally check for updates |
| `td export [flags]` | Export issues. Flags: `--format json\|md`, `--output`, `--all`, `--render-markdown` |
| `td import [file] [flags]` | Import issues. Flags: `--format json\|md`, `--dry-run`, `--force` |
| `td info [--json]` | Show database statistics and project overview. Alias: `stats` |
| `td stats analytics` | Show command usage analytics. Alias: `td stats usage` |
| `td stats security` | Show security exception log. Alias for `td security` |
| `td stats errors` | Show failed command attempts. Alias for `td errors` |
| `td config list` | List all config values |
| `td config get <key>` | Get a config value |
| `td config set <key> <value>` | Set a config value |
| `td config associate [dir] <target>` | Associate a directory with a td project |
| `td config associations` | List directory associations. Alias: `assoc` |
| `td config dissociate [dir]` | Remove a directory association |
| `td feature list` | List known feature flags and resolved states |
| `td feature get <flag>` | Get feature flag state |
| `td feature set <flag> <value>` | Set a local feature flag override |
| `td feature unset <flag>` | Remove a local feature flag override |
| `td errors [flags]` | View failed td command attempts. Flags: `--limit`, `--since`, `--session`, `--json`, `--count`, `--clear` |
| `td security [flags]` | View security exception audit log. Flags: `--json`, `--clear` |
| `td workflow [--dot] [--mermaid]` | Show issue status workflow |
| `td upgrade` | Run pending database migrations |
| `td completion <shell>` | Generate shell completion |
| `td debug-stats` | Output runtime memory and goroutine statistics as JSON |
Loading
Loading