CLI client for Vikunja

This is a simple CLI for Vikunja > The todo app to organize your life.

It provides a command line interface for adding, viewing and editing todo tasks on a Vikunja Server. The goal is to support a command line based task workflow ~ similar to taskwarrior.

Breaking changes in vja 4.0

vja 4.0 supports (and requires) the most recent Vikunja API >= 0.24.0. Use vja up to version 3.3.1 for compatibility with Vikunja API 0.23.0.

Usage

vja --help
vja ls

(You will be prompted for your account on first usage and any time the access token expires, see Features.md)

More user documentation is available on Features.md

Installation

Install from pypi:

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

Upgrade existing version:

python -m pip install --user vja --upgrade

Configuration

Before using vja you must provide a configuration. An example can be found in vja.rc.

Create a configuration file $HOME/.vjacli/vja.rc with ~ the following contents
```
[application]
frontend_url=https://try.vikunja.io/
api_url=https://try.vikunja.io/api/v1
```
(If you cloned from git, you may copy the folder .vjacli to your $HOME directory instead.)
Adjust to your needs. frontend_url and api_url must point to your own Vikunja server. Especially, the api_url must be reachable from your client. This can be verified, for example, by curl https://mydomain.com/api/v1/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 service instance of Vikunja to which vja should connect
[application]	frontend_url	Required to open Vikunja in Browser

Optional options

Section	Option	Description
[output]	arbitrary_name	Python format strings which may be referenced on the command line by `--custom-format=<option_name>`. May contain any valid python f-Format string. Take care: The format string may provide code which will be executed at runtime! Do not use `--custom-format` if you are unsure. Default: missing
[output]	another_format	Multiple formats can be defined for reference. (see above)
[urgency_coefficients]	due_date_weight	Weight of dueness in urgency score. Default: 1.0
[urgency_coefficients]	priority_weight	Weight of priority in urgency score. Default: 1.0
[urgency_coefficients]	favorite_weight	Weight of is_favorite in urgency score. Default: 1.0
[urgency_coefficients]	project_weight	Weight of keyword occurrence in project title in urgency score. Default: 1.0
[urgency_coefficients]	label_weight	Weight of keyword occurrence in label title in urgency score. Default: 1.0
[urgency_keywords]	lisproject_keywords	Tasks in projects with a title containing these keywords are considered more urgent. Default: None
[urgency_keywords]	label_keywords	Tasks labeled with one of these keywords are considered more urgent. Default: None

Development

Prepare python virtual environment

Python >= 3.8 is recommended. 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

cernst72/vja