CLI reference

Generated from the Commander registrations in src/index.ts. Every command below exists in the shipped CLI; anything absent here is not a Troth command.

The binary is troth. There are 111 commands in total. Run troth <command> --help for the same information in the terminal.

Global options

These are accepted on the root command. Individual commands may also declare their own --json or --brief flags.

Option	Description
--verbose	Show full stack traces on error
--json	Output as JSON (machine-readable)
--brief	Compact one-line-per-item output
-h, --help	Show this help

troth init

Initialize .troth/ directory in current project

troth init

Option	Description
-y, --yes	Skip prompts and use defaults
-n, --name <name>	Project name (skips name prompt)
--no-hooks	Skip git hook installation

troth migrate-jig

Copy a legacy .jig/ directory into .troth/ (does not delete .jig/)

troth migrate-jig

troth spec

Manage feature specs

troth spec

troth spec new

Create a new spec from template

troth spec new <name>

Option	Description
--layer <layer>	Architectural layer: platform, services, or surface
--parent <parent>	Parent spec name for sub-specs
--top-level	Skip placement suggestion and create as top-level spec

troth spec list

List all specs with status

troth spec list

Option	Description
--json	Output as JSON
--brief	Compact one-line output

troth spec show

Display spec content and task summary

troth spec show <name>

troth spec delete

Delete a spec and all its tasks

troth spec delete <name>

troth spec archive

Archive a spec (hides from list, preserves data)

troth spec archive <name>

troth spec reparent

Change a spec’s parent in the hierarchy

troth spec reparent <name>

Option	Description
--parent <parent>	New parent spec name
--no-parent	Remove parent (make top-level)

troth spec update

Write the spec body, or patch specific fields with –layer/–parent

troth spec update <name>

Option	Description
--from-file <path>	Write the spec body from a markdown file
--body <text>	Write the spec body inline (‘-’ reads stdin)
--layer <layer>	Set architectural layer (platform, services, surface)
--parent <parent>	Set parent spec name

troth spec refresh

Recompute spec status from task completion

troth spec refresh [name]

troth tasks

List all tasks for a spec

troth tasks <spec>

Option	Description
--json	Output as JSON
--brief	Compact one-line output

troth task

Manage individual tasks

troth task

troth task show

Display full task YAML (name alone searches all specs)

troth task show <name> [task-name]

Option	Description
--json	Output as JSON
--brief	Compact one-line output

troth task start

Mark a task as in-progress

troth task start <name> [task-name]

troth task done

Mark a task as passed (runs verification gates first)

troth task done <name> [task-name]

Option	Description
--notes <text>	Completion notes (what changed, decisions, watch-outs)
--skip-verify	Skip running verification gates

troth task fail

Mark a task as failed

troth task fail <name> [task-name]

Option	Description
--notes <text>	Failure notes (what went wrong)

troth task cancel

Mark a task as canceled (no longer relevant)

troth task cancel <name> [task-name]

Option	Description
--notes <text>	Why this task was canceled

troth task blocked

Mark a task as blocked with a reason

troth task blocked <name> [task-name]

Option	Description
--bug [text]	Also file a bug finding for the blocker

troth task add-guardrail

Add a guardrail to a task (accumulates, never replaces)

troth task add-guardrail <name> <guardrail>

troth task delete

Delete a task

troth task delete <spec> <task>

troth task move

Move a task to a different spec

troth task move <spec> <task>

troth task create

Create a new task for a spec

troth task create <spec> <task>

Option	Description
--objective <text>	Task objective (required unless –from-yaml)
--from-yaml <file>	Load task fields from a YAML file
--acceptance-criteria <json>	JSON array of criteria: plain strings and/or structured SAP objects
--intent <text>	Task intent/context
--complexity <level>	Complexity: trivial, simple, moderate, complex, epic
--file-scope <files>	Comma-separated list of file paths
--dependencies <deps>	Comma-separated list of dependency task names
--max-iterations <n>	Max iterations for loop execution
--mode <mode>	Execution mode: afk, hitl

