> For the complete documentation index, see [llms.txt](https://docs.nuvolos.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nuvolos.com/reference/nuvolos-cli-and-python-api/grade-check-cli/gc-cli-technical-appendix.md). # GC CLI Technical appendix #### Module map


Piece	Location
CLI group / commands	nuvolos_cli/grade.py → nv_grade, nv_grade_check, …
Wired into root CLI	nuvolos_cli/interface.py (nuvolos.add_command(nv_grade))
Start / stop / execute / distribute	nuvolos_cli/api_client.py
Collect / handback library	external nuvolos_collect
Client SDK	nuvolos-client-api

#### Orchestrator: run\_grade\_check High-level steps: 1. Validate the environment (API key and teaching Master Instance). 2. Create a staging run directory under /files/.nuvolos\_grade/\. 3. Collect submissions (unless skipped), then relabel by student email. 4. Read the manifest and resolve students. 5. Process students sequentially, or via a thread pool executor. 6. For each student, run test\_one\_student. 7. Publish per-student artifacts into the handin/handback structure. 8. Batch handback via nuvolos\_collect.handback. 9. Print summary counts. (By design, there’s no central grade\_run\_\*.json file.) #### Per-student: test\_one\_student preflight list\_apps\ → start\_app\ → wait\_for\_app\_running\ → execute\_command\_in\_app(wrapped\_command)\ → wait for done-file / exit sentinel (GRADE\_EXEC\_TIMEOUT\_SECS)\ → pull\_student\_logs\_to\_instructor (distribute\_content: student → instructor)\ → stop\_app (finally) #### Command wrapping (completion protocol) Nuvolos’s default stdout capture is unreliable for multi-segment shell sequences and redirections, so Grade Check owns its own logging: mkdir -p "$work"\ {\ \\ } > output.log 2>&1\ ec=$?\ printf '%s' "$ec" > .cmd\_done\ : > .cmd\_exit.$ec\ exit "$ec" Completion is detected by polling the files API for .cmd\_done / .cmd\_exit.\

. These are pure shell markers, so detection works even without Python present in the image.

#### Log pull path

1. Confirm output.log exists on the student’s files area.
2. Optionally stage or copy it into the work directory on the student side.
3. Run distribute\_content from the student’s development snapshot to the instructor Instance.
4. Read the bytes on the instructor’s filesystem, keeping excerpts (up to roughly 5 MB) for terminal display.
5. Copy the files into handin/handback \_grading/ and set them to read-only.

#### Manifest item → Instance slug resolution

Resolution follows this priority order:

1. Parse .../handin/\/... from the item’s src.
2. Otherwise, use the basename of target.
3. Otherwise, raise an error.

#### Parallelism semantics

if parallel > 1 and not continue\_on\_error and not dry\_run:\
    force parallel = 1

Sequential mode stops early on the first failure, unless --continue-on-error is set. Parallel mode submits all runnable students and gathers the results as they complete; there’s no mid-pool cancellation.

#### Dependency note

pip install nuvolos-cli\
\
*# separately:*\
pip install git+

nuvolos\_collect is installed separately because git-URL extras can’t be published to PyPI, and its historical click pin has, at times, conflicted with the click version required by nuvolos-cli. If you hit an installation error related to click, check both packages’ current dependency constraints rather than assuming these exact version numbers still apply.

#### Related but separate: evaluation sessions

A nuvolos grade session-style flow — starting many Applications, holding them running, and bulk-stopping them later — is planned but not part of grade check. Don’t repurpose check’s defaults for long-running, interactive evaluation.