Config

Dex can be configured via a dex.toml file in your project root or home directory.

Storage

Dex supports two storage modes:

In-Repo

Tasks stored in .dex/tasks.jsonl in your git repository (one task per line). No configuration needed. Old formats are auto-migrated.

When to commit .dex/:

• Shared projects where task history matters
• Long-running work that spans team members

When to gitignore .dex/:

• Personal tasks only
• High task churn

Centralized

Store tasks in a project-specific folder under ~/.dex/projects/:

[storage]
engine = "file"

[storage.file]
mode = "centralized"

Path Overrides

Override the storage path via environment variable or CLI flag:

# Environment variable
export DEX_STORAGE_PATH=/custom/path/.dex

# CLI flag
dex list --storage-path /custom/path/.dex

GitHub Sync

Sync tasks to GitHub Issues. Owner/repo are auto-detected from your git remote.

[sync.github]
enabled = true

Authentication: Uses gh CLI auth by default. Alternatively, set GITHUB_TOKEN environment variable.

Behavior:

• Top-level tasks → GitHub Issues
• Subtasks → Embedded in parent issue body as checklist
• Completed tasks → Issue closed (only after pushed to remote)
• Sync is one-way (local → GitHub)

Use dex sync to push tasks, or dex import <issue-url> to pull a GitHub Issue into dex.

Auto-Sync

By default, tasks sync to GitHub automatically whenever you create, update, or complete a task. You can customize this behavior:

[sync.github]
enabled = true

[sync.github.auto]
# Sync immediately on task mutations (default: true)
on_change = true

# If on_change=false, sync only when last sync exceeds max_age
# Format: "30m", "1h", "1d"
max_age = "1h"

on_change

Sync immediately after task create/update/complete. Default: true

max_age

If on_change=false, sync on mutation only when last sync exceeds this duration. Default: none

Common configurations:

• Always sync (default): on_change = true
• Periodic sync: on_change = false + max_age = "1h" — syncs only if stale
• Manual only: on_change = false — only sync via dex sync

Shortcut Sync

Sync tasks to Shortcut Stories. Workspace is auto-detected from your API token.

[sync.shortcut]
enabled = true
team = "Engineering"

Authentication: Set SHORTCUT_API_TOKEN environment variable.

Behavior:

• Tasks → Shortcut Stories
• Subtasks → Shortcut Sub-tasks (separate stories linked to parent)
• Blocked-by relationships → Story links
• Completed tasks → Story moved to "done" workflow state
• Sync is one-way (local → Shortcut)

Configuration Options

team

Required. Team name for story assignment (determines workflow)

workspace

Workspace slug (auto-detected from token)

workflow

Workflow ID (defaults to team's default workflow)

label

Label to apply to all synced stories

Auto-Sync

Auto-sync settings work the same as GitHub sync. See GitHub auto-sync settings for configuration options.

[sync.shortcut]
enabled = true
team = "Engineering"

[sync.shortcut.auto]
on_change = true

Environment Variables

DEX_STORAGE_PATH

Override storage directory

GITHUB_TOKEN

GitHub API token (optional if gh CLI is authenticated)

SHORTCUT_API_TOKEN

Shortcut API token for sync