troth task update

Update task fields

troth task update <spec> <task>

Option	Description
--status <status>	Set task status (pending, in-progress, passed, failed, canceled, blocked)
--notes <text>	Completion or status notes
--objective <text>	Update objective
--intent <text>	Update intent
--complexity <level>	Update complexity
--file-scope <files>	Set file scope (comma-separated)
--dependencies <deps>	Set dependencies (comma-separated)
--add-guardrail <text>	Add a guardrail
--max-iterations <n>	Set max iterations
--mode <mode>	Set mode: afk, hitl

troth next

Show next ready tasks in priority order

troth next

Option	Description
-n, --count <count>	Number of tasks to show
-a, --all	Show all ready tasks
-p, --parallel <count>	Return N conflict-free tasks safe to run in parallel
--json	Output as JSON
--brief	Compact one-line output

troth brief

Capture a structured project brief (interactive or from file)

troth brief

Option	Description
--file <path>	Read brief from a markdown file
--json	Output as JSON instead of formatted display

troth briefing

60-second prose briefing: where you left off, last decision, drift, what’s next

troth briefing

Option	Description
--json	Output structured data instead of prose

troth eod

End-of-day summary and optional decision capture

troth eod

Option	Description
--hours <n>	Session window in hours (default 24)
--skip-prompt	Print the summary only; skip the decision prompt

troth changelog

Prose changelog organized by topic, suitable for Slack/email/blog

troth changelog

Option	Description
--since <date>	ISO date or relative time like ‘3 days ago’. Default 7 days.

troth history

Show chronological timeline of context log, criteria changes, and test runs

troth history <task>

Option	Description
--type <type>	Filter by type: context-log, criteria-change, test-run, status-change, all

troth criteria

Manage structured acceptance criteria

troth criteria

troth criteria add

Add a structured acceptance criterion to a task

troth criteria add <task>

troth criteria list

List all current criteria for a task

troth criteria list <task>

troth criteria remove

Remove a criterion (soft-delete)

troth criteria remove <task> <criterion-id>

troth decompose

Output structured decomposition prompt for a spec

troth decompose <spec>

Option	Description
-y, --yes	Skip confirmation prompts

troth run

Run a task by piping its prompt to claude CLI

troth run <spec> <task>

Option	Description
--force	Skip dependency check

troth commit

Git commit + auto-mark Troth tasks from [spec/task] refs in message

troth commit

Option	Description
--skip-verify	Pass –no-verify to git commit

troth verify

Run verification gates for a task, or ‘verify audit’ to audit passed tasks

troth verify <spec> [task]

troth export

Export all user data as a structured JSON file

troth export

troth test

Test a task: run verification gates, assess criteria, check guardrails

troth test [task]

Option	Description
--criterion <n>	Test a specific criterion by number (1-indexed)
--skip-ai	Skip AI evaluation, run mechanical gates only
--staging	Run staging criteria only (against staging deployment)
--production	Run production criteria only (against deployed services)
--all	Run local, staging, and production criteria
--wave	Batch all criteria from eligible tasks (use with –staging)

troth status

Show project status overview or spec detail

troth status [spec]

Option	Description
--json	Output as JSON
--brief	Compact one-line output

troth search

Search across specs, tasks, findings, decisions, and requests

troth search <query>

Option	Description
--specs-only	Search specs only
--tasks-only	Search tasks only
--findings-only	Search findings only
--decisions-only	Search decisions only
--requests-only	Search requests only

troth tree

Show hierarchical spec and task tree

troth tree [spec]

troth guide

Show the Troth workflow guide

troth guide

troth env

Manage deployment environments

troth env

troth env list

Show configured environments with status

troth env list

troth env check

Ping health endpoints for each configured environment

troth env check

troth deploy

Deploy to staging or production environment

troth deploy

Option	Description
--staging	Deploy to staging environment
--production	Deploy to production environment

troth scan

Scan codebase and show project analysis

troth scan

Option	Description
--summary	Show compact feature-oriented summary

troth reindex

