Skip to content

Latest commit

 

History

History
526 lines (396 loc) · 18.6 KB

cli-reference.md

File metadata and controls

526 lines (396 loc) · 18.6 KB
title Look up Taskset CLI commands
description Complete reference for the taskset command-line interface.
contentType Reference
navLabel CLI Reference

Look up Taskset CLI commands

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.

Common Behavior

taskset help
taskset --help
taskset -h

Running 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.

Repository Commands

init

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>

config

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": {}
}

doctor

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.

generate

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.

Snapshot Commands

Snapshots are non-authoritative safety checkpoints under .taskset/snapshots/. Git remains the normal history and collaboration mechanism.

snapshot create

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.

snapshot list

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.

snapshot restore

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 Metadata Options

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.

Task Commands

task create

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.

task list

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.

task show

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.

task update

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.

task status

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.

task delete

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.

task program

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.

task migrate-ids

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.

sync

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.

Agent Commands

agent context

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 Commands

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.

Generated-View Warnings

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.

Compatibility Notes

tasks-for-file was removed. Use:

taskset task list --file <path> --impact

Task 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.