CLI Reference

Auto-generated from the Click command definitions. For hands-on examples and workflows, see the CLI Guide.

taskdog

Taskdog: Task management CLI tool with time tracking and optimization.

Usage:

taskdog [OPTIONS] [COMMAND] [ARGS]...

Options:

Name	Type	Description	Default
--version	boolean	Show the version and exit.	False
-H, --host	text	API server host (overrides config/env)	None
-p, --port	integer range (between 1 and 65535)	API server port (overrides config/env)	None
-k, --api-key	text	API key for authentication (overrides config/env)	None
-h, --help	boolean	Show this message and exit.	False

taskdog add

Add a new task.

Usage:

taskdog add [OPTIONS] NAME

Options:

Name	Type	Description	Default
--priority, -p	integer	Task priority (default: from config or 5, higher value = higher priority)	None
--fixed, -f	boolean	Mark task as fixed (won't be rescheduled by optimizer)	False
--depends-on, -d	integer	Task IDs this task depends on (can be specified multiple times)	Sentinel.UNSET
--tag, -t	text	Tags for categorization and filtering (can be specified multiple times)	Sentinel.UNSET
--deadline, -D	datetime (%Y-%m-%d %H:%M:%S)	Task deadline (format: YYYY-MM-DD HH:MM:SS)	None
--estimate, -e	float	Estimated duration in hours (must be > 0)	None
--start, -s	datetime (%Y-%m-%d %H:%M:%S)	Planned start time (format: YYYY-MM-DD HH:MM:SS)	None
--end, -E	datetime (%Y-%m-%d %H:%M:%S)	Planned end time (format: YYYY-MM-DD HH:MM:SS)	None
-h, --help	boolean	Show this message and exit.	False

taskdog audit

Inspect operation history (audit logs).

Usage:

taskdog audit [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
-h, --help	boolean	Show this message and exit.	False

taskdog audit list

Display operation history (audit logs).

Shows a history of operations performed via the API, including task creates, updates, status changes, and other modifications.

Use filters to narrow down the logs by client name, operation type, task ID, etc.

Examples: taskdog audit list # Show latest 100 logs taskdog audit list --client claude-code # Filter by client taskdog audit list --task 123 # Filter by task ID taskdog audit list --operation complete_task # Filter by operation taskdog audit list --since 2025-12-01 # Filter by date

Usage:

taskdog audit list [OPTIONS]

Options:

Name	Type	Description	Default
--client, -c	text	Filter by client name (e.g., 'claude-code')	None
--operation, -o	text	Filter by operation type (e.g., 'create_task', 'complete_task')	None
--task, -t	integer	Filter by task ID	None
--since	text	Show logs since this date (ISO format: YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS)	None
--until	text	Show logs until this date (ISO format: YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS)	None
--limit, -n	integer range (between 1 and 1000)	Maximum number of logs to show (default: 100, max: 1000)	100
--failed	boolean	Show only failed operations	False
-h, --help	boolean	Show this message and exit.	False

taskdog cancel

Mark task(s) as canceled.

Usage:

taskdog cancel [OPTIONS] TASK_IDS...

Options:

Name	Type	Description	Default
-h, --help	boolean	Show this message and exit.	False

taskdog db

Back up and restore the database.

Usage:

taskdog db [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
-h, --help	boolean	Show this message and exit.	False

taskdog db backup

Back up the database to a physical .db snapshot.

Usage:

taskdog db backup [OPTIONS]

Options:

Name	Type	Description	Default
--output, -o	file	Output file path (default: ./taskdog-backup-YYYYMMDD-HHMMSS.db).	Sentinel.UNSET
-h, --help	boolean	Show this message and exit.	False

taskdog db restore

Restore the database from a physical .db snapshot (applied on restart).

Usage:

taskdog db restore [OPTIONS] FILE_PATH

Options:

Name	Type	Description	Default
--yes, -y	boolean	Skip the confirmation prompt.	False
-h, --help	boolean	Show this message and exit.	False

taskdog dep

Manage task dependencies.

Usage:

taskdog dep [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
-h, --help	boolean	Show this message and exit.	False

taskdog dep add

Add a dependency to a task.

Usage:

taskdog dep add [OPTIONS] TASK_ID DEPENDS_ON_ID

Options:

Name	Type	Description	Default
-h, --help	boolean	Show this message and exit.	False

taskdog dep rm

Remove a dependency from a task.

Usage:

taskdog dep rm [OPTIONS] TASK_ID DEPENDS_ON_ID

Options:

Name	Type	Description	Default
-h, --help	boolean	Show this message and exit.	False

taskdog done

Mark task(s) as completed.

Usage:

taskdog done [OPTIONS] TASK_IDS...

Options:

Name	Type	Description	Default
-h, --help	boolean	Show this message and exit.	False

taskdog export

Export tasks to various formats (exports non-archived tasks by default).

Usage:

taskdog export [OPTIONS]

Options:

Name	Type	Description	Default
--format	choice (json | csv | markdown)	Output format (default: json).	json
--output, -o	path	Output file path (default: stdout).	Sentinel.UNSET
--fields, -f	field_list	Comma-separated list of fields to export (e.g., 'id,name,priority,status'). Available: id, name, priority, status, created_at, updated_at, planned_start, planned_end, deadline, actual_start, actual_end, estimated_duration, actual_duration_hours, is_fixed, is_archived, is_finished, has_notes, depends_on, tags, daily_allocations	Sentinel.UNSET
--tag, -t	text	Filter by tags (can be specified multiple times, uses OR logic)	Sentinel.UNSET
--end-date, -e	datetime (%Y-%m-%d | %Y-%m-%dT%H:%M:%S | %Y-%m-%d %H:%M:%S)	End date for filtering (YYYY-MM-DD). Shows tasks with any date field <= end date.	Sentinel.UNSET
--start-date, -s	datetime (%Y-%m-%d | %Y-%m-%dT%H:%M:%S | %Y-%m-%d %H:%M:%S)	Start date for filtering (YYYY-MM-DD). Shows tasks with any date field >= start date.	Sentinel.UNSET
--status	choice (pending | in_progress | completed | canceled)	Filter tasks by status (overrides --all). Note: archived tasks are controlled by the --all flag, not --status.	None
--all, -a	boolean	Show all tasks including completed, canceled, and archived	False
-h, --help	boolean	Show this message and exit.	False

taskdog fix-times

Correct actual start/end timestamps and duration for a task.

Usage:

taskdog fix-times [OPTIONS] TASK_ID

Options:

Name	Type	Description	Default
--start, -s	DATETIME	Actual start datetime (empty string "" to clear)	None
--end, -e	DATETIME	Actual end datetime (empty string "" to clear)	None
--duration, -d	FLOAT	Actual duration in hours (empty string "" to clear)	None
-h, --help	boolean	Show this message and exit.	False

taskdog gantt

Display tasks in Gantt chart format with workload analysis.

By default, shows non-archived tasks (all statuses except archived). Use -a/--all to include archived tasks. Use --status to filter by specific status (overrides --all). Use --tag to filter by tags (OR logic when multiple tags specified).

WORKLOAD CALCULATION: The chart displays a "Workload[h]" row at the bottom showing daily workload: - Hours are calculated from task estimated_duration - Workload is distributed across weekdays only (excludes weekends) - Values are rounded up (e.g., 4.3h → 5h)

COLOR CODING: - Gray (0h): No workload scheduled - Green (1-6h): Normal workload - Yellow (6-8h): Near capacity - Red (8h+): Overloaded, requires adjustment

TIMELINE SYMBOLS: - "░░░" (gray background): Planned period - "◆" (colored): Actual progress (status-based color) - "◆" (red): Deadline marker - " · ": No activity

EXAMPLE: taskdog gantt # Show non-archived tasks taskdog gantt -a # Show all tasks (including archived) taskdog gantt --status completed # Show only completed tasks taskdog gantt -t work -t urgent # Tasks with tag "work" OR "urgent" taskdog gantt --start-date 2025-10-01 --end-date 2025-10-31 # October tasks

Usage:

taskdog gantt [OPTIONS]

Options:

Name	Type	Description	Default
--tag, -t	text	Filter by tags (can be specified multiple times, uses OR logic)	Sentinel.UNSET
--start-date, -s	datetime (%Y-%m-%d | %Y-%m-%dT%H:%M:%S | %Y-%m-%d %H:%M:%S)	Start date for the chart (YYYY-MM-DD). Defaults to previous Monday.	Sentinel.UNSET
--end-date, -e	datetime (%Y-%m-%d | %Y-%m-%dT%H:%M:%S | %Y-%m-%d %H:%M:%S)	End date for the chart (YYYY-MM-DD). Defaults to fit terminal width.	Sentinel.UNSET
--reverse, -r	boolean	Reverse sort order	False
--sort	choice (id | priority | deadline | name | status | planned_start | created_at | updated_at)	Sort tasks by specified field (default: deadline)	deadline
--status	choice (pending | in_progress | completed | canceled)	Filter tasks by status (overrides --all). Note: archived tasks are controlled by the --all flag, not --status.	None
--all, -a	boolean	Show all tasks including completed, canceled, and archived	False
-h, --help	boolean	Show this message and exit.	False

taskdog list

Display tasks in flat table format (shows non-archived tasks by default).

Usage:

taskdog list [OPTIONS]

Options:

Name	Type	Description	Default
--fields, -f	field_list	Comma-separated list of fields to display (e.g., 'id,name,note,priority,status'). Available: id, name, note, priority, status, depends_on, planned_start, planned_end, actual_start, actual_end, deadline, duration, created_at, tags	Sentinel.UNSET
--tag, -t	text	Filter by tags (can be specified multiple times, uses OR logic)	Sentinel.UNSET
--end-date, -e	datetime (%Y-%m-%d | %Y-%m-%dT%H:%M:%S | %Y-%m-%d %H:%M:%S)	End date for filtering (YYYY-MM-DD). Shows tasks with any date field <= end date.	Sentinel.UNSET
--start-date, -s	datetime (%Y-%m-%d | %Y-%m-%dT%H:%M:%S | %Y-%m-%d %H:%M:%S)	Start date for filtering (YYYY-MM-DD). Shows tasks with any date field >= start date.	Sentinel.UNSET
--reverse, -r	boolean	Reverse sort order	False
--sort	choice (id | priority | deadline | name | status | planned_start | created_at | updated_at)	Sort tasks by specified field (default: id)	id
--status	choice (pending | in_progress | completed | canceled)	Filter tasks by status (overrides --all). Note: archived tasks are controlled by the --all flag, not --status.	None
--all, -a	boolean	Show all tasks including completed, canceled, and archived	False
-h, --help	boolean	Show this message and exit.	False

taskdog note

Edit task notes in markdown. Supports stdin, --content, --file, or $EDITOR.

Usage:

taskdog note [OPTIONS] TASK_ID

Options:

Name	Type	Description	Default
--content, -c	text	Note content as a string (alternative to opening editor).	Sentinel.UNSET
--file, -f	file	Read note content from a file (alternative to opening editor).	Sentinel.UNSET
--append, -a	boolean	Append to existing notes instead of replacing them.	False
-h, --help	boolean	Show this message and exit.	False

taskdog optimize

Auto-generate optimal schedules for tasks based on priority, deadlines, and workload.

By default, schedules tasks with estimated_duration across weekdays only. Use --include-all-days to schedule on weekends and holidays too. Use --force to override existing schedules.

Examples: taskdog optimize # Optimize all schedulable tasks (weekdays only) taskdog optimize 1 2 3 # Optimize only tasks 1, 2, and 3 taskdog optimize 5 --force # Force optimize task 5 taskdog optimize --include-all-days # Include weekends and holidays

Usage:

taskdog optimize [OPTIONS] [TASK_IDS]...

Options:

Name	Type	Description	Default
--start-date	datetime (%Y-%m-%d | %Y-%m-%dT%H:%M:%S | %Y-%m-%d %H:%M:%S)	Start date for scheduling (YYYY-MM-DD, default: server current time)	Sentinel.UNSET
--max-hours-per-day, -m	float range (between 0 and 24.0)	Max work hours per day (required, e.g., 6.0 or 8.0)	Sentinel.UNSET
--algorithm, -a	text	Optimization algorithm (required): greedy (front-load), balanced (even distribution), backward (JIT from deadline), priority_first (priority only), earliest_deadline (EDF), round_robin (parallel progress), dependency_aware (CPM), genetic (evolutionary), monte_carlo (random sampling)	Sentinel.UNSET
--force, -f	boolean	Override existing schedules	False
--include-all-days	boolean	Schedule tasks on weekends and holidays too (default: weekdays only)	False
-h, --help	boolean	Show this message and exit.	False

taskdog pause

Pause task(s) and reset time tracking (sets status to PENDING).

Usage:

taskdog pause [OPTIONS] TASK_IDS...

Options:

Name	Type	Description	Default
-h, --help	boolean	Show this message and exit.	False

taskdog reopen

Reopen completed or canceled task(s).

Usage:

taskdog reopen [OPTIONS] TASK_IDS...

Options:

Name	Type	Description	Default
-h, --help	boolean	Show this message and exit.	False

taskdog restore

Restore archived task(s).

Usage:

taskdog restore [OPTIONS] TASK_IDS...

Options:

Name	Type	Description	Default
-h, --help	boolean	Show this message and exit.	False

taskdog rm

Remove task(s) (archive by default, --hard for permanent deletion).

Usage:

taskdog rm [OPTIONS] TASK_IDS...

Options:

Name	Type	Description	Default
--hard	boolean	Permanently delete the task(s) instead of archiving.	False
-h, --help	boolean	Show this message and exit.	False

taskdog show

Show task details and notes with markdown rendering.

Usage:

taskdog show [OPTIONS] TASK_ID

Options:

Name	Type	Description	Default
--raw	boolean	Show raw markdown instead of rendered	False
-h, --help	boolean	Show this message and exit.	False

taskdog start

Start working on task(s) (sets status to IN_PROGRESS).

Usage:

taskdog start [OPTIONS] TASK_IDS...

Options:

Name	Type	Description	Default
-h, --help	boolean	Show this message and exit.	False

taskdog stats

Display task statistics and analytics.

Shows comprehensive statistics including basic counts, time tracking, estimation accuracy, deadline compliance, priority distribution, and trends.

Use --period to filter by time period and --focus to show specific sections.

Usage:

taskdog stats [OPTIONS]

Options:

Name	Type	Description	Default
--period, -p	choice (all | 7d | 30d)	Time period for filtering tasks (default: all)	all
--focus, -f	choice (all | basic | time | estimation | deadline | priority | trends)	Focus on specific statistics section (default: all)	all
-h, --help	boolean	Show this message and exit.	False

taskdog tag

View, set, or delete task tags.

Usage:

taskdog tag [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
-h, --help	boolean	Show this message and exit.	False

taskdog tag list

List all tags, or the tags of a single task.

Usage:

taskdog tag list [OPTIONS] [TASK_ID]

Options:

Name	Type	Description	Default
-h, --help	boolean	Show this message and exit.	False

taskdog tag rm

Delete a tag from the system (removes it from all tasks).

Usage:

taskdog tag rm [OPTIONS] TAG_NAME

Options:

Name	Type	Description	Default
-h, --help	boolean	Show this message and exit.	False

taskdog tag set

Set (replace) the tags of a task.

Usage:

taskdog tag set [OPTIONS] TASK_ID [TAGS]...

Options:

Name	Type	Description	Default
-h, --help	boolean	Show this message and exit.	False

taskdog timeline

Display actual work times for a specific day.

Shows when tasks were actually worked on during the day, based on actual_start and actual_end timestamps. This is a "daily Gantt" view where the horizontal axis is time-of-day instead of calendar days.

DISPLAY: - Horizontal axis: Hours of the day (e.g., 08, 09, 10, ...) - Vertical axis: Tasks (sorted by start time) - Bars: Show actual work periods with status-based colors - Duration: Work time for each task on that day

INCLUDED TASKS: - Tasks with actual_start on the target date - IN_PROGRESS tasks (uses current time as end) - Tasks spanning multiple days (clipped to target date)

COLOR CODING: - Blue bars: IN_PROGRESS - Green bars: COMPLETED - Red bars: CANCELED

EXAMPLE: taskdog timeline # Show today's work times taskdog timeline -d 2026-01-29 # Show specific date taskdog timeline --date 2026-01-15 # Show specific date (long form)

Usage:

taskdog timeline [OPTIONS]

Options:

Name	Type	Description	Default
--date, -d	datetime (%Y-%m-%d)	Date to show timeline for (YYYY-MM-DD). Defaults to today.	None
-h, --help	boolean	Show this message and exit.	False

taskdog tui

Launch the Text User Interface for interactive task management.

Usage:

taskdog tui [OPTIONS]

Options:

Name	Type	Description	Default
-h, --help	boolean	Show this message and exit.	False

taskdog update

Update multiple task properties at once.

Usage:

taskdog update [OPTIONS] TASK_ID

Options:

Name	Type	Description	Default
--name	text	New task name	None
--priority	integer	New priority	None
--status	choice (PENDING | IN_PROGRESS | COMPLETED | CANCELED)	New status	None
--planned-start	datetime (%Y-%m-%d %H:%M:%S)	Planned start (format: YYYY-MM-DD HH:MM:SS)	None
--planned-end	datetime (%Y-%m-%d %H:%M:%S)	Planned end (format: YYYY-MM-DD HH:MM:SS)	None
--deadline	datetime (%Y-%m-%d %H:%M:%S)	Deadline (format: YYYY-MM-DD HH:MM:SS)	None
--estimated-duration	float	Estimated duration in hours (e.g., 2.5)	None
-h, --help	boolean	Show this message and exit.	False