CLI Reference

Complete reference for all jig commands.

Global flags

These flags can be used with any command.

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

---

Table of contents

• Getting Started: init, bootstrap
• Specs: spec new, spec list, spec show, spec update, spec refresh, spec reparent, spec delete, spec archive
• Tasks: tasks, task show, task start, task done, task fail, task cancel, task blocked, task add-guardrail, task create, task update, task delete, task move, next, decompose
• Execution & Navigation: run, commit, verify, runs, status, search, tree, history
• Bundles: bundle create, bundle list, bundle show, bundle update, bundle delete, context (alias)
• Snippets: snippet new, snippet list, snippet show, snippet delete
• Criteria: criteria add, criteria list, criteria remove
• Intake: bug, idea, findings, dismiss
• Requests: request create, request list, request show, request link, request resolve, request search, request defer, learnings
• Cloud: login, logout, whoami, projects
• Servers: serve
• Environments: env list, env check, deploy, promote
• Reference: guide

---

Getting Started

init

Initialize a .jig/ directory in the current project and register the MCP server with Claude Code.

jig init [options]

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

Example:

cd my-project
jig init

---

bootstrap

Scan an existing codebase and generate a prompt for creating specs. The two-step flow outputs a prompt, you run it through an LLM, then apply the result with bootstrap apply.

jig bootstrap [options]

Flag	Description
--file <path>	Write prompt to file instead of stdout

Examples:

# Output bootstrap prompt to stdout
jig bootstrap

# Write prompt to file
jig bootstrap --file bootstrap-prompt.md

bootstrap apply

Apply pre-generated specs from JSON input (produced by running the bootstrap prompt through an LLM).

jig bootstrap apply [options]

Flag	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

Examples:

# Apply from file
jig bootstrap apply --file specs.json

# Preview without writing
jig bootstrap apply --file specs.json --dry-run

---

Specs

Manage feature specifications.

spec new

Create a new spec from template. Automatically suggests a parent spec if related specs exist.

jig spec new <name> [options]

Flag	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

Examples:

jig spec new auth-layer --layer platform
jig spec new login-flow --parent auth-layer
jig spec new standalone-feature --top-level

spec list

List all specs with their status summary.

jig spec list

Example output:

[in-progress] auth-layer (3/5 tasks)
  [new]  login-flow (0/2 tasks)
[done]   database-client (2/2 tasks)

spec show

Display a spec’s full markdown content and task summary.

jig spec show <name>

Example:

jig spec show auth-layer

spec update

Patch spec fields without touching content. Use flags to specify which fields to update.

jig spec update <name> [options]

Flag	Description
--layer <layer>	Set architectural layer (platform, services, surface)
--stage <stage>	Set spec stage
--parent <parent>	Set parent spec name
--bundles <bundles>	Set associated bundle names (comma-separated)

Examples:

jig spec update auth-layer --layer platform
jig spec update auth-layer --bundles "api-patterns,auth-config"
jig spec update login-flow --parent auth-layer --stage active

spec refresh

Recompute spec status from task completion. Run without a name to refresh all specs.

jig spec refresh [name]

Examples:

# Refresh a single spec
jig spec refresh auth-layer

# Refresh all specs
jig spec refresh

spec reparent

Change a spec’s position in the hierarchy. Move it under a different parent or make it top-level.

jig spec reparent <name> [options]

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

Examples:

# Move under a different parent
jig spec reparent login-flow --parent user-management

# Make top-level
jig spec reparent login-flow --no-parent

spec delete

Delete a spec and all its tasks. This is permanent.

jig spec delete <name>

Example:

jig spec delete old-feature

spec archive

Archive a spec. Archived specs are hidden from lists but preserved in the database.

jig spec archive <name>

Example:

jig spec archive completed-feature

---

Tasks

tasks

List all tasks for a spec.

jig tasks <spec>

Example:

jig tasks auth-layer

Example output:

[passed]      setup-auth-client
[in-progress] implement-token-refresh
[new]         add-session-middleware

---

task show

Display a task’s full details including objective, file scope, verification gates, and status. Providing only a task name searches all specs. Supports handles (e.g., kex-42).

jig task show <name>
jig task show <spec> <task>

Examples:

jig task show setup-auth-client
jig task show auth-layer setup-auth-client

task start

Mark a task as in-progress.

jig task start <name>
jig task start <spec> <task>

Example:

jig task start setup-auth-client

task done

Mark a task as passed. Runs verification gates first (unless skipped). Always provide --notes with a summary of what changed.

