Vikunja Vja

Vikunja Tasks (vja CLI)

Interact with a Vikunja instance using the vja command-line tool.

Two rules that always apply:

• Always pass --json for machine-readable output
• Task titles are positional arguments — not --title

---

Tasks

Create

vja add "Task title"
vja add "Task title" -n "Description" -d "tomorrow" -p 3 -l urgent -A alice
vja add "Task title" -d "next monday at 9:00" -r "1h before due_date" -o "My Project"

| Flag | Meaning | |------|---------| | -n / --note | Description/body | | -d / --due | Due date (natural language or ISO) | | --start / --end | Start/end dates | | -p / --prio | Priority: 1=low, 2=medium, 3=high, 4=urgent | | -l / --label | Label (repeat for multiple: -l bug -l backend) | | -A / --assignee | Username to assign | | -r / --reminder | Reminder time ("in 3 days at 18:00", "1h before due_date") | | -o / --project | Project name or ID | | -f / --star | Mark as favorite | | --force-create | Create the label if it doesn't exist |

List & Filter

# Basic list
vja ls --json | jq '.tasks[] | {id, title, due_date, priority}'

# Common filters
vja ls --filter "done eq false" --json | jq '.tasks[] | {id, title}'
vja ls --filter "priority ge 3" --json | jq '.tasks[] | {id, title, priority}'
vja ls --filter "due_date before today" --json | jq '.tasks[] | {id, title, due_date}'
vja ls -l urgent --json | jq '.tasks[] | {id, title}'
vja ls -o "My Project" --json | jq '.tasks[] | {id, title}'
vja ls -u 3 --json | jq '.tasks[] | {id, title, urgency}'  # urgency score >= 3
vja ls --all --json | jq '.tasks[] | {id, title, done}'    # include completed
vja ls --sort "-priority,due_date" --json | jq '.tasks[] | {id, title}'

Filter operators: eq, ne, gt, lt, ge, le, before, after, contains Multiple --filter flags are ANDed together.

Show

vja show  --json | jq '{id, title, description, due_date, priority, assignees, labels}'

Edit

vja edit  -i "New title"
vja edit  -n "Updated description"
vja edit  -a "Appended note"         # append to existing description
vja edit  -d "next friday" -p 4
vja edit  -l bug -l backend          # replace labels
vja edit  -A alice                   # toggle assignee (adds if absent, removes if present)
vja edit  -c true                    # mark completed
vja edit  -f                         # star; use --no-star to unstar
vja edit  -o "Other Project"         # move to a different project

Other task commands

vja toggle                # toggle done/undone
vja delete  -q            # delete quietly
vja defer  2d             # push due date forward (also shifts reminders)
vja defer  1h30m
vja clone  "New title"    # duplicate a task
vja open                  # open in browser

---

Projects

vja project ls --json | jq '.[] | {id, title, parent_project_id}'
vja project show  --json | jq .
vja project add "Project name"
vja project add "Sub-project" -o "Parent Project"

Labels

vja label ls --json | jq '.[] | {id, title}'
vja label add "new-label"

User

vja user show --json | jq '{id, username, email}'

---

Workflow Examples

Daily review

# Overdue open tasks
vja ls --filter "due_date before today" --filter "done eq false" --json \
  | jq '.tasks[] | {id, title, due_date}'

# High-priority open tasks, sorted by urgency
vja ls --filter "priority ge 3" --filter "done eq false" --sort "-urgency" --json \
  | jq '.tasks[] | {id, title, priority, urgency, due_date}'

Create with full context in one shot

vja add "Review PR #42" -p 3 -d "today" -A alice -l review --force-create

Bulk-defer all overdue tasks by one day

vja ls --filter "due_date before today" --filter "done eq false" --json \
  | jq '.tasks[].id' \
  | xargs -I{} vja defer {} 1d -q

Mark complete and confirm

vja toggle  -v --json | jq '{id, title, done}'

---

Notes

• Dates accept natural language via parsedatetime: "tomorrow", "next monday", "in 3 days at 9:00", "2025-12-31"
• --json returns Vikunja API format; --jsonvja returns vja's internal format
• Config lives at ~/.config/vja/config.rc (legacy: ~/.vjacli/vja.rc)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: smk-labs
• Source: smk-labs/claude-config
• License: MIT

Install and usage instructions live in the source repository linked above.