Vja - Vikunja CLI Task Manager

Manage tasks on a Vikunja server using the vja command-line interface. vja is a CLI client for Vikunja, the open-source self-hosted task manager.

Prerequisites

Check the installed version, then run a read-only command to check access:

vja --version
vja ls

Do not hide errors: distinguish a missing executable, incompatible API URL, authentication failure, and connection failure before suggesting a fix. These examples were checked against vja 6.0.3, which requires Vikunja >= 2.5.0 and an API URL ending in /api/v2. For other versions, consult vja <command> --help and the upstream documentation. Do not change server configuration or install software unless the user requests it.

Configuration lookup order:

  1. $VJA_CONFIGDIR/config.rc
  2. $XDG_CONFIG_HOME/vja/config.rc
  3. ~/.config/vja/config.rc
  4. ~/.vjacli/vja.rc (legacy fallback)

Use the existing configuration location. Do not print credentials or token files.

Commands Reference

All task commands work as both vja <command> and vja task <command>.

Adding Tasks

# Quick add to default project
vja add "Task title"

# Full options
vja add "Task title" \
  --note="Description text" \
  --priority=3 \
  --favorite \
  --due="tomorrow at 11:00" \
  --reminder \
  --label=@work \
  --project=1

Short flags: -n note, -p priority, -f favorite, -d due date, -r reminder, -l label, -o project

# Clone an existing task
vja clone 1 "Copy of task with this new title"

Listing Tasks

# All active tasks
vja ls

# JSON output
vja ls --json

# Specific tasks by ID
vja ls 10 13 14

Sorting:

vja ls --sort=id
vja ls --sort=-id          # reverse
vja ls --sort='due_date, -priority'

Default sort: 'done, -urgency, due_date, -priority, project.title, title'

Filtering:

vja ls --project=1                          # by project ID
vja ls --project=projec                            # project name (regex)
vja ls --base-project=myproject             # base project
vja ls --label="^@work$"                    # exact label title
vja ls -l work                              # label (regex)
vja ls --due-date="before today"            # overdue
vja ls --filter="due_date ge today" --filter="due_date before in 5 days"  # due within range
vja ls --favorite=True                      # favorites only
vja ls --priority="gt 3"                    # priority greater than 3
vja ls --title=ask                          # title matches regex
vja ls -u                                   # urgency >= 4
vja ls --urgency=8                          # urgency >= 8

Advanced filters:

vja ls --filter="created after 2 days ago"
vja ls --filter="due_date before today in 7 days"
vja ls --filter="labels contains @work"
vja ls --filter="labels ne @work"
vja ls --filter="priority gt 2"
vja ls --filter="title contains clean up"

Filters can be combined:

vja ls --filter="labels ne @work" --project=1 --urgent

Showing a Task

vja show 1
vja show 1 --json
vja show 1 2 3

Editing Tasks

# Update properties
vja edit 1 --title="new title" --due-date="friday" --priority=1 --star
vja edit 1 --no-star

# Set due date with reminder
vja edit 1 --due="in 4 days at 15:00" -r

# Toggle label (use --force to create new label)
vja edit 1 -l @work

# Mark as done
vja edit 1 --done="true"

# Shortcut to toggle done
vja check 1

# Batch edit
vja edit 1 5 8 --due="next monday 14:00"

For “mark done” requests, use --done=true, which leaves an already completed task completed. vja check toggles a single task and can reopen it; use it only when toggling is requested.

Deferring Tasks

# Defer by timedelta
vja defer 1 1d
vja defer 1 2w

# Batch defer
vja defer 1 2 3 1d

Moves a future due date forward by the given timedelta; for an overdue task, sets the due date to now plus that timedelta. Moves the first absolute reminder forward by the timedelta. Relative reminders stay relative to their configured date.

Reminders

# Absolute time
vja edit 1 -r "next sunday at 11:00"

# Relative to due date
vja edit 1 -r "1h before due_date"
vja edit 1 -r "10m before due"

# Set reminder equal to due date
vja edit 1 -r

# Remove reminder
vja edit 1 -r ""

Deleting Tasks

vja delete 1
vja delete 1 2 3

Note: No confirmation prompt — use carefully.

Opening in Browser

# Open Vikunja starting page
vja open

# Open specific tasks in browser
vja open 42 43

Managing Projects

# Add project
vja project add "New Project"

# Add subproject
vja project add "Subproject" -o 2
vja project add "Subproject" -o "parent-title"

# List projects
vja project ls

# Show project details
vja project show 1

# Open in browser
vja project open 1

Managing Kanban Buckets

vja bucket add "Doing" --project=1
vja bucket ls --project-id=1

Managing Labels

vja label add "Next action"
vja label ls

Session

# Logout (removes local token)
vja logout

Urgency

Tasks have an urgency score (displayed in the last column) calculated from:

  • Due date proximity
  • Priority
  • Favorite status
  • Keyword matches in project title
  • Keyword matches in label titles

Weights and keywords are configurable in the active configuration file (normally ~/.config/vja/config.rc) under [urgency_coefficients] and [urgency_keywords].

Priority Values

ValueMeaning
0Unset
1Low
2Medium
3High
4Urgent
5Do now

Common Workflows

Quick task capture

vja add "Fix the login bug" -p 2 -d "tomorrow" -l @work -r

Daily review

vja ls --sort='-urgency' -u
vja ls --due-date="before tomorrow"

Get things done

vja edit 1 --done=true
vja edit 2 3 --done=true

Reschedule

vja defer 5 2d
vja edit 8 9 --due="next monday"
Calendar October 19, 2026