jig task done <name> [options]
jig task done <spec> <task> [options]

Flag	Description
--notes <text>	Completion notes: what changed, decisions made, watch-outs
--skip-verify	Skip running verification gates

Example:

jig task done setup-auth-client \
  --notes "Changed: created src/auth/client.ts singleton. Decisions: used lazy init pattern. Watch: all Supabase access must go through this client."

task fail

Mark a task as failed. Always provide --notes with context on what went wrong.

jig task fail <name> [options]
jig task fail <spec> <task> [options]

Flag	Description
--notes <text>	Failure notes: what went wrong, what was tried, suggested next steps

Example:

jig task fail implement-token-refresh \
  --notes "Blocked by: Supabase refresh endpoint returns 403 in staging. Tried: manual token exchange, cookie fallback. Next: check Supabase project settings."

task cancel

Mark a task as canceled. Use when a task is no longer relevant.

jig task cancel <name> [options]
jig task cancel <spec> <task> [options]

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

Example:

jig task cancel old-migration-task \
  --notes "Superseded by new schema design in database-v2 spec."

task blocked

Mark a task as blocked with a mandatory reason. Optionally file a bug for the blocker.

jig task blocked <name> [options]
jig task blocked <spec> <task> [options]

Flag	Description
--reason <text>	Why the task is blocked (required)
--bug [text]	Also file a bug finding for the blocker

Example:

jig task blocked setup-auth-client \
  --reason "Waiting on Supabase project provisioning" \
  --bug "Supabase project creation is stuck in pending state"

task add-guardrail

Add a guardrail to a task. Guardrails accumulate and are never replaced.

jig task add-guardrail <name> <guardrail>

Example:

jig task add-guardrail setup-auth-client "Must not store tokens in localStorage"

task create

Create a new task for a spec. Requires either --objective or --from-yaml.

jig task create <spec> <task> [options]

Flag	Description
--objective <text>	Task objective (required unless --from-yaml)
--from-yaml <file>	Load task fields from a YAML file
--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
--execution-pattern <pattern>	Execution pattern: loop, plan_first, hybrid
--max-iterations <n>	Max iterations for loop execution
--mode <mode>	Execution mode: afk, hitl

Examples:

jig task create auth-layer setup-auth-client \
  --objective "Create the Supabase auth client singleton" \
  --complexity simple \
  --file-scope "src/auth/client.ts,src/auth/index.ts"

jig task create auth-layer full-auth-setup --from-yaml auth-task.yaml

task update

Update one or more fields on an existing task.

jig task update <spec> <task> [options]

Flag	Description
--status <status>	Set 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
--execution-pattern <pattern>	Set execution pattern
--max-iterations <n>	Set max iterations
--mode <mode>	Set mode: afk, hitl

Example:

jig task update auth-layer setup-auth-client \
  --complexity moderate \
  --file-scope "src/auth/client.ts,src/auth/index.ts,src/auth/types.ts"

task delete

Delete a task permanently.

jig task delete <spec> <task>

Example:

jig task delete auth-layer obsolete-task

task move

Move a task from one spec to another.

jig task move <spec> <task> --to <target-spec>

Flag	Description
--to <target-spec>	Target spec name (required)

Example:

jig task move auth-layer setup-oauth --to user-management

---

next

Show the next tasks that are ready to execute, ordered by priority. Supports parallel-safe selection for dispatching multiple agents.

jig next [options]

Flag	Description
-n, --count <n>	Number of tasks to show (default: 10)
-a, --all	Show all ready tasks
-p, --parallel <count>	Return N conflict-free tasks safe to run in parallel

Examples:

jig next
jig next --count 5
jig next --parallel 3

Example output:

Ready tasks (3):
  [new] setup-auth-client (auth-layer)
        Create the Supabase auth client singleton
  [new] create-spec-table (database-client)
        Add specs table migration

---

decompose

Decompose a spec into implementation tasks using AI. Analyzes the spec’s intent, acceptance criteria, and available context bundles, then proposes a task breakdown for review.

jig decompose <spec> [options]

Flag	Description
-y, --yes	Skip confirmation prompts

Example:

jig decompose auth-layer

---

Execution & Navigation

run

Execute a task by generating a full Claude Code prompt and piping it to claude.

jig run <spec> <task> [options]

Flag	Description
--force	Skip dependency check

Example:

jig run auth-layer setup-auth-client

---

commit

Git commit with automatic task marking. Any [spec/task] references in the commit message are parsed and those tasks are marked as passed.

jig commit -m <message> [options]

