CLI

dex status

Show a dashboard overview of your tasks. This is the default command — running dex with no arguments runs dex status.

• --json — Output as JSON for scripting

The dashboard shows:

• Stats — Total, pending, completed, blocked, and ready counts
• Ready to Work — Pending tasks with no blockers (up to 5)
• Blocked — Tasks waiting on dependencies
• Recently Completed — Latest completed tasks (up to 5)

dex                    # Show dashboard (default)
dex status             # Same as above
dex status --json      # Output as JSON

dex create

Create a new task with name and optional description.

• <name> — One-line summary (required, positional)
• -d, --description — Full implementation details (optional)
• -p, --priority <n> — Lower = higher priority (default: 1)
• -b, --blocked-by <ids> — Comma-separated task IDs that block this task
• --parent <id> — Parent task ID (creates subtask)

dex create "Add JWT authentication" \
  --description "Implement JWT middleware for route protection..."

dex create "Fix login bug"

dex create "Deploy to production" --blocked-by abc123

dex create "Add token refresh" --parent abc123

dex list

List tasks in tree view (default shows pending only).

• --all — Include completed tasks
• --completed — Only completed tasks
• --ready — Only unblocked tasks
• --blocked — Only blocked tasks
• -i, --in-progress — Only in-progress tasks
• --query <text> — Search in name/description
• --issue <number> — Find task by GitHub issue number
• --flat — Plain list instead of tree

Indicators:

• [>] — Task is in progress (blue)
• [B: xyz] — Task is blocked by task xyz
• [GH-42] — Task is linked to GitHub issue #42

dex list
dex list --all
dex list --ready
dex list --query "login"
dex list --issue 42

dex show

View full task details including context, result, blocking relationships, GitHub issue links, and subtasks. Supports multiple task IDs.

• -e, --expand — Show descriptions for ancestor tasks in the tree view
• -f, --full — Show full description and result (no truncation)
• --json — Output as JSON for scripting

If the task is linked to a GitHub issue (directly or via parent), the issue number, repo, and URL are displayed. Subtasks show "(via parent)" to indicate the link is inherited.

dex show abc123                # Show task details
dex show abc123 def456         # Show multiple tasks
dex show abc123 --expand       # Show ancestor descriptions

dex start

Mark a task as in progress. Use this to indicate you're actively working on a task.

• -f, --force — Re-claim a task that's already in progress

dex start abc123           # Mark task as in progress
dex start abc123 --force   # Re-claim a task already in progress

dex complete

Mark a task as completed with a result summary.

• --result — What was accomplished (required)
• --commit <sha> — Link to git commit (closes linked issue when merged)
• --no-commit — Complete without a commit (linked issue stays open)

Note: For tasks linked to GitHub issues or Shortcut stories, you must specify either --commit or --no-commit. This ensures issues are only closed when code is actually merged.

dex complete abc123 --result "Implemented JWT middleware with token refresh.
All 42 tests passing." --commit a1b2c3d

dex complete abc123 --result "Planning complete, no code changes" --no-commit

dex edit

Edit an existing task.

• -n, --name — Updated name
• -d, --description — Updated description
• --add-blocker <id> — Add blocking dependency
• --remove-blocker <id> — Remove blocking dependency

dex edit abc123 -n "Updated name"
dex edit abc123 --add-blocker xyz789
dex edit abc123 --remove-blocker xyz789

dex delete

Delete a task. Also deletes all subtasks.

dex delete abc123

dex archive

Archive a completed task and its descendants to reduce storage size. Archived tasks are compacted and moved to archive.jsonl.

Requirements:

• Task and all descendants must be completed
• Task must not have any incomplete ancestors

dex archive abc123

dex plan

Create a task from a markdown planning document. Automatically creates subtasks when the document contains distinct implementation steps.

• --priority <n> — Set priority
• --parent <id> — Create as subtask of existing task

dex plan ~/.claude/plans/auth-system.md
dex plan docs/SPEC.md --priority 2
dex plan feature.md --parent abc123

dex sync

Sync tasks to GitHub Issues and/or Shortcut Stories. Syncs all root tasks by default, or a specific task if ID is provided.

