Skip to content

docs: backfill website docs for notes and sync #114

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 2 commits into
base: main
Choose a base branch
from
Open

docs: backfill website docs for notes and sync #114

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3b4c9f7
docs: backfill website docs for notes and sync
Apr 6, 2026
b6e294e
docs: fix sync command enablement guidance
Apr 6, 2026
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
2 changes: 1 addition & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -136,7 +136,7 @@ cat docs/issue-description.md | td update td-a1b2 --append --description-file -
td start <issue-id>
```

For complete guides, see the [full documentation](https://marcus.github.io/td/docs/intro).
For complete guides, see [Getting Started](https://marcus.github.io/td/docs/intro), [Notes](https://marcus.github.io/td/docs/notes), and [Sync & Collaboration](https://marcus.github.io/td/docs/sync-collaboration).

## Claude Code / OpenAI Codex Skill

Expand Down
256 changes: 145 additions & 111 deletions website/docs/command-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,147 +1,181 @@
---
sidebar_position: 11
sidebar_position: 13
---

# Command Reference

Complete reference for all `td` commands.
Complete reference for the `td` CLI, including note management, work session helpers, diagnostics, and the feature-gated sync workflow.

## Core Commands
> **Note**: Sync and config commands are hidden unless `sync_cli` is enabled for the current process. Use `export TD_ENABLE_FEATURE=sync_cli` in your shell, or prefix one command with `TD_FEATURE_SYNC_CLI=true`. `td feature set sync_cli true` updates project config, but it does not register hidden commands.

## Core Issue 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. Common flags: `--type`, `--priority`, `--description`, `--description-file`, `--acceptance`, `--acceptance-file`, `--parent`, `--epic`, `--minor`, `--defer`, `--due` |
| `td list [flags]` | List issues. Common filters: `--status`, `--type`, `--priority`, `--epic`, `--all`, `--deferred`, `--surfacing`, `--overdue`, `--due-soon` |
| `td show &lt;id&gt;` | Display full details for one or more issues |
| `td update &lt;id&gt; [flags]` | Update issue fields, including rich text fields from files or stdin |
| `td delete &lt;id&gt;` | Soft-delete one or more issues |
| `td restore &lt;id&gt;` | Restore one or more soft-deleted issues |
| `td deleted` | List soft-deleted issues |
| `td task create "title"` | Create a task shortcut (`--type task`) |
| `td task list` | List task issues only |
| `td epic create "title"` | Create an epic |
| `td epic list` | List epics |
| `td note add "title"` | Create a freeform note |
| `td note list` | List notes with filters such as `--pinned`, `--archived`, `--search`, `--json` |
| `td note show &lt;id&gt;` | Show a note |
| `td note edit &lt;id&gt;` | Edit a note title or content |
| `td note pin &lt;id&gt;` / `td note unpin &lt;id&gt;` | Pin or unpin a note |
| `td note archive &lt;id&gt;` / `td note unarchive &lt;id&gt;` | Archive or restore a note |
| `td note delete &lt;id&gt;` | Soft-delete a note |

## 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

| 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`

The `--defer` and `--due` flags are also available on `td create` and `td update`.

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

## Agent-Safe Rich Text Input

Use `--description-file` and `--acceptance-file` for markdown-heavy fields so shells do not mangle code fences, quotes, or blank lines. Pass `-` to read the full field from stdin.

```bash
td create "Document sync failure modes" \
--description-file docs/issue-description.md \
--acceptance-file docs/issue-acceptance.md

cat docs/acceptance.md | td update td-a1b2 --append --acceptance-file -
```

## Query & Search
| `td start &lt;id&gt;` | Move issue to `in_progress` |
| `td unstart &lt;id&gt;` | Move issue back to `open` |
| `td block &lt;id&gt;` | Mark one or more issues blocked |
| `td unblock &lt;id&gt;` | Return blocked issues to `open` |
| `td review &lt;id&gt;` | Submit one or more issues for review |
| `td approve &lt;id&gt; [--reason "..."]` | Approve and close issues |
| `td reject &lt;id&gt; --reason "..."` | Reject issues back to active work |
| `td close &lt;id&gt;` | Close issues directly without review |
| `td reopen &lt;id&gt;` | Reopen closed issues |
| `td handoff &lt;id&gt; [flags]` | Capture done/remaining/decision/uncertain state before ending a session |
| `td resume [id]` | Show context and set focus |
| `td log "message" [flags]` | Add progress, blocker, decision, hypothesis, tried, or result logs |
| `td comment &lt;id&gt; "text"` | Add a comment shortcut |
| `td comments &lt;id&gt;` | List comments for an issue |
| `td comments add &lt;id&gt; "text"` | Add a comment via the comment subcommand |
| `td workflow` | Print the issue state workflow summary |
| `td check-handoff` | Exit non-zero when the current focus still needs a handoff |