Flag	Description
-m, --message <message>	Commit message (required)
--skip-verify	Pass --no-verify to git commit

Example:

jig commit -m "feat: add auth client singleton [auth-layer/setup-auth-client]"

This runs git commit first, then parses [auth-layer/setup-auth-client] from the message and marks that task as passed with auto-generated completion notes.

---

verify

Run the verification commands for a task without executing the task itself.

jig verify <spec> <task>

Example:

jig verify auth-layer setup-auth-client

---

runs

List execution runs for a spec.

jig runs <spec>

Example:

jig runs auth-layer

---

status

Show a project status overview with all specs and their task completion. Pass a spec name to see individual task progress.

jig status [spec]

Examples:

# Project overview
jig status

# Spec detail
jig status auth-layer

Example output:

[in-progress] auth-layer  (3/5 tasks passed)
[new]         dashboard-ui  (0/4 tasks passed)
[done]        database-client  (2/2 tasks passed)

---

search

Search across specs, tasks, and findings.

jig search <query> [options]

Flag	Description
--specs-only	Search specs only
--tasks-only	Search tasks only
--findings-only	Search findings only

Examples:

jig search "authentication"
jig search "login" --tasks-only

---

tree

Show a hierarchical view of specs and their tasks. Optionally scope to a single spec.

jig tree [spec]

Examples:

# Full project tree
jig tree

# Single spec tree
jig tree auth-layer

---

history

Show a chronological timeline of events for a task: context log entries, criteria changes, test runs, and status changes.

jig history <task> [options]

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

Examples:

jig history setup-auth-client
jig history setup-auth-client --type test-run

---

Bundles

Manage reusable context bundles that provide shared context (files, constraints, patterns) to tasks.

bundle create

Create a new context bundle.

jig bundle create <name> [options]

Flag	Description
--shared	Make this bundle shared across projects
--description <text>	Bundle description

Example:

jig bundle create api-client-patterns --description "REST API patterns and conventions"

bundle list

List all context bundles.

jig bundle list [options]

Flag	Description
--shared	Include shared bundles from other projects
--project-only	Show only project bundles (exclude shared)
--shared-only	Show only shared bundles

Example:

jig bundle list --shared

bundle show

Display a bundle’s full content including files, constraints, and patterns.

jig bundle show <name>

Example:

jig bundle show api-client-patterns

bundle update

Update bundle fields.

jig bundle update <name> [options]

Flag	Description
--description <text>	New description
--shared	Make bundle shared across projects
--no-shared	Make bundle project-only
--files <json>	Set files (JSON array)
--constraints <json>	Set constraints (JSON array)
--patterns <json>	Set patterns (JSON array)

Example:

jig bundle update api-client-patterns \
  --constraints '["Always use fetch, never axios", "Include retry logic"]'

bundle delete

Delete a bundle.

jig bundle delete <name>

Example:

jig bundle delete old-patterns

context (alias)

The context command is an alias for bundle. All subcommands are identical:

jig context create <name>
jig context list
jig context show <name>
jig context update <name>
jig context delete <name>

---

Snippets

Manage reusable text snippets that can be attached to tasks or shared across projects.

snippet new

Create a new snippet.

jig snippet new <name> [options]

Flag	Description
--content <text>	Inline snippet content
--shared	Make this snippet shared across projects

Example:

jig snippet new error-handling --content "Always wrap async calls in try/catch with structured error logging"

snippet list

List snippets.

jig snippet list [options]

Flag	Description
--shared	Include shared snippets from other projects
--project-only	Show only project snippets (exclude shared)
--shared-only	Show only shared snippets

Example:

jig snippet list --shared

snippet show

Display snippet content.

jig snippet show <name>

Example:

jig snippet show error-handling

snippet delete

Delete a snippet.

jig snippet delete <name>

Example:

jig snippet delete old-snippet

---

Criteria

Manage structured acceptance criteria on tasks. Criteria are mechanically verifiable and can be tested with jig test.

criteria add

Add a structured acceptance criterion to a task.

jig criteria add <task> [options]

Flag	Description
--subject <subject>	What to check: file path, URL, command, etc. (required)
--property <property>	Property to evaluate: contains_string, file_exists, http_status, etc. (required)
--expected <expected>	Expected value or pattern (required)
--description <description>	Human-readable description (required)

Example:

jig criteria add setup-auth-client \
  --subject "src/auth/client.ts" \
  --property file_exists \
  --expected "true" \
  --description "Auth client module exists"

criteria list

