Skip to content

docs: backfill website CLI docs #170

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

docs: backfill website CLI docs #170

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
8 changes: 5 additions & 3 deletions website/docs/ai-integration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -101,14 +101,16 @@ td supports three review policy modes via `review_policy_mode`:

The legacy `balanced_review_policy` flag is deprecated; prefer `review_policy_mode=balanced` instead.

Pin or change the mode:
Use the default `delegated` mode unless your project needs a stricter policy. For one-off commands, set the environment override:

```bash
td feature set review_policy_mode strict # or balanced, or delegated
# or, one-off:
TD_FEATURE_REVIEW_POLICY_MODE=strict td approve td-a1b2
```

For a persistent project override, set `feature_string_flags.review_policy_mode` in `.todos/config.json` to `strict`, `balanced`, or `delegated`.

When agents move between machines or shared environments, [Sync and Collaboration](./sync.md) covers the commands for linking a project, inviting teammates, and pulling remote updates.

### Delegated Review: Orchestrator + Sub-Agents

Under `delegated`, an orchestrator coordinates work across sub-agents. The review must come from a session that did not participate in implementation, but the close may be performed by any session — so the orchestrator can finish the task once a reviewer sub-agent records approval.
Expand Down
6 changes: 4 additions & 2 deletions website/docs/analytics.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ Shows which commands are used most, frequency patterns, and usage over time.
td stats security
```

Shows self-close exceptions (when issues were closed without proper review workflow).
Shows review workflow exceptions, such as administrative closes or legacy creator-approval exceptions.

## Error Tracking

Expand All @@ -30,6 +30,8 @@ td stats errors

Shows failed command attempts - useful for debugging agent issues.

For filters and cleanup commands, see [Troubleshooting](./troubleshooting.md#command-error-logs).

## Monitor Stats

Press `s` in the monitor to view:
Expand All @@ -50,4 +52,4 @@ Set this environment variable to disable local analytics collection.

## Data Storage

All analytics stored in local SQLite database (`.todos/db.sqlite`). Nothing leaves your machine.
All analytics are stored in the local SQLite database (`.todos/issues.db`). Nothing leaves your machine.
69 changes: 66 additions & 3 deletions website/docs/command-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,20 @@ Complete reference for all `td` commands.
| `td delete <id>` | Soft-delete issue |
| `td restore <id>` | Restore soft-deleted issue |

## Notes

| Command | Description |
|---------|-------------|
| `td note add "title" [--content "..."]` | Create a freeform note. Opens `$EDITOR` when content is omitted |
| `td note list [flags]` | List notes. Flags: `--pinned`, `--archived`, `--all`, `--search`, `--limit`, `--json` |
| `td note show <id>` | Display a note |
| `td note edit <id> [flags]` | Edit note title or content. Flags: `--title`, `--content` |
| `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>` | Restore an archived note |

## Workflow Commands

| Command | Description |
Expand All @@ -25,15 +39,16 @@ Complete reference for all `td` commands.
| `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. Submitting session is recorded as `review_requested_by_session` |
| `td review <id> [flags]` | Submit for review. Flags: `--reason`, `--minor`, `--json`. Submitting session is recorded as `review_requested_by_session` |
| `td reviewable [--include-approved]` | Show issues you can review; with `--include-approved`, also show reviewed issues you can close |
| `td approve <id> [flags]` | Approve and close, record-only review, or close using a recorded approval. Flags: `--reason`, `--record-only`, `--decision approved\|changes_requested`, `--all` |
| `td reject <id> --reason "..."` | Reject back to open. Supersedes any active approval review |
| `td approve <id> [flags]` | Approve and close, record-only review, or close using a recorded approval. Flags: `--reason`, `--record-only`, `--decision approved\|changes_requested`, `--all`, `--json` |
| `td reject <id> --reason "..."` | Reject back to open. Supersedes any active approval review. Flags: `--reason`, `--json` |
| `td block <id>` | Mark as blocked |
| `td unblock <id>` | Unblock to open |
| `td close <id>` | Admin close only (duplicates, won't-fix, cleanup). Use `td approve` for reviewed work |
| `td reopen <id>` | Reopen closed issue |
| `td comment <id> "text"` | Add comment |
| `td workflow [--mermaid\|--dot]` | Show the issue status workflow |

## Deferral & Due Dates

Expand Down Expand Up @@ -127,6 +142,7 @@ cat docs/acceptance.md | td update td-a1b2 --append --acceptance-file -
| `td session [name]` | Name session |
| `td session --new` | Force new session |
| `td status` | Dashboard view |
| `td resume <id>` | Show issue context and set focus |
| `td focus <id>` | Set focus |
| `td unfocus` | Clear focus |
| `td whoami` | Show session identity |
Expand All @@ -149,14 +165,61 @@ cat docs/acceptance.md | td update td-a1b2 --append --acceptance-file -
| `td unlink <id> <files...>` | Unlink files |
| `td files <id>` | Show file status |

## Sync & Collaboration

These commands are registered when the `sync_cli` feature is enabled, for example with `TD_ENABLE_FEATURE=sync_cli`.

| Command | Description |
|---------|-------------|
| `td auth login` | Log in to a sync server with the device flow |
| `td auth status` | Show saved auth status |
| `td auth logout` | Remove local sync credentials |
| `td sync [flags]` | Push and pull local project data. Flags: `--push`, `--pull`, `--status` |
| `td sync init` | Interactive sync setup |
| `td sync tail [flags]` | Show recent sync activity. Flags: `--follow`, `--lines` |
| `td sync conflicts [flags]` | Show recent sync conflicts. Flags: `--limit`, `--since` |
| `td sync-project create "name" [--description "..."]` | Create and link a remote project |
| `td sync-project join [name-or-id]` | Join a remote project by prompt, name, or ID |
| `td sync-project link <project-id> [--force]` | Link local database to a remote project |
| `td sync-project unlink [--force]` | Unlink local database from remote sync |
| `td sync-project list` | List remote projects visible to the current user |
| `td sync-project members` | List project members |
| `td sync-project invite <email> [role]` | Invite a member as `owner`, `writer`, or `reader` |
| `td sync-project role <user-id> <role>` | Change a member role |
| `td sync-project kick <user-id>` | Remove a project member |

## Configuration

| Command | Description |
|---------|-------------|
| `td config list` | List sync config as JSON |
| `td config get <key>` | Read a sync config key |
| `td config set <key> <value>` | Set a sync config key |
| `td config associate [dir] <target>` | Associate a directory with a td project |
| `td config associations` | List directory associations |
| `td config dissociate [dir]` | Remove a directory association |
| `td feature list` | List known feature flags and resolved state |
| `td feature get <name>` | Show one feature flag |
| `td feature set <name> <true\|false>` | Set a project-local feature flag |
| `td feature unset <name>` | Remove a project-local feature override |

## System

| Command | Description |
|---------|-------------|
| `td init` | Initialize project |
| `td monitor` | Live TUI dashboard |
| `td undo` | Undo last action |
| `td undo --list` | List recent undoable actions in the current session |
| `td last [-n N]` | Show recent actions in the current session |
| `td doctor` | Run sync diagnostics |
| `td doctor fk` | Report foreign-key orphan counts without modifying data |
| `td errors [flags]` | View failed command attempts. Flags: `--since`, `--session`, `--limit`, `--json`, `--count`, `--clear` |
| `td security [flags]` | View review/close exception audit log. Flags: `--json`, `--clear` |
| `td version` | Show version |
| `td export` | Export database |
| `td import` | Import issues |
| `td stats [subcommand]` | Usage statistics |
| `td stats analytics` | Command usage analytics |
| `td stats errors` | Failed command attempts |
| `td stats security` | Security exception log |
152 changes: 152 additions & 0 deletions website/docs/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,152 @@
---
sidebar_position: 16
---

# Configuration

td stores configuration in a few places because some settings are global to your user account, while others belong to the current project.

## Config Locations

| Location | Scope | Contains |
|----------|-------|----------|
| `~/.config/td/config.json` | User-global | Sync URL, sync enablement, auto-sync settings |
| `~/.config/td/auth.json` | User-global | Sync API key, email, server URL, device ID |
| `~/.config/td/associations.json` | User-global | Directory-to-project associations |
| `.todos/config.json` | Project-local | Focus, active work session, monitor filters, feature flags |
| `.todos/issues.db` | Project-local database | Issues, boards, notes, logs, handoffs, sync state, board positions |

Project-local config is safe to keep with a project. User-global auth files should not be committed.

## Sync Config

`td config` manages sync settings in `~/.config/td/config.json`.

```bash
td config list
td config get sync.url
td config set sync.url https://sync.example.com
```

Supported keys:

| Key | Default | Description |
|-----|---------|-------------|
| `sync.url` | `http://localhost:8080` | Sync server URL |
| `sync.enabled` | `false` when omitted | Stored sync enablement flag |
| `sync.auto.enabled` | `true` | User config switch for auto-sync after the `sync_autosync` feature is enabled |
| `sync.auto.debounce` | `3s` | Minimum time between post-mutation syncs |
| `sync.auto.interval` | `5m` | Periodic sync interval used by monitor workflows |
| `sync.auto.pull` | `true` | Pull as part of auto-sync |
| `sync.auto.on_start` | `true` | Sync when td commands start |
| `sync.snapshot_threshold` | `100` | Server event count before snapshot bootstrap is attempted |

:::info
`td config` is registered with the sync CLI. If the command is unavailable, enable `sync_cli` with `TD_ENABLE_FEATURE=sync_cli`.
:::

## Feature Flags

Use `td feature` for project-local feature flags stored in `.todos/config.json`.

```bash
td feature list
td feature get sync_cli
td feature set sync_cli true
td feature unset sync_cli
```

Known flags include:

| Feature | Default | Purpose |
|---------|---------|---------|
| `balanced_review_policy` | `false` | Deprecated compatibility flag; prefer `review_policy_mode=balanced` |
| `sync_cli` | `false` | Registers sync, auth, project, doctor, and config commands |
| `sync_autosync` | `false` | Enables startup, post-mutation, and monitor auto-sync hooks |
| `sync_monitor_prompt` | `false` | Enables monitor sync setup prompts |
| `sync_notes` | `true` | Allows notes to sync as an entity type |

Environment overrides win over project config:

```bash
TD_FEATURE_SYNC_CLI=true td sync --status
TD_ENABLE_FEATURE=sync_cli,sync_autosync td sync
TD_DISABLE_FEATURE=sync_autosync td list
TD_DISABLE_EXPERIMENTAL=1 td list
```

Auto-sync requires both `sync_autosync=true` and `sync.auto.enabled=true`. The config defaults can be present while the feature flag is still off, so enable the feature first when you expect automatic startup, post-mutation, or monitor sync to run:

```bash
td feature set sync_autosync true
td config set sync.auto.enabled true
```

Feature override forms:

| Variable | Effect |
|----------|--------|
| `TD_FEATURE_<NAME>` | Set a specific feature, such as `TD_FEATURE_SYNC_CLI=true` |
| `TD_ENABLE_FEATURE` or `TD_ENABLE_FEATURES` | Comma-separated features to enable |
| `TD_DISABLE_FEATURE` or `TD_DISABLE_FEATURES` | Comma-separated features to disable |
| `TD_DISABLE_EXPERIMENTAL` | Disable all experimental features |

## Review Policy

Review behavior is controlled by the string feature `review_policy_mode`. New installs default to `delegated`, where an independent reviewer can record an approval and any session can close using that recorded approval.

```bash
TD_FEATURE_REVIEW_POLICY_MODE=delegated td approve td-a1b2
```

Supported values:

| Mode | Behavior |
|------|----------|
| `delegated` | Default. Reviewers can record approval; any session may close after that independent approval exists |
| `strict` | Reviewer must have no prior involvement, and review plus close happen together |
| `balanced` | Strict plus a creator-approval exception for externally implemented work |

For a persistent project override, edit `.todos/config.json`:

```json
{
"feature_string_flags": {
"review_policy_mode": "delegated"
}
}
```

`td feature` manages boolean feature flags. The legacy boolean `balanced_review_policy` still resolves to `balanced` or `strict` when explicitly set, but it is deprecated. Do not set both `review_policy_mode` and `balanced_review_policy`; conflicting values fail closed. See [AI Agent Integration](./ai-integration.md#review-policy-modes) for multi-agent examples.

## Environment Variables

Common environment variables:

| Variable | Purpose |
|----------|---------|
| `TD_WORK_DIR` | Use a project directory without changing the shell cwd |
| `TD_SESSION_ID` | Pin the current agent/session identity |
| `TD_LOG_FILE` | Write td debug logs to a file |
| `TD_ANALYTICS` | Set to `false` to disable local analytics |
| `TD_SYNC_URL` | Override the sync server URL |
| `TD_AUTH_KEY` | Override sync API key |
| `TD_SYNC_SNAPSHOT_THRESHOLD` | Override snapshot bootstrap threshold |
| `TD_SYNC_AUTO` | Override auto-sync enablement |
| `TD_SYNC_AUTO_START` | Override startup auto-sync |
| `TD_SYNC_AUTO_DEBOUNCE` | Override post-mutation debounce |
| `TD_SYNC_AUTO_INTERVAL` | Override periodic auto-sync interval |
| `TD_SYNC_AUTO_PULL` | Override whether auto-sync pulls |

## Directory Associations

Associations let td use one project database while commands run from another directory. This is useful for monorepos, generated worktrees, or tools that launch from nested folders.

```bash
td config associate /path/to/project
td config associate /path/to/nested/dir /path/to/project
td config associations
td config dissociate /path/to/nested/dir
```

Associations are stored in `~/.config/td/associations.json`.
6 changes: 3 additions & 3 deletions website/docs/core-workflow.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -98,14 +98,14 @@ td exposes three policy modes via `review_policy_mode`:

The legacy `balanced_review_policy` flag is **deprecated**; prefer `review_policy_mode=balanced` instead. Setting the legacy flag still works but emits a one-time deprecation warning.

Set the mode per-project or via env:
Use the default `delegated` mode unless your project needs a stricter policy. For one-off commands, set the environment override:

```bash
td feature set review_policy_mode strict # or balanced, or delegated
# or, one-off:
TD_FEATURE_REVIEW_POLICY_MODE=strict td approve td-a1b2
```

For a persistent project override, set `feature_string_flags.review_policy_mode` in `.todos/config.json` to `strict`, `balanced`, or `delegated`.

### Balanced (Legacy) — Creator Exception

Under `balanced`, a session that *created* a task (but didn't implement it) can approve with a reason:
Expand Down
11 changes: 11 additions & 0 deletions website/docs/intro.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,15 @@ td review td-a1b2
Issue IDs like `td-a1b2` are generated automatically when you create an issue. Use `td list` to see your current issues and their IDs.
:::

## Project Memory

Use issues for reviewed work and handoffs. Use [notes](./notes.md) for freeform project memory that should survive across sessions but does not need status, priority, or review.

```bash
td note add "Release runbook" --content "Test, build, tag, publish."
td note pin nt-abc123
```

## Setting Up with AI Agents

Add this to your `CLAUDE.md`, system prompt, or agent instructions:
Expand All @@ -94,4 +103,6 @@ Works with Claude Code, Cursor, Codex, Copilot, and Gemini CLI.

- [Core Workflow](./core-workflow.md) -- Issue lifecycle, logging, handoffs, and reviews in depth
- [Boards](./boards.md) -- Visual overview of issue status across your project
- [Sync and Collaboration](./sync.md) -- Share a td project across machines or teammates
- [Configuration](./configuration.md) -- Config files, feature flags, environment variables
- [Query Language](./query-language.md) -- Filter and search issues with structured queries
Loading
Loading