Command Line Interface¶

Complete reference for all TaskRepo CLI commands.

Command Groups¶

TaskRepo organizes commands into logical groups:

Setup & Configuration: Initialize and configure TaskRepo
Viewing Tasks: List, search, and inspect tasks
Managing Tasks: Create, edit, and update tasks
Repository Operations: Manage task repositories and sync

Setup & Configuration¶

`tsk init`¶

Initialize TaskRepo configuration.

tsk init

Interactive prompts: - Parent directory for task repositories (default: ~/tasks) - Default priority (H/M/L) - Default status (pending/in-progress/completed/cancelled)

Creates: - Configuration file at ~/.TaskRepo/config - Parent directory for repositories

`tsk config`¶

Interactive configuration management.

tsk config

Opens an interactive TUI to modify configuration settings: - Parent directory - Default priority - Default status - Default assignee - Default GitHub organization - Sort order - Due date clustering

Use arrow keys to navigate, Enter to edit, and 's' to save.

`tsk config-show`¶

Display current configuration.

tsk config-show

Output: Pretty-printed YAML configuration

`tsk llm-info`¶

Display TaskRepo CLI reference for LLM assistants.

tsk llm-info

Outputs comprehensive CLI documentation optimized for language models, including: - Command syntax and options - Configuration file format - Task file format - Common workflows

`tsk upgrade`¶

Upgrade TaskRepo to the latest version.

tsk upgrade

Homebrew installations: Runs brew upgrade taskrepo pipx installations: Runs pipx upgrade taskrepo

Automatically detects installation method and uses the appropriate upgrade command.

Viewing Tasks¶

`tsk list`¶

List tasks with optional filters.

tsk list [OPTIONS]

Options: - --repo, -r TEXT: Filter by repository name - --status, -s [pending|in-progress|completed|cancelled]: Filter by status - --priority [H|M|L]: Filter by priority - --project, -p TEXT: Filter by project - --assignee, -a TEXT: Filter by assignee (e.g., @alice) - --tag, -t TEXT: Filter by tag - --all: Show all tasks including completed

Examples:

# List all pending tasks
tsk list

# List tasks in 'work' repository
tsk list --repo work

# List high-priority tasks
tsk list --priority H

# List tasks assigned to @alice
tsk list --assignee @alice

# List tasks tagged 'bug'
tsk list --tag bug

# List all tasks including completed
tsk list --all

# Combine multiple filters
tsk list --repo work --priority H --status pending

Output: Rich formatted table with columns: - ID: Display ID - Title: Task title - Proj: Project name (color-coded) - Status: Task status (color-coded) - P: Priority (H/M/L) - Assign: Assigned users - Tags: Task tags - Due: Due date - Count: Countdown to due date

`tsk search`¶

Search for tasks containing a text query.

tsk search QUERY [OPTIONS]

Arguments: - QUERY: Text to search for (case-insensitive)

Options: All filter options from list command: - --repo, -r TEXT - --status, -s [pending|in-progress|completed|cancelled] - --priority [H|M|L] - --project, -p TEXT - --assignee, -a TEXT - --tag, -t TEXT - --all: Include completed tasks

Search scope: Title, description, project name, tags

Examples:

# Find tasks mentioning "authentication"
tsk search "authentication"

# Search in specific repository
tsk search "bug" --repo backend

# Find high-priority tasks with keyword
tsk search "urgent" --priority H

# Include completed tasks
tsk search "feature" --all

`tsk info`¶

Display detailed information about a specific task.

tsk info TASK_ID [OPTIONS]

Arguments: - TASK_ID: Display ID or UUID of the task

Options: - --repo, -r TEXT: Limit search to specific repository

Output: Complete task details including: - UUID and display ID - Title and description - Repository and project - Status and priority - Assignees and tags - Links (URLs) - Due date - Created and modified timestamps - Dependencies

`tsk tui`¶

Launch interactive TUI for task management.

tsk tui [OPTIONS]

Options: - --repo, -r TEXT: Start TUI with specific repository selected

Opens a full-screen terminal interface for browsing and managing tasks. See Interactive TUI for detailed keyboard shortcuts and usage.

Managing Tasks¶

`tsk add`¶

Add a new task.

tsk add [OPTIONS]

Interactive mode (no options):

tsk add

Prompts for: - Repository (with fuzzy autocomplete) - Title (required) - Project (autocomplete from existing) - Status (default from config) - Priority (default from config) - Assignees (autocomplete with @ prefix) - Tags (autocomplete from existing) - Links (URLs) - Due date (flexible date parsing) - Description (optional, opens editor)

Non-interactive mode (all required fields provided):

tsk add --repo work \
  --title "Fix authentication bug" \
  --project backend \
  --priority H \
  --status pending \
  --assignees @alice,@bob \
  --tags bug,security \
  --links https://github.com/org/repo/issues/123 \
  --due "2025-11-15" \
  --description "JWT token validation is broken"