## Query, Dependencies, And Boards

| 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"` | Run a TDQ query |
| `td search "keyword"` | Full-text search across issues |
| `td next` | Show the highest-priority open issue |
| `td ready` | List ready issues by priority |
| `td blocked` | List blocked issues |
| `td in-review` | List in-review issues |

## Dependencies

| Command | Description |
|---------|-------------|
| `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 in-review` | List issues in review |
| `td reviewable` | List issues you can review from this session |
| `td dep add &lt;issue&gt; &lt;depends-on&gt;...` | Add dependencies |
| `td dep rm &lt;issue&gt; &lt;depends-on&gt;` | Remove dependencies |
| `td dep &lt;issue&gt;` | Show dependencies for an issue |
| `td dep &lt;issue&gt; --blocking` | Show issues this work item blocks |
| `td blocked-by &lt;issue&gt;` | Show issues waiting on this issue |
| `td depends-on &lt;issue&gt;` | Show issues this issue depends on |
| `td critical-path` | Show the best unblocking order |
| `td tree &lt;id&gt;` | Show the issue tree, with optional `--depth` or `--json` |
| `td board create "name" --query "..."` | Create a board from a TDQ query |
| `td board list` | List boards |
| `td board show &lt;board&gt;` | Show board results, optionally filtered by status |
| `td board move &lt;board&gt; &lt;id&gt; &lt;position&gt;` | Set explicit ordering for a card on a board |
| `td board unposition &lt;board&gt; &lt;id&gt;` | Remove a board-specific position override |
| `td board edit &lt;board&gt;` | Rename a board or change its query |
| `td board delete &lt;board&gt;` | Delete a board |

## Boards
## Sessions And Work Sessions

| Command | Description |
|---------|-------------|
| `td board create "name" --query "..."` | Create board |
| `td board list` | List boards |
| `td board show <board>` | Show board |
| `td board move <board> <id> <pos>` | Position issue |
| `td board edit <board> [flags]` | Edit board |
| `td board delete <board>` | Delete board |

## Epics & Trees
| `td usage [--new-session] [-q]` | Generate AI-friendly context for the current project |
| `td session [name]` | Label the current session |
| `td session --new` | Force a new session at context start |
| `td session list` | List branch- and agent-scoped sessions |
| `td session cleanup` | Remove stale session files |
| `td whoami` | Show the current session identity |
| `td status` | Show the dashboard view |
| `td focus &lt;id&gt;` | Set the focused issue |
| `td unfocus` | Clear the focus |
| `td ws start "name"` | Start a multi-issue work session |
| `td ws tag &lt;ids...&gt;` | Tag issues into the active work session |
| `td ws tag &lt;ids...&gt; --no-start` | Tag issues without auto-starting open work |
| `td ws untag &lt;ids...&gt;` | Remove issues from the active work session |
| `td ws log "message"` | Log once to the work session and all tagged issues |
| `td ws current` | Show the active work session |
| `td ws handoff` | Generate handoffs for tagged issues and end the session |
| `td ws end` | End the current work session without handoff generation |
| `td ws list` | List recent work sessions |
| `td ws show &lt;session-id&gt;` | Show a past work session |

## Files And Directory Associations

| Command | Description |
|---------|-------------|
| `td epic create "title" [flags]` | Create epic |
| `td epic list` | List epics |
| `td tree <id>` | Show tree |
| `td tree add-child <parent> <child>` | Add child |
| `td link &lt;id&gt; &lt;files...&gt;` | Link files or globs to an issue |
| `td unlink &lt;id&gt; &lt;files...&gt;` | Remove linked files |
| `td files &lt;id&gt;` | Show linked files and change status |
| `td config associate [dir] &lt;project&gt;` | Associate a directory with a td project root |
| `td config associations` | List directory-to-project associations |
| `td config dissociate [dir]` | Remove a directory association |

