vja 5.1.0
A simple CLI for Vikunja task manager
Requires Python: >=3.9

[![pypi package version](https://img.shields.io/pypi/v/vja)](https://pypi.org/project/vja/)
[![pypi downloads](https://img.shields.io/pypi/dw/vja)](https://pypi.org/project/vja/)
[![pipeline status](https://gitlab.com/ce72/vja/badges/main/pipeline.svg)](https://gitlab.com/ce72/vja/-/pipelines)
[![coverage report](https://gitlab.com/ce72/vja/badges/main/coverage.svg)](https://gitlab.com/ce72/vja/commits/main)

# vja
A command line interface for Vikunja > [The todo app to organize your life](https://vikunja.io/).
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 5.0.0**

Due to an breaking API change in Vikunja, `vja` with version >= 5.0.0 will only support Vikunja with version >= 1.0.0, while `vja` < 5.0.0 is recommended for older Vikunja servers.
(Additionally vja:5.0.0 allows `vja --oldapi` to support pre-1.0.0 server instances. (Deprecated!)) 

**❗Important change in vja 4.10**

New name for configuration file (`config.rc`) and XDG conform path lookup, see [Configuration](#configuration)

## Table of contents
<!-- TOC -->
  * [Usage](#usage)
  * [Installation](#installation)
    * [Install with pipx (recommended)](#install-with-pipx-recommended)
    * [Install with pip](#install-with-pip)
  * [Configuration](#configuration)
    * [Description of configuration](#description-of-configuration)
      * [Required options](#required-options)
      * [Optional options](#optional-options)
    * [Shell completion](#shell-completion)
      * [Bash](#bash)
      * [Zsh](#zsh)
      * [Fish](#fish)
  * [Development](#development)
    * [Prepare python virtual environment](#prepare-python-virtual-environment)
    * [Local build](#local-build)
      * [Local development install](#local-development-install)
      * [Run integration test](#run-integration-test)
<!-- TOC -->
## Usage

```shell
vja --help
vja ls
```

(You will be prompted for your account on first usage and any time the access token expires,
see [Features.md](https://gitlab.com/ce72/vja/-/blob/main/Features.md#login).)

**More user documentation is available on [Features.md](https://gitlab.com/ce72/vja/-/blob/main/Features.md).**

## Installation
### Install with pipx (recommended)
(More on pipx [here](https://pipx.pypa.io/stable/).)
```shell
pipx install vja
```
Upgrade an existing version:
```shell
pipx upgrade vja
 ```

### Install with pip
Not recommended as it might break system dependencies.
  ```shell
  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](https://gitlab.com/ce72/vja/-/blob/main/.config/vja/config.rc).

- Create a configuration file at any valid path (see above) with the following minimal contents
  ```shell
  [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 `.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/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.<br>Take care: The format string may provide code which will be executed at runtime! Do not use `--custom-format` if you are unsure.<br> 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
```sh
mkdir -p ~/.config/bash/completions
_VJA_COMPLETE=bash_source vja > ~/.config/bash/completions/vja
```
Then add to your `~/.bashrc`:
```sh
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
```sh
mkdir -p ~/.config/zsh/completions
_VJA_COMPLETE=zsh_source vja > ~/.config/zsh/completions/vja.zsh
```
Then add to your `~/.zshrc`:
```sh
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](https://ohmyz.sh), place completion scripts under
`~/.oh-my-zsh/custom/completions`.

#### Fish
```sh
_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

Python >= 3.9 is recommended. First create a local environment:

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

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

### Local build

#### Local development install

```shell
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:

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