Refresh the code-import graph for the structure views (no re-decomposition)

troth reindex

troth surfaces

Screens as a first-class view (docs/design/SURFACES-BRIEF.md)

troth surfaces

troth surfaces init

Scaffold .troth/surfaces.json, detect the bundler, and check for an existing headless browser

troth surfaces init

Option	Description
--force	Overwrite an existing .troth/surfaces.json

troth surfaces list

List surfaces with current verdict and stale marker

troth surfaces list

Runs by default when troth surfaces is called with no subcommand.

troth surfaces render

Render all surfaces, or one with –surface ; uploads markup + deduped assets

troth surfaces render

Option	Description
--surface <key>	Render only this surface

troth surfaces status

Show what is pending re-render and what is stale

troth surfaces status

troth bootstrap

Scan codebase and output bootstrap prompt (no API calls)

troth bootstrap

Option	Description
--file <path>	Write prompt to file instead of stdout
--auto	Call Claude directly to generate and apply specs automatically
--dry-run	With –auto: show proposed specs without writing
--summarize	Output compact summary (no file contents) for manual piping

troth bootstrap apply

Apply generated specs from JSON input

troth bootstrap apply

Option	Description
--file <path>	Read specs from file instead of stdin
--dry-run	Show proposed changes without writing
--spec <name>	Apply only this spec
--layer <layer>	Apply only specs in this layer
--uncategorized	Apply only uncategorized specs

troth projects

Manage registered projects

troth projects

troth projects add

Register a project directory (default: current directory)

troth projects add [path]

troth projects list

List all registered projects

troth projects list

troth projects remove

Unregister a project (does not delete files)

troth projects remove <name>

troth projects delete

Permanently delete a cloud project and all its data

troth projects delete <name>

Option	Description
-y, --yes	Skip confirmation prompt

troth projects switch

Switch this directory to a different cloud project

troth projects switch <name>

troth projects rename

Rename a cloud project (keeps ID, specs, tasks, decisions)

troth projects rename <currentName> <newName>

troth projects create

Create a new Troth project (alias for troth init)

troth projects create

troth serve

Start API server for web UI

troth serve

Option	Description
-p, --port <port>	API server port

troth serve mcp

Start MCP server (stdio transport)

troth serve mcp

troth mcp

MCP server utilities

troth mcp

troth mcp check

Run MCP auth and connectivity diagnostics

troth mcp check

troth bug

File a bug finding

troth bug <message>

troth idea

File an idea finding

troth idea <message>

troth findings

Manage findings (intake pile)

troth findings

troth findings list

List active findings

troth findings list

Runs by default when troth findings is called with no subcommand.

Option	Description
--bugs	Show only bugs
--ideas	Show only ideas
--type <type>	Filter by type: bug or idea
--status <status>	Filter by status: new, triaged, dismissed
--limit <n>	Max findings to show (default 50)
--all	Show the entire pile, not just the newest page

troth findings confirm

Confirm a finding (set status to triaged)

troth findings confirm <id>

troth findings promote

Promote a finding to a task or request

troth findings promote <id>

Option	Description
--target <target>	Promote target: task or request (required)
--spec <name>	Spec name (required for task)
--objective <text>	Task objective (required for task)

troth dismiss

Dismiss a finding

troth dismiss <id>

troth request

Manage requests (intent tracking)

troth request

troth request create

Create a new request

troth request create <title>

Option	Description
--description <text>	Request description
--origin <origin>	Origin: conversation, bug, idea, user-report, internal
--priority <priority>	Priority: critical, high, normal, low

troth request list

List requests

troth request list

Option	Description
--status <status>	Filter by status: open, in-progress, resolved, abandoned, deferred
--priority <priority>	Filter by priority: critical, high, normal, low

troth request show

Show request details and linked work

troth request show <id>

troth request link

Link a task, finding, or spec to a request

troth request link <request-id>

Option	Description
--task <spec/task>	Link a task (spec/task format)
--finding <id>	Link a finding
--spec <name>	Link a spec

troth request resolve