List all current criteria for a task.

jig criteria list <task>

Example:

jig criteria list setup-auth-client

criteria remove

Remove a criterion by ID (soft-delete).

jig criteria remove <task> <criterion-id>

Example:

jig criteria remove setup-auth-client crit-abc123

---

Intake

bug

File a bug finding into the intake pile. AI triage runs in the background to match it to a spec.

jig bug "<message>"

Example:

jig bug "Login button does nothing when clicked on mobile Safari"

---

idea

File an idea finding into the intake pile.

jig idea "<message>"

Example:

jig idea "Let users pin specs to the top of the list for quick access"

---

findings

List active findings from the intake pile.

jig findings [options]

Flag	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

Examples:

jig findings
jig findings --bugs
jig findings --status triaged

---

dismiss

Dismiss a finding by ID. Dismissed findings are hidden but not deleted.

jig dismiss <id>

Example:

jig dismiss bug-3a9f

---

Requests

Manage requests for tracking user intent from conversation through resolution. Requests link to specs, tasks, and findings, and produce learnings when resolved.

request create

Create a new request.

jig request create <title> [options]

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

Example:

jig request create "Add dark mode support" \
  --description "Users are requesting dark mode for the dashboard" \
  --origin user-report \
  --priority normal

request list

List requests with optional filters.

jig request list [options]

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

Example:

jig request list --status open --priority high

request show

Show request details and all linked work (tasks, findings, specs).

jig request show <id>

Example:

jig request show req-abc123

request link

Link a task, finding, or spec to a request.

jig request link <request-id> [options]

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

Example:

jig request link req-abc123 --task "auth-layer/setup-auth-client"
jig request link req-abc123 --spec dashboard-ui

request resolve

Resolve a request with an outcome and learning.

jig request resolve <id> [options]

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

Example:

jig request resolve req-abc123 \
  --outcome resolved \
  --learning "Dark mode requires CSS custom properties migration before it can be implemented cleanly"

request search

Search requests by title or description.

jig request search <query>

Example:

jig request search "dark mode"

request defer

Defer a request for later.

jig request defer <id> [options]

Flag	Description
--reason <text>	Reason for deferring

Example:

jig request defer req-abc123 --reason "Waiting on design system v2 for proper theming support"

---

learnings

List learnings extracted from resolved requests.

jig learnings [options]

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

Examples:

jig learnings
jig learnings --search "authentication"

---

Cloud

login

Authenticate with Jig via GitHub or Google OAuth.

jig login [options]

Flag	Description
--token <token>	Paste an API token directly (for headless or SSH environments)
--provider <provider>	OAuth provider: github (default) or google

Examples:

jig login
# Opens browser for GitHub OAuth

jig login --token jig_tok_abc123
# Headless environments

jig login --provider google

---

logout

Clear saved credentials from the local machine.

jig logout

---

whoami

Show the currently authenticated user.

jig whoami

Example output:

Logged in as: alice@example.com

---

projects

Manage projects registered with Jig.

projects add

Register a project directory. Defaults to the current directory.

jig projects add [path]

Examples:

jig projects add
jig projects add /Users/alice/projects/my-app

projects list

List all registered projects.

jig projects list

Example output:

my-app     /Users/alice/projects/my-app     4 specs
api-server /Users/alice/projects/api        2 specs

projects remove

Unregister a project. Does not delete any files.

jig projects remove <name>

Example:

jig projects remove my-app

projects delete

Permanently delete a cloud project and all its data.

jig projects delete <name> [options]

Flag	Description
-y, --yes	Skip confirmation prompt

Example:

jig projects delete old-project --yes

projects switch

Switch this directory to a different cloud project.

jig projects switch <name>

Example:

jig projects switch my-other-project

---

Servers

serve

Start the API server for the web UI.

jig serve [options]

Flag	Description
-p, --port <port>	Port to listen on (default: 3847)

serve mcp

Start the MCP server on stdio transport for use with Claude Code or other MCP clients.

jig serve mcp

---

Environments

env list

Show configured environments with their current status.

jig env list

env check

Ping health endpoints for each configured environment.

jig env check

---

deploy

Deploy to staging or production environment.

jig deploy [options]

Flag	Description
--staging	Deploy to staging environment
--production	Deploy to production environment

Examples:

jig deploy --staging
jig deploy --production

---

promote

Promote from staging to production. Runs the full pipeline: verify staging, deploy to production, run production tests.

jig promote

---

Reference

guide

Show the Jig workflow guide with the full SAP format reference and examples.

jig guide