Options: - --repo, -r TEXT: Repository name (required in non-interactive) - --title, -t TEXT: Task title (required in non-interactive) - --project, -p TEXT: Project name - --priority [H|M|L]: Priority level - --status, -s [pending|in-progress|completed|cancelled]: Task status - --assignees, -a TEXT: Comma-separated assignees (e.g., @alice,@bob) - --tags TEXT: Comma-separated tags - --links TEXT: Comma-separated URLs - --due TEXT: Due date (ISO format, natural language, or keywords) - --description TEXT: Task description

Due date formats: - ISO: 2025-11-15 - Keywords: today, tomorrow, next week, next month - Natural: Nov 15, November 15 2025

`tsk edit`¶

Edit one or more tasks.

tsk edit TASK_IDS [OPTIONS]

Arguments: - TASK_IDS: Comma-separated display IDs or UUIDs (e.g., 1, 4,5,6)

Options: - --repo, -r TEXT: Limit search to specific repository - --title, -t TEXT: New title - --project, -p TEXT: New project - --priority [H|M|L]: New priority - --status, -s [pending|in-progress|completed|cancelled]: New status - --assignees, -a TEXT: New assignees (comma-separated) - --tags TEXT: New tags (comma-separated) - --links TEXT: New links (comma-separated URLs) - --due TEXT: New due date - --description TEXT: New description

Interactive mode (no field options): Opens an interactive prompt to edit all task fields.

Batch editing (field options provided): Updates specified fields for all matching tasks.

Examples:

# Interactive edit
tsk edit 1

# Change priority
tsk edit 1 --priority H

# Update multiple fields
tsk edit 4 --status in-progress --assignees @alice

# Batch edit multiple tasks
tsk edit 4,5,6 --priority H --tags urgent

# Clear a field (set to empty)
tsk edit 1 --assignees ""

`tsk ext`¶

Set task due dates to a specific date or extend by a duration.

tsk ext TASK_IDS DATE_OR_DURATION [OPTIONS]

Arguments: - TASK_IDS: Comma-separated display IDs or UUIDs - DATE_OR_DURATION: Date or duration to set/extend

Duration formats (relative): - 3d - 3 days - 1w - 1 week - 2m - 2 months (30 days each) - 1y - 1 year (365 days)

Date formats (absolute): - Keywords: today, tomorrow, next week, next month - ISO: 2025-10-30 - Natural: Nov 1, October 30 2025

Options: - --repo, -r TEXT: Limit search to specific repository

Examples:

# Set due date to tomorrow
tsk ext 4 tomorrow

# Extend by 1 week from current due date
tsk ext 4 1w

# Extend multiple tasks
tsk ext 4,5,6 2d

# Set specific date
tsk ext 10 2025-11-15

`tsk move`¶

Move one or more tasks to a different repository.

tsk move TASK_IDS DESTINATION_REPO [OPTIONS]

Arguments: - TASK_IDS: Comma-separated display IDs or UUIDs - DESTINATION_REPO: Target repository name

Options: - --repo, -r TEXT: Source repository (limits task search)

Examples:

# Move task to 'archive' repository
tsk move 4 archive

# Move multiple tasks
tsk move 4,5,6 personal

# Specify source repository
tsk move 10 work --repo backend

`tsk in-progress`¶

Mark one or more tasks as in progress.

tsk in-progress TASK_IDS [OPTIONS]

Arguments: - TASK_IDS: Comma-separated display IDs or UUIDs

Options: - --repo, -r TEXT: Limit search to specific repository

Examples:

# Mark single task as in-progress
tsk in-progress 4

# Mark multiple tasks
tsk in-progress 4,5,6

`tsk done`¶

Mark one or more tasks as completed, or list completed tasks if no task IDs are provided.

# Mark tasks as completed
tsk done TASK_IDS [OPTIONS]

# List completed tasks
tsk done [OPTIONS]

Arguments (optional): - TASK_IDS: Comma-separated display IDs or UUIDs

Options: - --repo, -r TEXT: Filter by repository - --project, -p TEXT: Filter by project - --assignee, -a TEXT: Filter by assignee - --tag, -t TEXT: Filter by tag

Examples:

# Mark task as completed
tsk done 4

# Mark multiple tasks as completed
tsk done 4,5,6

# List all completed tasks
tsk done

# List completed tasks in specific repository
tsk done --repo work

`tsk cancelled`¶

Mark one or more tasks as cancelled.

tsk cancelled TASK_IDS [OPTIONS]

Arguments: - TASK_IDS: Comma-separated display IDs or UUIDs

Options: - --repo, -r TEXT: Limit search to specific repository

Examples:

# Cancel task
tsk cancelled 4

# Cancel multiple tasks
tsk cancelled 4,5,6

`tsk del`¶

Delete one or more tasks permanently.

tsk del TASK_IDS [OPTIONS]

Arguments: - TASK_IDS: Comma-separated display IDs or UUIDs

Options: - --repo, -r TEXT: Limit search to specific repository

Warning: This permanently deletes task files. Use with caution.

Examples:

# Delete task
tsk del 4

# Delete multiple tasks
tsk del 4,5,6