Resolve a request with outcome and learning

troth request resolve <id>

Option	Description
--outcome <outcome>	Outcome: resolved, partial, deferred, wont-fix, cant-reproduce
--learning <text>	What was learned (required)
--notes <text>	Additional notes

troth request search

Search requests by title or description

troth request search <query>

troth request defer

Defer a request

troth request defer <id>

Option	Description
--reason <text>	Reason for deferring

troth learnings

List learnings from resolved requests

troth learnings

Option	Description
--search <query>	Filter learnings by keyword

troth login

Login to Troth via GitHub or Google

troth login

Option	Description
--token <token>	Paste a token directly (for headless/SSH environments)
--provider <provider>	OAuth provider: github (default) or google

troth logout

Clear saved credentials

troth logout

troth whoami

Show current logged-in user

troth whoami

troth auth

Authentication utilities (used by Claude Code hooks)

troth auth

troth auth token

Print the current access token to stdout (machine-readable, no trailing newline)

troth auth token

Option	Description
--raw	Accepted for forward compatibility; output is always raw

troth report-bug

Submit a bug report to GitHub with diagnostic context

troth report-bug [description]

Option	Description
-i, --interactive	Open $EDITOR for a longer description
-y, --yes	Skip confirmation prompt

troth debt

Show understanding debt: count of unreviewed execution records

troth debt

Option	Description
--json	Output as JSON

troth session

Session utilities (used by Claude Code hooks)

troth session

troth session recap-delta

Emit a structured session delta JSON to stdout (consumed by the SessionEnd hook)

troth session recap-delta

troth constitution

Manage project constitution (foundations)

troth constitution

troth constitution set

Write the project constitution from a file, –content, or stdin (-)

troth constitution set [file]

Option	Description
--content <markdown>	Inline markdown content (alternative to file)
--project <name>	Target project name
--workspace	Workspace scope (Phase 2, not yet supported)
--overwrite	Replace existing constitution (default: refuse if set)

troth constitution show

Display the current constitution (stdout, suitable for piping)

troth constitution show

Option	Description
--project <name>	Target project name

troth bible

Manage project design bible (foundations)

troth bible

troth bible set

Write the project design bible from a file, –content, or stdin (-)

troth bible set [file]

Option	Description
--content <markdown>	Inline markdown content (alternative to file)
--project <name>	Target project name
--workspace	Workspace scope (Phase 2, not yet supported)
--overwrite	Replace existing design bible (default: refuse if set)

troth bible show

Display the current design bible (stdout, suitable for piping)

troth bible show

Option	Description
--project <name>	Target project name

troth tokens

Manage project design tokens (foundations)

troth tokens

troth tokens set

Write design tokens from a JSON file, –content, or stdin (-)

troth tokens set [file]

Option	Description
--content <json>	Inline JSON content (alternative to file)
--project <name>	Target project name
--workspace	Workspace scope (Phase 2, not yet supported)
--overwrite	Replace existing tokens (default: refuse if set)

troth tokens show

Display the current design tokens as pretty-printed JSON (stdout)

troth tokens show

Option	Description
--project <name>	Target project name

troth foundations

Manage project foundations (constitution, design bible, tokens)

troth foundations

troth foundations show

Display all project foundations: constitution, design bible, and tokens

troth foundations show

Runs by default when troth foundations is called with no subcommand.

Option	Description
--project <name>	Target project name

troth asset

Manage project design assets (foundations)

troth asset

troth asset add

Upload a design asset file (max 5 MB)

troth asset add <file>

Option	Description
--project <name>	Target project name
--overwrite	Replace existing asset with the same filename

troth asset list

List uploaded assets for a project

troth asset list

Option	Description
--project <name>	Target project name

troth asset download

Download an asset to disk

troth asset download <name>

Option	Description
--project <name>	Target project name
--output <path>	Output file path (default: ./)

troth asset remove

Remove an asset from a project

troth asset remove <name>

Option	Description
--project <name>	Target project name
-y, --yes	Skip confirmation prompt

troth help

Show this help

troth help