recodex-cli 0.2.2
CLI client for ReCodEx API implemented in Python based on recodex-pylib.
Requires Python: >=3.11

# ReCodEx CLI Client

A command-line interface for the [ReCodEx](https://github.com/ReCodEx) system. This tool allows users to interact with ReCodEx from their terminal, streamlining workflows and enabling scripting possibilities. The aim is not to create a terminal-based replacement for web application, but rather an intermediate layer for bash scripts or other automation tools.

This tool is built on top of the [recodex-pylib](https://github.com/ReCodEx/pylib) Python library, which provides a wrapper for ReCodEx API generated from OpenAPI (swagger) specification.

**Development documentation** can be found in [src/README.md](src/README.md).


## Key Features

* **Authentication:** Securely log in to your ReCodEx account. The CLI will securely store your access token for future sessions. The session is shared with the `recodex-pylib` library, so you can use it in conjunction with your Python scripts.
* **Execute Requests:** Send API requests and view responses from the command line.
* **Interactive Mode:** You can use the interactive mode to browse and use existing endpoints.
* **Plugins:** Use existing plugins or write your own to streamline your work.


## Installation

The most common way to install the ReCodEx CLI is via `pip`. Python 3.11 is recommended, but other versions may also work:

```bash
pip install recodex-cli
```

Note that this also installs the `recodex-pylib` library as a dependency.


### Installation from source code

For developers or those who prefer to install directly from the source code into local venv, follow these steps:

```bash
./bin/init.sh
source ./venv/bin/activate
```

Or you can install it globally (not recommended):

```bash
pip install -r requirements.txt
pip install -e .
```


## Getting Started

The CLI is invoked via either
```bash
python3 -m recodex_cli <command> [options]
```
or using the deployed script wrapper
```bash
recodex <command> [options]
```

Let us review basic operations:

- **Login:** You can login with your credentials or an API token.

    ```bash
    # login with credentials
    recodex login --username test@test.tld --password test --api-url http://your.recodex.domain/api
    
    # login with an API token (can be generated in webapp in user settings)
    recodex login --api-url http://your.recodex.domain/api --token eyJ...

    # login via an interactive prompt
    recodex login --prompt-credentials
    recodex login --prompt-token

    # logout
    recodex logout
    ```
    Let us note that the JWT token (either provided or obtained after credentials verification) is stored in a configuration file in your home directory (usually `~/.local/share/recodex/context.yaml`).

- **Explore Commands:** You can view the full list of available commands and options by running:

    ```bash
    recodex --help
    ```

## Usage

### Call Command

The client defines the `call` command, which can be used to call any endpoint.

- **Interactive Mode:** By calling the command without any arguments, an interactive query will start that will prompt you for what endpoint you want to call and its parameters.


    ```bash
    recodex call
    ```

- **Calling an Endpoint:** To call an endpoint, add an argument in the `presenter.action` format, followed by any request parameters.

    ```bash
    # use QUERY parameters in <name=value> format
    recodex call groups.default --query search=Demo

    # beware that some parameters must be encoded in JSON (the quotes must be backslashed so the bash won't remove them)
    recodex call users.default --filters={\"search\":\"Kloda\"}

    # you can pass a JSON or YAML file as a request body
    recodex call registration.create_invitation --body-path invite.yaml

    # PATH parameters are used in order of declaration (the first one is usually the ID)
    recodex call groups.set_organizational 10000000-2000-4000-8000-160000000000 --body '{"value":true}'
    ```

- **Help:** To print a detailed description on how to use the command, use:

    ```bash
    recodex call --help
    ```

    You can also view all parameters of a specific command.

    ```bash
    recodex call groups.default --help
    ```

### Plugins

The client can also be extended with plugins that can streamline common request patterns.

- **File Upload:**  Files can be uploaded simply by providing a path. Larger files will automatically be fragmented into chunks.

    ```bash
    recodex file upload test.csv 
    > File sent successfully
    > File ID: 73aac159-b2e2-402b-9e19-096f3ec0ae7c
    ```

- **File Download:** 
    ```bash
    recodex file download 73aac159-b2e2-402b-9e19-096f3ec0ae7c --out-path test.csv
    ```

- **Get Swagger:** This command returns the Swagger document (OpenAPI Specification) currently used by the client.

    ```bash
    recodex info swagger
    ```

## Examples

The following examples can be used as snippets to quickly perform common tasks (just replace parameters as needed).

### Group management

**Add a student to a group:**
```bash
recodex call groups.add_student <group-id> <user-id>
```

**Remove a student from a group:**
```bash
recodex call groups.remove_student <group-id> <user-id>
```

**Add a member (admin) to a group (this does not work for students):**
```bash
recodex call groups.add_member <group-id> <user-id> --body {\"type\":\"admin\"}
```