Vikunja

Interact with a self-hosted Vikunja task management instance via its REST API. Use when the user asks to create, update, delete, or list tasks/projects/labels, schedule reminders, check due dates, bulk-complete tasks. Also use for "add to my todo list", "remind me to", "schedule X", "what's on my task list", "mark done", "recurring task", or any Vikunja-specific request. Triggers on: task, todo, to-do, reminder, schedule, project, inbox, label, gantt, vikunja, recurring task.

Self-hosted Vikunja integration via REST API. The instance is configured in references/vikunja.yaml (or ~/.config/vikunja.yaml).

Quick Start

# Authenticate once, then use the token for all requests
TOKEN=$(python3 "$(skill-dir)/scripts/vikunja.py" login)

# Add a task to the Inbox project (id=1)
python3 "$(skill-dir)/scripts/vikunja.py" task create "Walk the dog" --project 1 --due "2026-05-20T18:00:00Z" --priority 2

Configuration

Place ~/.config/vikunja.yaml with:

base_url: "http://192.168.1.230:3456"
username: "admin"
password: "admin123"

The helper script auto-detects this path. Override with env vars: VIKUNJA_BASE_URL, VIKUNJA_USER, VIKUNJA_PASS.

Important API Quirks

• PUT creates resources (not POST)
• POST updates resources (not PUT)
• DELETE works for deleting tasks/projects
• Tasks are created under a project — each project must exist first
• Token expires; the script re-authenticates automatically on 401

Core Workflows

1. Create a Task

python3 "$(skill-dir)/scripts/vikunja.py" task create "Title" \
  --project 1 \
  --description "Details here" \
  --due "2026-05-20T18:00:00" \
  --start "2026-05-19T09:00:00" \
  --priority 2 \
  --label "work" \
  --reminder "before 1h"

Supported flags: --project, --description, --due, --start, --end, --priority, --label, --reminder, --repeat-every, --repeat-mode (0=default, 1=monthly, 2=from-current), --color.

2. List Tasks

# All tasks
python3 "$(skill-dir)/scripts/vikunja.py" task list

# Tasks in a specific project
python3 "$(skill-dir)/scripts/vikunja.py" task list --project 1

# Only undone tasks, sorted by priority descending
python3 "$(skill-dir)/scripts/vikunja.py" task list --filter "done=false" --sort-by "priority" --order "desc"

Filter syntax: see API Reference for full query syntax.

3. Update a Task

# Mark as done
python3 "$(skill-dir)/scripts/vikunja.py" task update $TASK_ID --done

# Change due date
python3 "$(skill-dir)/scripts/vikunja.py" task update $TASK_ID --due "2026-05-21T10:00:00"

# Change priority
python3 "$(skill-dir)/scripts/vikunja.py" task update $TASK_ID --priority 3

4. Bulk Operations

# Mark multiple tasks done at once
python3 "$(skill-dir)/scripts/vikunja.py" tasks bulk-complete 12 15 18

5. Projects

# List all projects
python3 "$(skill-dir)/scripts/vikunja.py" project list

# Create a new project
python3 "$(skill-dir)/scripts/vikunja.py" project create "Side Projects" --identifier "SP" --color "#ff6600"

6. Labels

# List labels
python3 "$(skill-dir)/scripts/vikunja.py" label list

# Create a label
python3 "$(skill-dir)/scripts/vikunja.py" label create "urgent" --color "#ff0000"

# Assign label to task
python3 "$(skill-dir)/scripts/vikunja.py" task add-label $TASK_ID "urgent"

7. Delete

python3 "$(skill-dir)/scripts/vikunja.py" task delete $TASK_ID
python3 "$(skill-dir)/scripts/vikunja.py" project delete $PROJECT_ID

AI Usage Patterns

When the user says "schedule X for Y date", parse the date and create a task:

• "remind me to buy milk tomorrow at 6pm" → task title "Buy milk", due "2026-05-19T18:00:00"
• "every monday review expenses" → task with --repeat-every 604800 --repeat-mode 0
• "add fix the login bug as high priority" → priority 3 or 4

For recurring tasks, compute repeat_after in seconds:

• daily = 86400, weekly = 604800, monthly = 2592000, yearly = 31536000

Version Notes

• Buckets/Kanban (bucket commands) require Vikunja v2.4+ — not available in v2.3.0
• Admin routes (/api/v1/admin/) require Vikunja v2.4+ — not available in v2.3.0
• This skill works with Vikunja v2.3.0+ for all task/project/label operations

Error Handling

• 401 → re-login automatically
• 403 → project access issue; list projects to check permissions
• 404 → task/project not found; try listing to find it
• 400 → invalid request body; check required fields (title is always required)
• Log errors to memory/vikunja-errors.log for debugging

Resources

• Full API Reference — endpoint details, schemas, examples