• --github — Sync only to GitHub Issues
• --shortcut — Sync only to Shortcut Stories
• --dry-run — Preview what would be synced without making changes

dex sync                    # Sync to all configured services
dex sync abc123             # Sync specific task
dex sync --github           # Sync only to GitHub
dex sync --shortcut         # Sync only to Shortcut
dex sync --dry-run          # Preview sync

dex import

Import a GitHub Issue or Shortcut Story as a dex task.

• --all — Import all items with the dex label
• --github — Filter --all to only GitHub
• --shortcut — Filter --all to only Shortcut
• --update — Update existing task if already imported
• --dry-run — Preview what would be imported

Reference formats:

• GitHub: #123, owner/repo#123, or full URL
• Shortcut: sc#123, SC#123, or full URL

dex import #42                    # Import GitHub issue #42
dex import sc#123                 # Import Shortcut story #123
dex import https://github.com/owner/repo/issues/42
dex import https://app.shortcut.com/myorg/story/123
dex import --all                  # Import all dex-labeled items
dex import --all --shortcut       # Import only from Shortcut
dex import #42 --update           # Refresh local task from GitHub

dex export

Export tasks to GitHub Issues without enabling sync. Unlike dex sync, this creates issues but does not save the issue metadata back to the task.

• <task-id>... — One or more task IDs to export (required)
• --dry-run — Preview without creating issues

Tasks that are already synced to GitHub are skipped with a warning.

dex export abc123                 # Export single task
dex export abc123 def456          # Export multiple tasks
dex export abc123 --dry-run       # Preview export

dex doctor

Check dex configuration and storage for issues, with optional auto-repair.

• --fix — Automatically fix detected issues

Checks performed:

• Config — Valid TOML syntax, deprecated settings, missing environment variables
• Storage — Task file validity, relationship consistency, orphaned references, depth limits

dex doctor             # Check for issues (read-only)
dex doctor --fix       # Check and fix issues

dex init

Initialize dex configuration. Creates a config file and optionally sets up shell completions.

• -y, --yes — Accept all defaults (skip prompts)
• --config-dir <path> — Override config directory

dex init              # Interactive setup
dex init -y           # Accept all defaults

dex dir

Print the dex directory path. By default, prints the task storage directory for the current repository.

• -g, --global — Print the global config directory instead

dex dir                # Print task storage path (e.g., /path/to/repo/.dex)
dex dir --global       # Print global config path (~/.config/dex)
cd $(dex dir)          # Navigate to task directory
ls $(dex dir)          # List task directory contents

dex config

Get or set configuration values (similar to git config).

• -g, --global — Use global config (~/.config/dex/dex.toml)
• -l, --local — Use project config (.dex/config.toml)
• --unset <key> — Remove a config key
• --list — List all set config values

Config keys:

• storage.engine — file (only supported engine)
• storage.file.path — Custom storage directory
• storage.file.mode — in-repo | centralized
• sync.github.enabled — Enable GitHub sync (boolean)
• sync.github.token_env — Environment variable for GitHub token
• sync.github.label_prefix — Label prefix for dex tasks
• sync.github.auto.on_change — Sync on mutations (boolean)
• sync.github.auto.max_age — Max age before stale (e.g., 30m, 1h)
• sync.shortcut.enabled — Enable Shortcut sync (boolean)
• sync.shortcut.token_env — Environment variable for Shortcut token
• sync.shortcut.workspace — Shortcut workspace slug (auto-detected if not set)
• sync.shortcut.team — Team ID or mention name (required for sync)
• sync.shortcut.workflow — Workflow ID (uses team default if not set)
• sync.shortcut.label — Label name for dex stories (default: "dex")

dex config sync.github.enabled           # Get value
dex config sync.github.enabled=true      # Set value
dex config --local sync.github.enabled=true
dex config --unset sync.github.label_prefix
dex config --list                        # Show all values

dex mcp

Run dex as an MCP server for integration with other tools.

dex mcp

dex completion

Generate shell completion script.

eval "$(dex completion bash)"
eval "$(dex completion zsh)"
dex completion fish | source

dex help

Show help for dex or a specific command.

dex help
dex help create
dex help complete

dex version

Display the installed version of dex.

dex version            # Show version
dex --version          # Same as above
dex -V                 # Short flag