vja

A command line interface for Vikunja, the open-source todo app to organize your life.

vja lets you add, view and edit your Vikunja tasks and projects directly from the terminal. The goal is a fast, command line based task workflow, similar in spirit to taskwarrior. It also ships an MCP server so AI agents can manage your tasks.

vja add "Buy milk" --due=tomorrow --priority=3   # add a task
vja ls                                           # list active tasks, sorted by urgency
vja check 1                                       # mark task 1 as done

Highlights:

Add, list, edit, defer, clone and delete tasks, with natural-language dates and reminders
Powerful filtering and sorting, plus an urgency score you can tune
Manage projects, labels and kanban buckets
Custom output formats for scripting
Optional MCP server to drive vja from AI agents

More user documentation is in Features.md.

❗ Important change in vja 6.0.0 — a Vikunja server with version >= 2.5.0 is required, and api_url must point to /v2, e.g. api_url=https://my.domain/api/v2.

Installation

Install with pipx (recommended)

(More on pipx here.)

pipx install vja

To install vja with MCP support from the start, install the optional extra instead:

pipx install "vja[mcp]"

To add MCP support to an existing pipx installation of vja, install its dependency into that environment:

pipx inject vja "mcp>=2"

Upgrade an existing version:

pipx upgrade vja

This upgrades vja and its dependencies as needed. If MCP support was added with pipx inject, upgrade the injected MCP dependency as well:

pipx upgrade vja --include-injected

To explicitly upgrade the MCP package even when its installed version already satisfies the mcp>=2 requirement, run:

pipx runpip vja install --upgrade mcp

Install with pip

Not recommended because it does not isolate vja's dependencies from other Python packages.

python -m pip install --user vja
vja --help

Configuration

Before using vja you must provide a configuration. vja looks for its configuration at the following paths (in order):

$VJA_CONFIGDIR/config.rc
$XDG_CONFIG_HOME/vja/config.rc
$HOME/.config/vja/config.rc
$HOME/.vjacli/vja.rc (deprecated - for backward compatibility only)

A full example can be found in config.rc.

Create a configuration file at any valid path (see above) with the following minimal contents:
```
[application]
frontend_url=https://try.vikunja.io/
api_url=https://try.vikunja.io/api/v2
```
(If you cloned from git, you may copy the folder .config/vja to your $HOME/.config directory instead.)
Adjust to your needs. frontend_url and api_url must point to your own Vikunja server. In particular, api_url must be reachable from your client. You can verify this, for example, with curl https://mydomain.com/api/v2/info.

You may change the location of the configuration directory with an environment variable like VJA_CONFIGDIR=/not/my/home.

Description of configuration

Required options

Section	Option	Description
`[application]`	`api_url`	The Vikunja instance vja should connect to
`[application]`	`frontend_url`	Base URL used to open Vikunja in the browser

Optional options

Section	Option	Description
`[output]`	(custom formats)	Named python format strings for `--custom-format`. See Output format.
`[urgency_coefficients]`	`due_date_weight`	Weight of dueness in the urgency score. Default: 1.0
`[urgency_coefficients]`	`priority_weight`	Weight of priority in the urgency score. Default: 1.0
`[urgency_coefficients]`	`favorite_weight`	Weight of is_favorite in the urgency score. Default: 1.0
`[urgency_coefficients]`	`project_weight`	Weight of keyword occurrence in the project title (see `project_keywords`). Default: 1.0
`[urgency_coefficients]`	`label_weight`	Weight of keyword occurrence in label titles (see `label_keywords`). Default: 1.0
`[urgency_keywords]`	`project_keywords`	Tasks in projects whose title contains one of these keywords are more urgent. Default: None
`[urgency_keywords]`	`label_keywords`	Tasks labeled with one of these keywords are more urgent. Default: None

Usage

Once installed and configured, run:

vja --help
vja ls

On first usage (and whenever the access token expires) you will be prompted for your account. See Login in Features.md for details and the API-token alternative, and Features.md for the full command reference.

Shell completion

Shell tab-completion can be enabled by generating a shell completion script (not specific to vja):

Bash

mkdir -p ~/.config/bash/completions
_VJA_COMPLETE=bash_source vja > ~/.config/bash/completions/vja

Then add to your ~/.bashrc:

source ~/.config/bash/completions/vja

Note: Instead of sourcing the completion script in .bashrc you can just move it to a folder which is supported by bash_completion (e.g. ~/.local/share/bash-completion/completions/).

Zsh

mkdir -p ~/.config/zsh/completions
_VJA_COMPLETE=zsh_source vja > ~/.config/zsh/completions/vja.zsh

Then add to your ~/.zshrc:

source ~/.config/zsh/completions/vja.zsh

Note: The script location is just a suggestion; you can put it wherever you like. If you use ohmyzsh, place completion scripts under ~/.oh-my-zsh/custom/completions.

Fish

_VJA_COMPLETE=fish_source vja > ~/.config/fish/completions/vja.fish

Note: Fish completions in the directory above will be automatically loaded for new sessions.

MCP server

Besides the CLI, vja can act as an MCP server so AI agents (Claude, Kiro, Cursor, ...) can manage your Vikunja tasks. Install the optional dependency and register the vja-mcp command with your client:

pipx install "vja[mcp]"   # or: python -m pip install --user "vja[mcp]"

For client configuration, available tools, and other MCP details, see the MCP server documentation in Features.md.

{
  "mcpServers": {
    "vja": {
      "command": "vja-mcp"
    }
  }
}

The server uses the same configuration as the CLI. See Features.md for the available tools and AGENTS.md for agent-specific guidance.

Development

Prepare python virtual environment

First create a local environment:

python -m venv ./venv
source venv/bin/activate

(That may be source venv/Scripts/activate on some windows machines.)

Local build

Local development install

python -m pip install -r requirements_dev.txt
python -m pip install -e .

Run integration test

Start docker container for vikunja/api:latest and execute pytest against that server instance:

docker compose -f tests/docker-compose.yml up -d
VJA_CONFIGDIR=tests/.vjatest pytest
docker compose -f tests/docker-compose.yml down

Environment
- Console
Intended Audience
- End Users/Desktop
Programming Language

Metadata

Environment
- Console
Intended Audience
- End Users/Desktop
Programming Language

Release files for vja 6.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for vja 6.1.1
File	Size	Uploaded
vja-6.1.1.tar.gz	50.7 kB	Oct 3, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for vja 6.1.1
File	Interpreter	ABI	Platform	Reset
vja-6.1.1-py3-none-any.whl 49.2 kB Oct 3, 2026	Python 3	none	any	Details

Total release size: 99.8 kB

Release files / vja-6.1.1.tar.gz

Download URL	vja-6.1.1.tar.gz
Size	50.7 kB
Tags	Source
SHA-256 checksum How to use checksums	`7a6d80cfa97ea848578faeeb064e6e769e53b03821f1d03f1e0d62598aa0c912`
BLAKE2b-256 checksum How to use checksums	`987033fa6a9e47c2276960b120c7272cd14c139f3abb1ca7d40f13cbe6863aaf`
Upload date	Oct 3, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.11.2`

Release files / vja-6.1.1-py3-none-any.whl

Download URL	vja-6.1.1-py3-none-any.whl
Size	49.2 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`28feb7e79b77cda36a0a636e41f40e0d1d5610b36c5ee52519eafbfb29700138`
BLAKE2b-256 checksum How to use checksums	`662626399a92502d5e1d2f3d3555aad7d132a7d1df2f2dae54e38fde6e1358ce`
Upload date	Oct 3, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.11.2`