pypi package version pypi downloads pipeline status coverage report

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):

  1. $VJA_CONFIGDIR/config.rc
  2. $XDG_CONFIG_HOME/vja/config.rc
  3. $HOME/.config/vja/config.rc
  4. $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. Especially, the api_url must be reachable from your client. This can be verified, for example, by 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 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

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (6.0.3)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for ce72 from gravatar.com ce72

Credits

Author: ce72

License expression

GPL-3.0-or-later
View SPDX License List

Requires

Python >=3.12

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

vja-6.0.2.tar.gz (46.0 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

vja-6.0.2-py3-none-any.whl (45.6 kB view details)

Uploaded Python 3

File details

Details for the file vja-6.0.2.tar.gz.

File metadata

  • Download URL: vja-6.0.2.tar.gz
  • Upload date:
  • Size: 46.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.2.0 CPython/3.11.2

File hashes

Hashes for vja-6.0.2.tar.gz
Algorithm Hash digest
SHA256 b0ea035ee3e14a8331f00a90d8e9bd78658b5bf13094a7c61f3455a836b730ba
MD5 22af58edfdbe40e53e4357cc72bde6af
BLAKE2b-256 f13458929a30221d8b12fd8c401f7e9489041e1cae5fd3e14e5f06b95323060b

See more details on using hashes here.

File details

Details for the file vja-6.0.2-py3-none-any.whl.

File metadata

  • Download URL: vja-6.0.2-py3-none-any.whl
  • Upload date:
  • Size: 45.6 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.2.0 CPython/3.11.2

File hashes

Hashes for vja-6.0.2-py3-none-any.whl
Algorithm Hash digest
SHA256 4a18210a84e54d0916346e85680e4c40fec0375a25e58607acfdaff7f6405c0d
MD5 0e8b6ad02e5eb3a3d2003ff6b3cfbfca
BLAKE2b-256 347605eca730b0f339f18d677f7c9e4f8ce3bd941eb8894c97ce43068ff83efb

See more details on using hashes here.

Release history Release notifications | RSS feed

6.0.3

2 files

This release

6.0.2 This release

2 files

6.0.1

2 files

6.0.0

2 files

5.4.2

2 files

5.4.1

2 files

5.4.0

2 files

5.3.0

2 files

5.2.1

2 files

5.2.0

2 files

5.1.0

2 files

5.0.0

2 files

4.10.1

2 files

4.10.0

2 files

4.9.0

2 files

4.8.0

2 files

4.7.3

2 files

4.7.2

2 files

4.7.1

2 files

4.7.0

2 files

4.6.0

2 files

4.5.2

2 files

4.5.1

2 files

4.5.0

2 files

4.4.1

2 files

4.4.0

2 files

4.3.0

2 files

4.2.0

2 files

4.1.0

2 files

4.0.0

2 files

3.4.0

2 files

3.3.1

2 files

3.3.0

2 files

3.2.1

2 files

3.2.0

2 files

3.1.0

2 files

3.0.0

2 files

2.5.0

2 files

2.4.1

2 files

2.4.0

2 files

2.3.0

2 files

2.2.1

2 files

2.2.0

2 files

2.1.0

2 files

2.0.0

2 files

Pre-release

2.0.0rc4

2 files

Pre-release

2.0.0rc3

2 files

Pre-release

2.0.0rc2

2 files

Pre-release

2.0.0rc1

2 files

Pre-release

2.0.0b4

2 files

Pre-release

2.0.0b3

2 files

Pre-release

2.0.0b2

2 files

Pre-release

2.0.0b1

2 files

1.5.1

2 files

1.5.0

2 files

1.4.1

2 files

1.4.0

2 files

1.3.2

2 files

1.3.1

2 files

1.3.0

2 files

1.2.1

2 files

1.2.0

2 files

1.1.0

2 files

1.0.6

2 files

1.0.5

2 files

1.0.4

2 files

1.0.3

1 file

1.0.2

1 file

1.0.0

1 file

0.5.0

1 file

0.4.1

1 file

0.4.0

1 file

0.3.1

1 file

0.3.0

2 files

0.2.2

1 file

0.2.1

1 file

0.2.0

1 file

0.1.11

1 file

0.1.10

1 file

0.1.9

1 file

0.1.8

1 file

0.1.7

1 file

0.1.6

2 files

0.1.5

1 file

0.1.4

2 files

0.1.3

2 files

0.1.2

2 files

0.1.1

2 files

0.1.0

2 files

0.0.13

2 files

0.0.12

2 files

0.0.11

2 files

0.0.10

2 files

0.0.9

2 files

0.0.8

2 files

0.0.7

2 files

0.0.6

2 files

0.0.4

2 files

0.0.3

2 files

0.0.2

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page