## Sessions
## System And Diagnostics

| 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 unfocus` | Clear focus |
| `td whoami` | Show session identity |

## Work Sessions
| `td init` | Initialize a td project |
| `td monitor` | Launch the live TUI dashboard |
| `td serve` | Start the td HTTP API server |
| `td info` | Show project overview and database stats |
| `td stats analytics` | Show command usage analytics |
| `td stats errors` / `td errors` | Show failed command attempts |
| `td stats security` / `td security` | Show workflow exception audit events |
| `td undo` | Undo the last action |
| `td last` | Show the last action performed |
| `td export` | Export the database |
| `td import &lt;file&gt;` | Import issues |
| `td upgrade` | Run database migrations |
| `td feature list` | List experimental features and resolved state |
| `td feature get &lt;name&gt;` | Get one feature flag |
| `td feature set &lt;name&gt; &lt;true\|false&gt;` | Set a project-level feature override |
| `td feature unset &lt;name&gt;` | Remove a project-level feature override |
| `td debug-stats` | Print runtime memory and goroutine stats as JSON |
| `td version` | Show the current version and update info |

## Sync And Collaboration Commands

These commands are available only when `sync_cli` is enabled through an environment override for the current process. See [Sync & Collaboration](./sync-collaboration.md) for setup and troubleshooting.

| Command | Description |
|---------|-------------|
| `td ws start "name"` | Start work session |
| `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 auth login` | Authenticate with a sync server |
| `td auth status` | Show current auth status |
| `td auth logout` | Remove local credentials |
| `td config set &lt;key&gt; &lt;value&gt;` | Set sync config such as `sync.url` or autosync behavior |
| `td config get &lt;key&gt;` | Read one config value |
| `td config list` | Print config as JSON |
| `td doctor` | Run sync diagnostics |
| `td sync init` | Guided sync setup |
| `td sync` | Push then pull changes |
| `td sync --push` | Push only |
| `td sync --pull` | Pull only |
| `td sync --status` | Show local and server sync state |
| `td sync conflicts` | Show recent overwrite conflicts |
| `td sync tail` | Show recent sync activity, optionally with `-f` |
| `td sync-project create "name"` | Create and link a remote sync project |
| `td sync-project join [name-or-id]` | Join an invited project by picker, name, or ID |
| `td sync-project link &lt;project-id&gt;` | Link directly to a known project ID |
| `td sync-project unlink` | Remove the local remote-project link |
| `td sync-project list` | List available remote projects |
| `td sync-project members` | List members on the linked project |
| `td sync-project invite &lt;email&gt; [role]` | Invite a collaborator as `writer`, `reader`, or `owner` |
| `td sync-project role &lt;user-id&gt; &lt;role&gt;` | Change a member role |
| `td sync-project kick &lt;user-id&gt;` | Remove a member |

## Files
## Agent-Safe Rich Text Input

| Command | Description |
|---------|-------------|
| `td link <id> <files...>` | Link files to issue |
| `td unlink <id> <files...>` | Unlink files |
| `td files <id>` | Show file status |
Use `--description-file` and `--acceptance-file` for markdown-heavy content so your shell does not mangle code fences, quotes, or blank lines. Pass `-` to read the field from stdin.

## System
```bash
td create "Document sync failure modes" \
--description-file docs/issue-description.md \
--acceptance-file docs/issue-acceptance.md

| Command | Description |
|---------|-------------|
| `td init` | Initialize 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 |
cat docs/acceptance.md | td update td-a1b2 --append --acceptance-file -
```
2 changes: 2 additions & 0 deletions website/docs/intro.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -93,5 +93,7 @@ Works with Claude Code, Cursor, Codex, Copilot, and Gemini CLI.
## Next Steps

- [Core Workflow](./core-workflow.md) -- Issue lifecycle, logging, handoffs, and reviews in depth
- [Notes](./notes.md) -- Capture freeform project context without creating an issue
- [Boards](./boards.md) -- Visual overview of issue status across your project
- [Sync & Collaboration](./sync-collaboration.md) -- Enable shared projects, auth, and remote sync
- [Query Language](./query-language.md) -- Filter and search issues with structured queries
Loading
Loading