`tsk archive`¶

Archive one or more tasks, or list archived tasks if no task IDs are provided.

# Archive tasks
tsk archive TASK_IDS [OPTIONS]

# List archived tasks
tsk archive [OPTIONS]

Arguments (optional): - TASK_IDS: Comma-separated display IDs or UUIDs

Options: - --repo, -r TEXT: Filter by repository - --project, -p TEXT: Filter by project - --assignee, -a TEXT: Filter by assignee - --tag, -t TEXT: Filter by tag

Behavior: Moves completed tasks to archive/ subdirectory within the repository.

Examples:

# Archive completed tasks
tsk archive 4,5,6

# List all archived tasks
tsk archive

# List archived tasks in specific repository
tsk archive --repo work

`tsk unarchive`¶

Unarchive one or more tasks (restore from archive folder).

tsk unarchive TASK_IDS [OPTIONS]

Arguments: - TASK_IDS: Comma-separated display IDs or UUIDs

Options: - --repo, -r TEXT: Limit search to specific repository

Behavior: Moves tasks from archive/ back to tasks/ subdirectory.

Examples:

# Unarchive task
tsk unarchive 4

# Unarchive multiple tasks
tsk unarchive 4,5,6

Repository Operations¶

`tsk create-repo`¶

Create a new task repository.

tsk create-repo [OPTIONS]

Interactive mode (no options): Prompts for repository name.

Non-interactive mode:

tsk create-repo --name work

Options: - --name, -n TEXT: Repository name

GitHub integration (if default_github_org is configured): Prompts to create corresponding GitHub repository.

Creates: - Directory: {parent_dir}/tasks-{name}/ - Git repository with initial commit - Subdirectory: tasks/ for task files - Optional: GitHub remote repository

`tsk repos`¶

List all task repositories.

tsk repos

Output: Table showing: - Repository name - Path - Task count - Git status (if repository has uncommitted changes or unpushed commits)

`tsk repos-search`¶

Search for TaskRepo repositories on GitHub.

tsk repos-search [OPTIONS]

Options: - --org TEXT: GitHub organization/user to search (uses default_github_org from config if not specified)

Output: List of found repositories with clone URLs

Requires: GitHub CLI (gh) installed and authenticated

`tsk sync`¶

Sync task repositories with git (pull and optionally push).

tsk sync [OPTIONS]

Options: - --repo, -r TEXT: Sync specific repository only - --push / --no-push: Push changes after pulling (default: prompt) - --conflict [auto|local|remote|interactive]: Conflict resolution strategy

Conflict resolution strategies: - auto (default): Smart merge when possible, interactive otherwise - local: Always keep local version - remote: Always keep remote version - interactive: Always prompt for resolution

Behavior: 1. Commits any uncommitted changes 2. Pulls from remote (detects and resolves conflicts) 3. Optionally pushes to remote 4. Displays sync summary

Examples:

# Sync all repositories (interactive)
tsk sync

# Sync specific repository
tsk sync --repo work

# Sync and push automatically
tsk sync --push

# Use specific conflict resolution
tsk sync --conflict local

See Git Sync for detailed conflict resolution documentation.

Global Options¶

Available for all commands:

--version: Show TaskRepo version
-h, --help: Show command help

Environment Variables¶

TaskRepo respects the following environment variables:

EDITOR: Default text editor for descriptions (overridden by default_editor in config)
VISUAL: Alternative to EDITOR
TASKREPO_CONFIG: Custom config file location (default: ~/.TaskRepo/config)

Exit Codes¶

0: Success
1: General error
2: Invalid arguments or options
3: Task not found
4: Repository not found
5: Git operation failed

Next Steps¶

Configuration File - Configuration file format
Task File Format - Task markdown format
Task Management - Task workflow guide

Command Line Interface¶

Command Groups¶

Setup & Configuration¶

tsk init¶

tsk config¶

tsk config-show¶

tsk llm-info¶

tsk upgrade¶

Viewing Tasks¶

tsk list¶

tsk search¶

tsk info¶

tsk tui¶

Managing Tasks¶

tsk add¶

tsk edit¶

tsk ext¶

tsk move¶

tsk in-progress¶

tsk done¶

tsk cancelled¶

tsk del¶

tsk archive¶

tsk unarchive¶

Repository Operations¶

tsk create-repo¶

tsk repos¶

tsk repos-search¶

tsk sync¶

Global Options¶

Environment Variables¶

Exit Codes¶

Next Steps¶

`tsk init`¶

`tsk config`¶

`tsk config-show`¶

`tsk llm-info`¶

`tsk upgrade`¶

`tsk list`¶

`tsk search`¶

`tsk info`¶

`tsk tui`¶

`tsk add`¶

`tsk edit`¶

`tsk ext`¶

`tsk move`¶

`tsk in-progress`¶

`tsk done`¶

`tsk cancelled`¶

`tsk del`¶

`tsk archive`¶

`tsk unarchive`¶

`tsk create-repo`¶

`tsk repos`¶

`tsk repos-search`¶

`tsk sync`¶