Vikunja Task Manager

---

name: vikunja description: > Manage Vikunja tasks, projects, labels, comments, relations, and attachments via the Vikunja REST API. Use this skill whenever the user asks to view, create, update, complete, or delete tasks or projects in Vikunja. allowed-tools: shell license: MIT

Overview

This skill provides a Python CLI (vikunja.py) that wraps the Vikunja REST API. Run all commands from this skill's base directory using:

python vikunja.py <group> <command> [options]

All output is JSON. Successful responses have a data key. List responses also include a _pagination key. Errors have an error key (and optionally code and http_status).

---

Prerequisites

1. Python 3.10+ is installed.
2. Dependencies are installed: pip install -r requirements.txt
3. Config is set (one-time): python vikunja.py config set --url URL --token TOKEN
   • Get an API token from Vikunja → Settings → API Tokens

---

config — Connection settings

# Save connection details
python vikunja.py config set --url https://vikunja.example.com --token YOUR_API_TOKEN

# Show current config (token masked)
python vikunja.py config show

---

projects — Project management

# List projects (paginated)
python vikunja.py projects list [--page N] [--per-page N] [--search TEXT] [--archived]

# Get a single project
python vikunja.py projects get PROJECT_ID

# Create a project
python vikunja.py projects create --title "My Project" [--description TEXT] [--parent-id N]

# Update a project
python vikunja.py projects update PROJECT_ID [--title TEXT] [--description TEXT]

# Delete a project (and all its tasks)
python vikunja.py projects delete PROJECT_ID

---

tasks — Task management

# List all tasks (optionally filtered)
python vikunja.py tasks list \
  [--project-id N] \
  [--page N] [--per-page N] \
  [--search TEXT] \
  [--filter 'due_date < now && !done'] \
  [--sort-by due_date] [--order-by asc|desc]

# Get a single task
python vikunja.py tasks get TASK_ID

# Create a task in a project
python vikunja.py tasks create \
  --project-id N \
  --title "Task title" \
  [--description TEXT] \
  [--due-date 2024-12-31T23:59:59Z] \
  [--priority 0-5] \
  [--label-ids 1,2,3]

# Update a task (provide only fields to change)
python vikunja.py tasks update TASK_ID \
  [--title TEXT] \
  [--description TEXT] \
  [--due-date 2024-12-31T23:59:59Z] \
  [--priority 0-5] \
  [--done true|false] \
  [--percent-done 0.0-1.0]

# Delete a task
python vikunja.py tasks delete TASK_ID

Filter syntax

The --filter flag uses Vikunja's filter query language:

• Fields: title, description, done, due_date, priority, start_date, end_date, percent_done, created, updated, project_id
• Operators: =, !=, <, <=, >, >=, like
• Values: bare strings, numbers, now, today, true, false
• Combinators: && (and), || (or), ! prefix (not)
• Examples: !done, due_date < now, priority >= 3 && !done, title like "%bug%"

Due date format

Use RFC3339: 2024-12-31T23:59:59Z or 2024-12-31T10:00:00+02:00.

Priority levels

| Value | Meaning | |-------|---------| | 0 | Unset | | 1 | Low | | 2 | Medium | | 3 | High | | 4 | Urgent | | 5 | DO NOW |

---

labels — Label management

# List all labels
python vikunja.py labels list [--search TEXT] [--page N] [--per-page N]

# Get a label
python vikunja.py labels get LABEL_ID

# Create a label
python vikunja.py labels create --title "Bug" [--color "#FF5733"] [--description TEXT]

# Update a label
python vikunja.py labels update LABEL_ID [--title TEXT] [--color "#RRGGBB"] [--description TEXT]

# Delete a label
python vikunja.py labels delete LABEL_ID

# Apply a label to a task
python vikunja.py labels apply --task-id N --label-id N

# Remove a label from a task
python vikunja.py labels remove --task-id N --label-id N

---

comments — Task comments

# List comments on a task
python vikunja.py comments list --task-id N

# Add a comment
python vikunja.py comments create --task-id N --text "Comment text (Markdown supported)"

# Delete a comment
python vikunja.py comments delete --task-id N --comment-id N

---

attachments — Task attachments

# List attachment metadata for a task
python vikunja.py attachments list --task-id N

# Download an attachment to disk
python vikunja.py attachments download --task-id N --attachment-id N [--output-dir ./downloads]
# Returns: {"data": {"saved_to": "/abs/path/to/file.pdf", "filename": "file.pdf"}}

---

relations — Task relations

Supported relation kinds: subtask, parenttask, related, duplicateof, duplicates, blocking, blocked, precedes, follows, copiedfrom, copiedto.

# List all relations for a task
python vikunja.py relations list TASK_ID

# Create a relation
python vikunja.py relations create --task-id N --other-id N --kind subtask

# Delete a relation
python vikunja.py relations delete --task-id N --other-id N --kind subtask

---

Common workflows

Find overdue tasks:

python vikunja.py tasks list --filter "due_date < now && !done" --sort-by due_date

Mark a task done:

python vikunja.py tasks update 42 --done true

Create a task with labels:

python vikunja.py tasks create --project-id 5 --title "Fix login bug" --label-ids 1,3 --priority 4

Download all attachments for a task:

# First list to get IDs
python vikunja.py attachments list --task-id 42
# Then download each one
python vikunja.py attachments download --task-id 42 --attachment-id 7 --output-dir ./downloads