gh-benjaminjackson-reclaim-skills-reclaim/skills/reclaim-tasks/REFERENCE.md

Reclaim Tasks: Complete Reference

Complete reference documentation for the reclaim CLI.

Commands

list [FILTER]

List tasks with optional filter.

Filters:

• active (default when no command given) - Lists scheduled and in-progress tasks
• completed - Lists completed tasks
• overdue - Lists tasks past their due date

Examples:

reclaim                # List active tasks (default)
reclaim list           # List active tasks (explicit)
reclaim list active    # List active tasks
reclaim list completed # List completed tasks
reclaim list overdue   # List overdue tasks

create

Create a new task. Requires --title at minimum.

Required:

• --title TITLE - Task title

Optional: See "Task Options" section below

Examples:

reclaim create --title "My task"
reclaim create --title "Important work" --due 2025-11-15 --priority P1

get TASK_ID

Get detailed information about a specific task.

Arguments:

• TASK_ID - The unique identifier for the task

Examples:

reclaim get abc123

update TASK_ID

Update an existing task. At least one option must be provided.

Arguments:

• TASK_ID - The unique identifier for the task

Options: See "Task Options" section below

Examples:

reclaim update abc123 --title "Updated title"
reclaim update abc123 --priority P1 --due 2025-11-20

complete TASK_ID

Mark a task as complete (sets status to ARCHIVED).

Arguments:

• TASK_ID - The unique identifier for the task

Examples:

reclaim complete abc123

Note: This sets the task to ARCHIVED status, which represents a truly completed task in Reclaim.

delete TASK_ID

Permanently delete a task. This action cannot be undone.

Arguments:

• TASK_ID - The unique identifier for the task

Examples:

reclaim delete abc123

Warning: This is permanent deletion. Use complete if you want to mark a task as done while preserving it.

list-schemes

List all available time schemes for the account.

Examples:

reclaim list-schemes

help

Show help message with command and option reference.

Examples:

reclaim help
reclaim --help

Task Options

Options available for create and update commands.

--title TITLE

Task title text.

Type: String Required for: create Optional for: update

Examples:

--title "Write quarterly report"
--title "Review PR #123"

--due DATE

Task due date. Can be a date or date-time.

Type: Date (YYYY-MM-DD) or DateTime (YYYY-MM-DDTHH:MM:SS) Special values: none, clear, null (to remove due date)

Examples:

--due 2025-11-30
--due 2025-11-30T17:00:00
--due none  # Clear the due date

--priority PRIORITY

Task priority level.

Type: P1, P2, P3, or P4 Default: P3 (when not specified)

Priority levels:

• P1 - Highest priority (most urgent/important)
• P2 - High priority
• P3 - Medium priority (default)
• P4 - Low priority

Examples:

--priority P1
--priority P4

--duration HOURS

Task duration in hours.

Type: Decimal number Common values:

• 0.25 - 15 minutes
• 0.5 - 30 minutes
• 0.75 - 45 minutes
• 1 - 1 hour
• 1.5 - 90 minutes
• 2 - 2 hours
• 4 - 4 hours (half day)
• 8 - 8 hours (full day)

Examples:

--duration 2
--duration 0.5
--duration 1.5

--split [CHUNK_SIZE]

Allow Reclaim to split the task into smaller chunks across multiple time slots.

Type: Optional decimal number (minimum chunk size in hours) Default: When flag is present without value, Reclaim uses its default minimum

Examples:

--split              # Allow splitting with default minimum
--split 0.5          # Allow splitting, minimum 30-minute chunks
--split 1            # Allow splitting, minimum 1-hour chunks

Note: Use with --min-chunk and --max-chunk for finer control.

--min-chunk HOURS

Minimum chunk size when task splitting is enabled.

Type: Decimal number (hours) Requires: --split flag

Examples:

--split --min-chunk 0.5   # Minimum 30-minute chunks
--split --min-chunk 1     # Minimum 1-hour chunks

--max-chunk HOURS

Maximum chunk size when task splitting is enabled.

Type: Decimal number (hours) Requires: --split flag

Examples:

--split --max-chunk 2     # Maximum 2-hour chunks
--split --min-chunk 0.5 --max-chunk 2  # Between 30min and 2 hours

--min-work HOURS

Minimum total work duration.

Type: Decimal number (hours)

Examples:

--min-work 1
--min-work 0.5

--max-work HOURS

Maximum total work duration.

Type: Decimal number (hours)

Examples:

--max-work 4
--max-work 2

--defer DATE

Start task after this date/time. Task won't be scheduled before this date.

Type: Date (YYYY-MM-DD) or DateTime (YYYY-MM-DDTHH:MM:SS) Special values: none, clear, null (to remove defer date) Alias: --snooze (same functionality)

Examples:

--defer 2025-11-15
--defer 2025-11-15T09:00:00
--defer none  # Clear the defer date

--snooze DATE

Synonym for --defer. Start task after this date/time.

Type: Date (YYYY-MM-DD) or DateTime (YYYY-MM-DDTHH:MM:SS) Special values: none, clear, null (to remove snooze date)

Examples:

--snooze 2025-11-20
--snooze none  # Clear the snooze date

--start DATE

Specific start time for the task. Locks the task to a specific calendar slot.

