ReCodEx CLI Client

A command-line interface for the 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 Python library, which provides a wrapper for ReCodEx API generated from OpenAPI (swagger) specification.

Development documentation can be found in 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:

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:

./bin/init.sh
source ./venv/bin/activate

Or you can install it globally (not recommended):

pip install -r requirements.txt
pip install -e .

Getting Started

The CLI is invoked via either

python3 -m recodex_cli <command> [options]

or using the deployed script wrapper

recodex <command> [options]

Let us review basic operations:

• Login: You can login with your credentials or an API token.

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

  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.

  recodex call

• Calling an Endpoint: To call an endpoint, add an argument in the presenter.action format, followed by any request parameters.

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

  recodex call --help

  You can also view all parameters of a specific command.

  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.

  recodex file upload test.csv 
  > File sent successfully
  > File ID: 73aac159-b2e2-402b-9e19-096f3ec0ae7c

• File Download:

  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.

  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:

recodex call groups.add_student <group-id> <user-id>

Remove a student from a group:

recodex call groups.remove_student <group-id> <user-id>

Add a member (admin) to a group (this does not work for students):

recodex call groups.add_member <group-id> <user-id> --body {\"type\":\"admin\"}