| title | Look up Taskset CLI commands |
|---|---|
| description | Complete reference for the taskset command-line interface. |
| contentType | Reference |
| navLabel | CLI Reference |
The taskset command is a thin adapter over @taskset/core for the full Taskset surface: stories, flows, research, decisions, runbooks, lessons, concerns, audits, and tasks. It parses arguments, validates options, calls core operations, and renders human or JSON output.
Invoke it with npx @taskset/cli, pnpm dlx @taskset/cli, yarn dlx @taskset/cli, bunx @taskset/cli, a project binary, or a global install. Examples below use taskset directly.
taskset help
taskset --help
taskset -hRunning without a command also prints usage. These help paths exit with code
0.
Most repository commands accept:
| Option | Description |
|---|---|
--cwd <path> |
Resolve repository discovery from another working directory. |
--json |
Emit structured JSON instead of human-readable text where supported. |
Stdout is reserved for requested output. Diagnostics, validation failures, and best-effort generated-view refresh warnings are written to stderr.
Exit codes:
| Code | Meaning |
|---|---|
0 |
Command succeeded. |
1 |
Repository or domain operation failed, such as invalid task state or delete blockers. |
2 |
CLI usage, argument validation, path normalization, or parse validation failed. |
taskset init [--config] [--cwd <path>]Initializes a Taskset repository. The command resolves a root from an existing .taskset/, Git or workspace markers, or the working directory, then creates .taskset/ task and document directories plus .taskset/.gitignore when they do not already exist. Pass --config to also write optional taskset.config.ts.
Human output:
Initialized Taskset in <root-directory>
taskset config [--json] [--cwd <path>]Discovers the nearest .taskset/ directory by walking upward from the working directory. Optional taskset.config.ts at that root overlays defaults when present.
Human output is the config file path when a config exists, or defaults (<root-directory>) when it does not. JSON output contains:
{
"rootDirectory": "...",
"configPath": "...",
"hasConfig": false,
"dataDirectory": "...",
"config": {}
}taskset doctor [--json] [--cwd <path>]Validates the repository without modifying files. It scans canonical task and document metadata, paths, graph relationships, required template headings for operational kinds, taxonomy allowlists, and optional closeout gaps.
Human success output:
Taskset repository is valid (<count> tasks, <count> documents)
Considerations (<count>)
<consideration-code> <path> <message> <recommendation>
Human failure output is tab-separated:
<code> <path-or-> <message> <remediation>
JSON output is the full doctor result, including valid, taskCount,
documentCount, diagnostics, considerationCount, and considerations.
Diagnostics describe repository integrity; errors fail the command and warnings
do not. Considerations are valid but unresolved work and review queues, so they
never change the exit code. Doctor reports open tasks, decisions awaiting
approval, research awaiting acceptance, active concerns, and other ready
documents awaiting review.
taskset generate [--json] [--cwd <path>]Rebuilds disposable generated views under each entity folder's .generated/
directory (for example .taskset/tasks/.generated/ and
.taskset/stories/.generated/). Removes any legacy .taskset/generated/ tree.
Human output:
Generated <count> views in <directory>
JSON output is the generated-views result with the target directory and written files.
Snapshots are non-authoritative safety checkpoints under .taskset/snapshots/.
Git remains the normal history and collaboration mechanism.
taskset snapshot create [--json] [--cwd <path>]Creates an immutable archive of canonical task files.
Human output is the snapshot ID. JSON output is the snapshot manifest.
taskset snapshot list [--json] [--cwd <path>]Lists available snapshots.
Human output is tab-separated:
<snapshot-id> <created-at> <file-count>
JSON output is an array of snapshot manifests.
taskset snapshot restore <snapshot-id> [--apply] [--json] [--cwd <path>]Previews or restores canonical task files from a snapshot. The default is a dry
run. Use --apply to mutate task files.
Human output:
Would restore <count> task files from <snapshot-id>
Restored <count> task files from <snapshot-id>
JSON output is the restore result, including applied and changes.
task create and task update accept the same metadata options unless noted.
Array options are repeatable.
| Option | Field | Notes |
|---|---|---|
--title <title> |
title |
Required for create, optional for update. |
--status <status> |
status |
One of todo, doing, blocked, done, canceled. |
--priority <priority> |
priority |
One of low, medium, high, urgent. |
--order <number> |
order |
Nonnegative finite number. Lower values sort first. |
--label <label> |
labels |
Repeatable. |
--depends-on <reference> |
dependsOn |
Repeatable; prefer a canonical repository-relative filename. |
--file <path> |
files |
Repeatable; normalized to a repository-relative POSIX path. |
--owner <owner> |
owner |
Trimmed string. |
--assignee <assignee> |
assignees |
Repeatable. |
--reviewer <reviewer> |
reviewers |
Repeatable. |
--team <team> |
team |
Trimmed string. |
--estimate <minutes> |
estimate |
Nonnegative integer. |
--effort <value> |
effort |
Nonnegative finite number. |
--risk <risk> |
risk |
One of low, medium, high. |
--due-date <date> |
dueDate |
YYYY-MM-DD or YYYY-MM-DD HH:mm UTC. |
--related <reference> |
related |
Repeatable; tasks and documents are accepted. |
--duplicate <reference> |
duplicates |
Repeatable. |
--parent <reference> |
parent |
Single entity reference. |
--directory <path> |
directories |
Repeatable; normalized to a repository-relative POSIX path. |
--project <project> |
projects |
Repeatable. |
--body <markdown> |
body | Replaces the body; normalizes literal whitespace escapes in prose while preserving code. |
--json |
output | Emit a task record as JSON. |
--cwd <path> |
discovery | Resolve repository discovery from another directory. |
taskset task create --title <title> [metadata options] [--json] [--cwd <path>]Creates a versionless task file using repository defaults for omitted configured fields.
Human output is the task ID. JSON output is a task record containing
relativePath and metadata fields.
taskset task list [query options] [--json] [--cwd <path>]Lists tasks using metadata, relationship, planning, timestamp, text, path, and impact filters.
Filter options:
| Option | Description |
|---|---|
--status <status> |
Repeatable; OR within statuses. |
--priority <priority> |
Repeatable; OR within priorities. |
--label <label> |
Repeatable; every requested label must be present. |
--owner <owner> |
Repeatable; OR within owners. |
--assignee <assignee> |
Repeatable; OR within assignees. |
--reviewer <reviewer> |
Repeatable; OR within reviewers. |
--team <team> |
Repeatable; OR within teams. |
--risk <risk> |
Repeatable; OR within risks. |
--project <project> |
Repeatable; OR within projects. |
--depends-on <task-id> |
Match a direct dependency. |
--related <task-id> |
Match a related task. |
--duplicate <task-id> |
Match a duplicate task relationship. |
--parent <task-id> |
Match a direct parent. |
--file <path> |
Repeatable; unified containment query over files and directories. |
--directory <path> |
Repeatable; containment query over directories only. |
--estimate-min <minutes> |
Inclusive minimum estimate. |
--estimate-max <minutes> |
Inclusive maximum estimate. |
--effort-min <value> |
Inclusive minimum effort. |
--effort-max <value> |
Inclusive maximum effort. |
--due-before <date> |
Inclusive due-date upper bound. |
--due-after <date> |
Inclusive due-date lower bound. |
--created-before <date> |
Inclusive created-at upper bound. |
--created-after <date> |
Inclusive created-at lower bound. |
--updated-before <date> |
Inclusive updated-at upper bound. |
--updated-after <date> |
Inclusive updated-at lower bound. |
--search <text> |
Search task title and Markdown body; every whitespace-separated term must match. |
--sort <key> |
Sort key. |
| `--direction <asc | desc>` |
--impact |
Add tasks that transitively depend on direct matches. |
--include-derived |
Include derived relationship projections in JSON output. |
Sort keys are id, title, status, priority, order, owner, team,
estimate, effort, risk, dueDate, createdAt, and updatedAt. With
--sort order, tasks without order sort after ordered tasks; duplicate
values fall back to task ID ordering.
Different filter categories compose with AND. Repeated enum, person, project, file, and directory values use OR within their category. Repeated labels are stricter and require all requested labels.
Search is Unicode-normalized and case-insensitive. Its terms may occur in any
order or location across the combined title and Markdown body, so
--search "cache invalidation" does not require that exact phrase.
Without --impact, human output is:
<task-id> <status> <title>
With --impact, human output prefixes direct and impacted rows:
direct <task-id> <status> <title>
impact <task-id> <status> <title>
JSON output without --impact is an array of task records. JSON output with
--impact is:
{
"direct": [],
"impacted": []
}Use --include-derived to include blockedBy, blocks, children, and
subtasks projections in each JSON record.
taskset task show <task-id> [--include-derived] [--json] [--cwd <path>]Shows one task by ID.
Human output is the serialized task Markdown. JSON output contains:
{
"relativePath": ".taskset/tasks/0000001-short-title-a1b2c3.md",
"metadata": {},
"body": "...",
"derived": {}
}The derived property is present only with --include-derived.
taskset task update <task-id> [metadata options] [clear options] [--json] [--cwd <path>]Updates one task. At least one non-control option is required. A field cannot be set and cleared in the same command.
Clear options:
| Option | Effect |
|---|---|
--clear-priority |
Remove priority. |
--clear-order |
Remove order. |
--clear-labels |
Replace labels with an empty list. |
--clear-dependencies |
Replace dependsOn with an empty list. |
--clear-files |
Replace files with an empty list. |
--clear-owner |
Remove owner. |
--clear-assignees |
Replace assignees with an empty list. |
--clear-reviewers |
Replace reviewers with an empty list. |
--clear-team |
Remove team. |
--clear-estimate |
Remove estimate. |
--clear-effort |
Remove effort. |
--clear-risk |
Remove risk. |
--clear-due-date |
Remove dueDate. |
--clear-related |
Replace related with an empty list. |
--clear-duplicates |
Replace duplicates with an empty list. |
--clear-parent |
Remove parent. |
--clear-directories |
Replace directories with an empty list. |
--clear-projects |
Replace projects with an empty list. |
Human output is the task ID. JSON output is the updated task record.
taskset task status <task-id> <status> [--json] [--cwd <path>]Updates only task status and enforces lifecycle transition rules. done and
canceled are terminal states.
Human output is the task ID. JSON output is the updated task record.
taskset task delete <task-id> [--remove-dependencies] [--json] [--cwd <path>]Deletes one task. By default, deletion is blocked while another task has an
inbound canonical dependency on the target. Use --remove-dependencies to
remove those inbound references and delete the target in one mutation.
Human output is the deleted task ID. JSON output contains deleted: true
alongside the deleted task record.
taskset task program <parent-id> [--json] [--cwd <path>]Summarizes a parent task as a program rollup: child counts by status, open child
IDs, blocked dependency edges, related open concerns, related research not yet
accepted, parent checklist completion, and closeoutReady.
Human output is one tab-separated summary line. JSON output is the full rollup object.
taskset task migrate-ids [--json] [--cwd <path>]Atomically converts legacy TS- and sequential task IDs to immutable short hex
IDs, normalizes filenames to {sequence}-{slug}-{id}.md, repairs duplicate
sequence prefixes by createdAt, and rewrites canonical relationships plus
references in repository text files. Dependencies, Git internals, build output,
caches, generated views, indexes, and snapshots are excluded. Human output is a
tab-separated old-to-new mapping; JSON emits the same mapping as objects.
taskset sync [--dry-run] [--fix] [--concurrency <count>] [--json] [--cwd <path>]Runs a complete non-mutating preflight before any repository change, then plans
legacy identity migrations, filename normalization, relationship rewrites, and
generated views in a temporary staging area. --dry-run prints the plan without
publishing it. --fix permits only deterministic repairs: quoting numeric
references, inferring a missing type from its canonical directory, inserting
empty required sections, resolving known aliases, and linking proven entity
mentions in managed prose. Conflicting types and ambiguous or unknown targets
remain errors. Canonical files publish in one optimistic transaction; generated
views rebuild afterward. JSON diagnostics stay on stdout and progress stays on
stderr.
Normal command input accepts a repository-relative path, unique basename,
canonical filename stem, or immutable ID for compatibility. Human output and
persisted relationships prefer complete repository-relative filenames. JSON
retains id and adds resolved relationship objects with path, filename,
title, kind, and status.
taskset agent context <task-reference> [--max-related <count>] [--max-children <count>] [--max-body-chars <count>] [--include-document-bodies] [--json] [--cwd <path>]Resolves the bounded, read-only Taskset context needed before executing or reviewing a task. It includes ownership permission, blockers, parent and child state, checklist progress, related durable memory, repository scopes, program readiness, and truncation warnings without mutating repository state.
Defaults limit child tasks and related documents to 20 entries and task bodies
to 4,000 characters. Related document bodies are omitted unless
--include-document-bodies is supplied. Every bounded collection reports its
total and truncation state; warnings explains hidden context.
Human output is one tab-separated summary:
<task-id> <status> <allowed|confirmation_required|blocked> <title>
JSON output is the stable formatVersion: "1" context object. Stdout contains
only the requested result; diagnostics remain on stderr. The command is local
and offline and delegates to the same core operation used by agent adapters.
document may be shortened to doc. Supported types are story, flow,
decision, research, runbook, lesson, concern, and audit. Aliases:
adr / dr → decision; antipattern → lesson.
taskset document create <type> --title <title> [metadata options]
taskset document import <markdown-path> [--type <type>] [--title <title>] [--move]
taskset document batch <manifest.json> [--concurrency <count>] [--json]
taskset document list [type] [query options]
taskset document show <document-id> [--type <type>] [--include-derived] [--json]
taskset document update <document-id> [metadata options] [--type <type>]
taskset document status <document-id> <status> [--type <type>] [--json]
taskset document delete <document-id> [--type <type>] [--remove-dependencies] [--json]Create uses the type-specific template unless --body is supplied and accepts
the same metadata options as task create, plus lesson/concern options:
--severity, repeatable --related-skill, repeatable --pack, --class, and
--cadence. Lesson/concern/audit templates are validated for required headings.
Import preserves the Markdown body and infers type from a recognized parent
directory when possible (lessons/, concerns/, audits/ included). It copies
by default; --move deletes the source only after the canonical document is
written successfully.
List, show, update, status, and delete mirror the task commands, including
search, filters, sort, impact, derived relationships, clear flags, and
guarded deletion. Document list also accepts --class and --severity. Document
statuses are draft, ready, active, accepted, superseded, and
archived.
Batch manifests contain an array of create, import, update, and export
operations. Work is paced with bounded concurrency, results preserve manifest
order, progress is sent to stderr, and --json reserves stdout for the result
array. See Document Types for a complete
manifest example.
Task and document creation, update, status changes, deletion, and snapshot restore mutate canonical Markdown first and then refresh disposable generated views. If that refresh fails after the canonical mutation succeeds, the command still succeeds and writes a stderr warning:
warning: <message>
Run taskset generate later to rebuild generated views explicitly.
tasks-for-file was removed. Use:
taskset task list --file <path> --impactTask files are versionless. Frontmatter that still contains a legacy version
field is invalid and must be converted by removing that field while preserving
the rest of the task metadata and Markdown body. Snapshot restore previews by
default; pass --apply only when the displayed plan is the mutation you intend
to commit.