Type: DateTime (YYYY-MM-DDTHH:MM:SS) Special values: none, clear, null (to remove specific start time)

Examples:

--start 2025-11-15T14:00:00
--start none  # Clear the specific start time

Note: This pins the task to a specific calendar time rather than letting Reclaim schedule it flexibly.

--time-scheme SCHEME

Time scheme that defines when the task can be scheduled.

Type: Time scheme ID or alias

Common aliases:

• work, working hours, business hours - Finds schemes containing 'work'
• personal, off hours, private - Finds schemes containing 'personal'

Examples:

--time-scheme work
--time-scheme personal
--time-scheme ts_abc123def  # Specific scheme ID

Note: Use reclaim list-schemes to see available time schemes.

--private BOOL

Make the task private (hidden from others who can see your calendar).

Type: Boolean (true or false)

Examples:

--private true
--private false

--category CATEGORY

Event category for grouping and filtering.

Type: String

Examples:

--category "Meetings"
--category "Deep Work"
--category "Planning"

--color COLOR

Color for the event on your calendar.

Type: Color name or code

Examples:

--color blue
--color red
--color green

--notes TEXT

Additional notes or description for the task.

Type: String (may require quotes if contains spaces)

Examples:

--notes "Need to include Q3 metrics"
--notes "Follow up with John about API changes"

Date and Time Formats

Date Format

Format: YYYY-MM-DD Examples:

• 2025-11-15
• 2025-12-31
• 2026-01-01

DateTime Format

Format: YYYY-MM-DDTHH:MM:SS Examples:

• 2025-11-15T14:30:00 (2:30 PM)
• 2025-11-15T09:00:00 (9:00 AM)
• 2025-11-20T16:45:00 (4:45 PM)

Clearing Dates

To remove a date field, use any of these special values:

• none
• clear
• null

Examples:

reclaim update abc123 --due none
reclaim update abc123 --defer clear
reclaim update abc123 --start null

Status Values

Tasks in Reclaim can have the following statuses:

• SCHEDULED - Task is scheduled on the calendar
• IN_PROGRESS - Task is currently being worked on
• COMPLETE - Task is marked complete but still active
• ARCHIVED - Task is truly completed (set by reclaim complete)

Note: The complete command sets status to ARCHIVED, which represents a truly finished task.

Time Scheme Aliases

When using --time-scheme, you can use aliases instead of scheme IDs:

Work-related aliases:

• work
• working hours
• business hours

These find schemes containing "work" in their name.

Personal-related aliases:

• personal
• off hours
• private

These find schemes containing "personal" in their name.

Example:

reclaim create --title "Code review" --duration 2 --time-scheme work

GTD Integration

The CLI supports GTD (Getting Things Done) integration:

ID Tracking Format

Store Reclaim task IDs in your GTD system (e.g., NEXT.md) using this format:

[Reclaim:task_id]

Example:

- [ ] Finish quarterly report [Reclaim:abc123def]
- [ ] Review team PRs [Reclaim:xyz789ghi]

This allows you to sync your GTD system with Reclaim tasks.

Error Handling

Common errors:

Missing required fields:

Error: --title is required for create command

Solution: Provide the --title option.

Invalid task ID:

Error: Task not found: abc123

Solution: Verify the task ID using reclaim list or reclaim list completed.

Invalid date format:

Error: Invalid date format

Solution: Use YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS format.

Invalid priority:

Error: Priority must be P1, P2, P3, or P4

Solution: Use one of the four priority levels.

Best Practices

Use priorities wisely

• Reserve P1 for truly urgent and important tasks
• Use P2 for important but less urgent work
• Default P3 works for most regular tasks
• Use P4 for nice-to-have items

Set realistic durations

• Be honest about how long tasks take
• Include buffer time for context switching
• Consider using --split for longer tasks to allow flexible scheduling

Use time schemes effectively

• Create separate schemes for work and personal time
• Use schemes to enforce work-life boundaries
• Apply the right scheme to ensure tasks are scheduled appropriately

Defer vs Start

• Use --defer when you want Reclaim to schedule the task flexibly after a date
• Use --start when the task MUST happen at a specific time
• Avoid over-using --start as it reduces scheduling flexibility

Task splitting strategy

• Enable --split for tasks longer than 2 hours
• Set --min-chunk to maintain focus (e.g., 1 hour minimum)
• Set --max-chunk to prevent overly long blocks

Keep tasks actionable

• Use clear, action-oriented titles
• Add context in --notes for future reference
• Complete or delete tasks promptly to keep your list current

Complete Examples

Complex task creation

reclaim create \
  --title "Q4 Planning Session" \
  --due 2025-11-30 \
  --priority P2 \
  --duration 6 \
  --split \
  --min-chunk 1.5 \
  --max-chunk 3 \
  --time-scheme work \
  --category "Planning" \
  --color blue \
  --notes "Include team input from retrospective"

Full task update

reclaim update abc123 \
  --title "Updated: Q4 Planning Session" \
  --priority P1 \
  --due 2025-11-25 \
  --duration 4 \
  --notes "Deadline moved up due to executive meeting"

Task with deferred start and specific duration

reclaim create \
  --title "Annual review preparation" \
  --defer 2025-12-01 \
  --duration 3 \
  --priority P2 \
  --time-scheme personal \
  --private true