vja
A command line interface for Vikunja > The todo app to organize your life. Manage your tasks and projects directly from the terminal with simple commands.
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.
❗Important change in vja 6.0.0
Vikunja server with version >= 2.5.0 is required. Please configure your api_url to /v2, like api_url=https://my.domain/api/v2
Table of contents
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 with pipx (recommended)
(More on pipx here.)
pipx install vja
Upgrade an existing version:
pipx upgrade vja
Install with pip
Not recommended as it might break system dependencies.
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/vjato your$HOME/.configdirectory instead.) - Adjust to your needs.
frontend_urlandapi_urlmust point to your own Vikunja server. Especially, the api_url must be reachable from your client. This can be verified, for example, bycurl 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 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 (see project_keywords). Default: 1.0 |
| [urgency_coefficients] | label_weight | Weight of keyword occurrence in label title in urgency score (see label_keywords). Default: 1.0 |
| [urgency_keywords] | project_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 |
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.
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
1 maintainer
Metadata
1 maintainer
Release files for vja 6.0.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| vja-6.0.4.tar.gz | 46.9 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| vja-6.0.4-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 93.0 kB
Release files / vja-6.0.4.tar.gz
| Download URL | vja-6.0.4.tar.gz |
|---|---|
| Size | 46.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b99b97e658018a57a6c8c54557165c00f7dcde9f986d44f6a3b7dfc8fc3d7223
|
|
BLAKE2b-256 checksum How to use checksums |
55946fb8f9b723c4038b0c2970f85fb6596db010d39ab4c01715b9863b1b2f24
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.2
|
Release files / vja-6.0.4-py3-none-any.whl
| Download URL | vja-6.0.4-py3-none-any.whl |
|---|---|
| Size | 46.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
00360eee3f9e2e719feee45c00ce88348267f4b87f1d8a31ecaba225fb841c31
|
|
BLAKE2b-256 checksum How to use checksums |
d1e9786f0dc47b1e5440c1c8b3c6d5f61e95f4c62bba3d4effd891d9e286ec95
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.2
|
