# CL-cli utility

Provide a CLI interface for several recurring tasks for Champs-Libres

Currently:

- convert a gitlab issue to a work package

## Install

There are two components to install:

- a firefox add-ons;
- some binaries on the host machine

### Install firefox add-on

Using firefox, download the `.xpi` file from the [release page](https://gitea.champs-libres.be/julienfastre/cl-cli/releases) of the `julienfastre/cl-cli` repository.

### Install cl-cli binaries

#### Using package manager

A debian package is published and stored on gitea.



```bash
# download the gpg key
sudo curl https://gitea.champs-libres.be/api/packages/julienfastre/debian/repository.key -o /etc/apt/keyrings/gitea-julienfastre.asc

# add the package repository. You must adapt the $distribution (see below)
echo "deb [signed-by=/etc/apt/keyrings/gitea-julienfastre.asc] https://gitea.champs-libres.be/api/packages/julienfastre/debian $distribution main" | sudo tee -a /etc/apt/sources.list.d/gitea.list

# update
sudo apt update

# install
sudo apt install cl-cli
```

Available distributions:

- Ubuntu 24..04: noble
- Ubuntu 25.04: plucky
- Ubuntu: 25.10: questing

**Note:** The package is very simple, there are very few dependencies, and there isn't any difference between them for now.


## Configure

Copy the file [config.toml.dist](./config.toml.dist) as a template, and
save it at the path `$HOME/.config/cl-cli/config.toml`:

```bash
mkdir -p $HOME/.config/cl-cli
cp config.toml $HOME/.config/cl-cli/config.toml
editor $HOME/.config/cl-cli/config.toml
```

Then, fill it with the required configuration options:

- gitea personal access token: 

    ![configuration screenshort](./docs/configuration/gitea_screenshot_configure_pat.png)
- Gitlab: [Create an access token](https://gitlab.com/-/user_settings/personal_access_tokens?name=cl-cli&scopes=api,read_user) With the "api" and "read_user" scopes
- [Openproject](https://champs-libres.openproject.com/my/access_tokens)


## Usage as CLI

### Convert a gitlab issue into a work package

```bash
cl-cli planning i2work https://gitlab.com/Chill-Projet/chill-bundles/-/issues/240 chill
```

Where:

- `https://gitlab.com/Chill-Projet/chill-bundles/-/issues/240` is the URL of the issue
- `chill` is the identifier of the project in openproject (see the identifier 
  in the URL like the page "Vue globale": https://champs-libres.openproject.com/projects/chill/, or 
  see it there: https://champs-libres.openproject.com/projects/chill/identifier (Paramètres du projet / changer 
  l'identifiant (bouton en haut)))