Course Evaluation using CLI

Outcome You generate a table that links each Student Instance ID in a Space to the corresponding student's name and email, using the Nuvolos CLI from a terminal inside a Nuvolos Application - giving you a mapping you can match against assignment hand-ins for grading or evaluation.

Before you start

• Owner or Editor access to the course Space.

• A Nuvolos Application with terminal access (e.g., the Terminal Application).

• You know which course Space you want to generate the mapping for.

When grading or auditing assignment activity, you often need to connect a Student Instance ID - for example single_user_inst_1b114824 - back to the student who owns it. This guide shows how to generate that mapping yourself, using the Nuvolos CLI from a terminal inside a Nuvolos Application.

This is a self-serve workflow: once set up, you can rerun it at any point in the course - before each deadline, at the end of the term, or whenever your evaluation system needs a refresh.

Who this is for

Instructors and teaching assistants who need a list connecting each Student Instance in a course Space to the corresponding student's name, email, and role.

How it works

There is no single API call that returns the full mapping in one step. Instead, the process:

1. Lists every Instance in the Space, excluding the Master Instance.

2. For each Instance, lists its members and keeps only those explicitly added to that Instance - filtering out roles inherited from the Space or organization level.

3. Combines the results into a single table with name, email, status, role, and Instance ID.

The steps below automate this end to end.

1

Create an API key

1. Open your Nuvolos user profile and go to API access.

2. Create a new API key.

3. Start (or restart) a Nuvolos Application with terminal access inside the course Space, so the CLI operates on the correct set of Instances.

Tip: For a general walkthrough of key creation and CLI setup, see the CLI installation guide referenced at the end of this page.

2

Install the required tools

From the terminal, install jq (used to parse JSON output) and the Nuvolos CLI:

mamba install -c conda-forge --freeze-installed jq
pip install --upgrade nuvolos-cli

Using --upgrade ensures you always run the current CLI release rather than a version pinned to a specific point in time.

3

Generate the mapping

Run the following script. It loops through every non-master Instance in the Space, pulls the explicitly assigned members of each, and formats the result as a Markdown table.

for inst in $(nuvolos instances list -f json | jq -r '.[] | select(.slug != "master") | .slug'); do
  nuvolos instances members -i "$inst" -f json \
    | jq --arg inst "$inst" '.[] | select(.role_source == "EXPLICIT") + {instance: $inst}'
done | jq -r -s '
  ["name", "email", "active", "role", "role_source", "instance"],
  ["---", "---", "---", "---", "---", "---"],
  (.[] | [.name, .email, .active, .role, .role_source, .instance] | map(tostring))
  | "| " + join(" | ") + " |"
'

The output is a Markdown table:

name	email	active	role	role_source	instance
Jane Doe	[e-mail]	true	EDITOR	EXPLICIT	single_user_inst_1b114824

Saving or reformatting the output:

• > mapping.md - append this to the command above to save the result to a file instead of printing it to the terminal.

• Export as CSV - the final jq block can be adapted to comma-separated output, useful if your evaluation system expects CSV rather than Markdown.

Reading the results:

• Each row represents one student explicitly assigned to a Student Instance.

• The instance column is the Instance ID (or slug) you'll match against your assignment records.

• If a Student Instance shows more than one row, this is usually a teaching assistant or test account rather than a data error - the role column will typically make this clear.

Where to go next

• For creating a Nuvolos API key and installing the CLI, see CLI installation guide.

• For the full command reference, including options beyond what this page uses, see Using the CLI.

• For listing and filtering Instances or Instance members directly, see Listing Instances and Listing Instance members.

• For reviewing and exporting grades once hand-ins are matched to students, see Assignments, grading, and feedback.