Usage#

The entry point for usage of cijoe is the command-line tool cijoe. Much like Ansible requires playbooks and inventories, make needs a Makefile, and GitHub Actions relies on workflows, then cijoe also requires input to function, these are:

For guidance on creating these files, refer to the Resources section. For the rest of the Usage section, and subsections, we will use the example script, workflow, and configuration file generated by running:

# Print a list of bundled usage examples
cijoe --example

The command above by default produces the example provided by the core cijoe package, however, as you can see in section Packages, then there are multiple packages and examples for using them are produced in the same manner:

  • cijoe --example qemu

  • cijoe --example linux

The following sections describe the use of Scripts, Workflows, the remainder of the current section provides subsections with information provided for reference on all CLI Arguments, Environment Variables, and behaverial information on Search Paths.

CLI Arguments#

When in doubt, then you can always consult the cijoe command-line arguments:

cijoe --help

Which yields the following output:

usage: cijoe [-h] [--config CONFIG] [--workflow WORKFLOW] [--output OUTPUT]
             [--log-level] [--monitor] [--no-report] [--skip-report]
             [--tag TAG] [--archive] [--produce-report] [--integrity-check]
             [--resources] [--example [EXAMPLE]] [--version]
             [step ...]

options:
  -h, --help            show this help message and exit

workflow:
  Run workflow at '-w', using config at '-c', and output at '-o'

  step                  Given a workflow; one or more workflow steps to run.
                        Else; one or more cijoe Python scripts to run.
                        (default: None)
  --config CONFIG, -c CONFIG
                        Path to the Configuration file. (default: cijoe-
                        config.toml)
  --workflow WORKFLOW, -w WORKFLOW
                        Path to workflow file. (default: cijoe-workflow.yaml)
  --output OUTPUT, -o OUTPUT
                        Path to output directory. (default: /cijoe/docs/cijoe-
                        output)
  --log-level, -l       Increase log-level. Provide '-l' for info and '-ll'
                        for debug. (default: None)
  --monitor, -m         Dump command output to stdout (default: False)
  --no-report, -n       Skip the producing, and opening, a report at the end
                        of the workflow-run (default: False)
  --skip-report, -s     Skip the report opening at the end of the workflow-run
                        (default: True)
  --tag TAG, -t TAG     Tags to identify a workflow-run. This will be prefixed
                        while storing in archive (default: None)

utilities:
  Workflow, and workflow-related utilities

  --archive, -a         Move the output at '-o / --output' to 'cijoe-
                        archive/YYYY-MM-DD_HH:MM:SS (default: False)
  --produce-report, -p  Produce report, and open it, for output at '-o /
                        --output' and exit. (default: None)
  --integrity-check, -i
                        Check integrity of workflow at '-w / --workflow' and
                        exit. (default: False)
  --resources, -r       List collected resources and exit. (default: False)
  --example [EXAMPLE], -e [EXAMPLE]
                        Emits the given example. When no example is given,
                        then it prints a list of available examples. (default:
                        None)
  --version, -v         Print the version number of 'cijoe' and exit.
                        (default: False)

Search Paths#

The CLI Arguments for the positional argument, and config-files (--c / --config) and workflows (-w / --workflow) by default search for files named cijoe-workflow.yaml and cijoe-config.toml, respectfully. These files are searched for, in order, in the following locations:

$PWD

In your current working directory

$PWD/.cijoe

In the subfolder named .cijoe of your current working directory

$HOME/.cijoe

In a subfolder of your home-directory named .cijoe

$HOME/.config/cijoe

In a subfolder of of the .config folder in your home-directory named cijoe

In addition to these search paths for the cijoe configuration file, then the environment variable named CIJOE_DEFAULT_CONFIG can be utilized to directly set the path to the configuration file instead providing it via the --config command-line option.

Environment Variables#

The following environment variables modify the bahavior of the cijoe command-line tool.

CIJOE_DISABLE_SSH_ENV_INJECT

When this is set, the environment variables passed to cijoe.run(..., env={your: vars}) will not be passed on to the SSH transport.

CIJOE_DEFAULT_CONFIG

When set, the value will be used as the default for the command-line -c/--config argument.

CIJOE_DEFAULT_WORKFLOW

When set, the value will be used as the default for the positional command-line argument.

Docker Image#

There is a cijoe Docker image available at GitHub, which contains everything needed to build, install and run cijoe. This includes all the tools required by the built-in packages of cijoe, for example Docker and QEMU.

A prebuilt cijoe Docker image is available at GitHub. This image provides a ready-to-use environment containing all necessary dependencies to build, install, and run cijoe. It includes tools required by built-in cijoe packages, such as Docker and QEMU.

Pulling the Docker Image#

To download the latest version of the cijoe Docker image, use:

docker pull ghcr.io/refenv/cijoe-docker:latest

For a specific version, replace latest with the desired tag, e.g.:

docker pull ghcr.io/refenv/cijoe-docker:v0.9.50

Using the latest tag ensures you get the newest available image, while using a specific version provides stability across runs.

GitHub Actions#

The following GitHub Actions workflow demonstrates how to use the cijoe Docker image to run the core.default example and upload the cijoe report as an artifact.

name: cijoe_example

on:
  workflow_dispatch:

jobs:
  run_cijoe_example:
    runs-on: ubuntu-22.04
    container:
      image: ghcr.io/refenv/cijoe-docker:latest

    steps:
    - name: Set up Python 3.12
      uses: actions/setup-python@v5.3.0
      with:
        python-version: "3.12"

    - name: Generate cijoe example
      run: |
        $(which cijoe) --example core.default
        mv ./cijoe-example-core.default ./example

    - name: Execute workflow
      run: |
        $(which cijoe) --monitor -l \
          --config ./example/cijoe-config.toml \
          --workflow ./example/cijoe-workflow.yaml

    - name: Upload report
      if: always()
      uses: actions/upload-artifact@v4.3.0
      with:
        name: report-cijoe_example
        path: cijoe-output/*
        if-no-files-found: error