Nitro CLI

CLI client for judge.nitro-ai.org.

Features

• login using Nitro's JSON API
• list contests with page controls
• list tasks for a contest
• view full task statements
• download task data files
• launch a past contest locally with Docker
• submit solutions and wait for feedback
• list submissions
• inspect submission feedback/details
• interactive shell mode when run without arguments

Requirements

• Python 3.10+
• no third-party Python package dependencies

Login

nitro-cli login posts to Nitro's /api/auth/login endpoint and stores the returned access and refresh tokens.

Behavior:

1. saves API tokens in the local CLI state file
2. refreshes an expired access token when a refresh token is available
3. asks you to log in again if the saved refresh token is no longer valid

Example:

nitro-cli login --username MihneaStoica

Installation

With pipx:

pipx install .

With pip:

python3 -m pip install .

For local development:

python3 -m pip install -e .

From PyPI:

pipx install nitro-ai-judge-cli

Usage

Direct commands:

nitro-cli login
nitro-cli contests
nitro-cli --api-url http://127.0.0.1:8080 contests
nitro-cli contests --page 2
nitro-cli contests --all-pages
nitro-cli tasks algolymp/algolymp-preojia-ix-x
nitro-cli task algolymp/algolymp-preojia-ix-x 1
nitro-cli download-data algolymp/algolymp-preojia-ix-x 1 --out-dir data
nitro-cli download-data algolymp/algolymp-preojia-ix-x 1 --category statement --output TASK.md
nitro-cli download-data algolymp/algolymp-preojia-ix-x 1 --category test_data --output test_data.zip
nitro-cli play algolymp/algolymp-preojia-ix-x
nitro-cli play algolymp/algolymp-preojia-ix-x --gpu --port 8890
nitro-cli play logs algolymp/algolymp-preojia-ix-x
nitro-cli play stop algolymp/algolymp-preojia-ix-x
nitro-cli play down algolymp/algolymp-preojia-ix-x
nitro-cli submissions algolymp/algolymp-preojia-ix-x 1 --mode both
nitro-cli submission 3a009d767bd5 --org algolymp --comp algolymp-preojia-ix-x --task-id 1
nitro-cli submit algolymp/algolymp-preojia-ix-x 1 --output submission.csv --source solution.py --wait

Custom backend:

NITRO_API_BASE_URL=http://127.0.0.1:8080 nitro-cli tasks algolymp/algolymp-preojia-ix-x
nitro-cli --api-url http://127.0.0.1:8080 tasks algolymp/algolymp-preojia-ix-x

API URL precedence is --api-url, then NITRO_API_BASE_URL, then PROXY_URL, then Nitro's hosted API.

Contestant Cloud submission proxy:

PROXY_URL=http://127.0.0.1:8080 nitro-cli tasks algolymp/algolymp-preojia-ix-x
PROXY_URL=http://127.0.0.1:8080 nitro-cli submit algolymp/algolymp-preojia-ix-x 1 --output submission.csv --source solution.py
nitro-cli --api-url http://127.0.0.1:8080 --submission-proxy submit algolymp/algolymp-preojia-ix-x 1 --output submission.csv --source solution.py

When PROXY_URL is set and neither --api-url nor NITRO_API_BASE_URL is set, nitro-cli uses it as the API URL and enables submission proxy mode automatically. --submission-proxy still forces proxy submission mode for an explicit --api-url.

Past-contest play:

nitro-cli play algolymp/algolymp-preojia-ix-x
nitro-cli play logs algolymp/algolymp-preojia-ix-x
nitro-cli play stop algolymp/algolymp-preojia-ix-x
nitro-cli play down algolymp/algolymp-preojia-ix-x

play requires Docker and docker compose. It stores generated Compose files under ~/.nitro-cli/contestant-cloud/<org>-<comp>/, creates the external nitro_net Docker network, and starts the contest notebook plus submission proxy.

Lifecycle commands:

• nitro-cli play <org>/<comp> writes the Compose files, pulls the Docker images, and starts Jupyter plus the submission proxy.
• nitro-cli play logs <org>/<comp> follows the Docker Compose logs for that contest.
• nitro-cli play stop <org>/<comp> stops the containers but keeps generated files and Docker volumes so the environment can be started again.
• nitro-cli play down <org>/<comp> stops the containers, removes volumes/orphans, and deletes the generated play files.

Interactive shell:

nitro-cli
PROXY_URL=http://127.0.0.1:8080 nitro-cli

Example shell session:

contest list
contest list --page 2
contest list --all-pages
select 20
play
play stop
tasks
select 1
show
task download-data --out-dir data
submit submission.csv solution.py --wait
submissions
submission 1

Shell commands:

help
exit | quit
back | unselect
login [username]
status
contests
contest list [--all] [--page N] [--page-size N] [--all-pages]
contest select <index|org/slug>
contest show
play [<org>/<comp>] [--gpu] [--port PORT]
play logs [<org>/<comp>]
play stop [<org>/<comp>]
play down [<org>/<comp>]
tasks
task list
task select <index|id>
select <index|id>
show
task download-data [--category CATEGORY ...] [--out-dir DIR] [--force]
submit <output.csv> [source.py] [--note TEXT] [--wait]
task show
task submit <output.csv> [source.py] [--note TEXT] [--wait]
submissions [--mode partial|complete|both]
task submissions list [--mode partial|complete|both]
submission <index|short-id|full-id>
submission view <index|short-id|full-id>
task submissions show <index|short-id|full-id>
set-final <index|short-id|full-id>
unset-final <index|short-id|full-id>

Notes:

• select is context-sensitive: at top level it selects a contest; inside a contest it selects a task.
• back / unselect clears the current task first, then the current contest.
• play uses the selected contest when no <org>/<comp> is given.

State

Login state is stored in:

~/.nitro-cli/state.json

Override with:

NITRO_STATE_DIR=/some/path nitro-cli login

Publishing

This repo includes a GitHub Actions workflow at .github/workflows/publish.yml.

Behavior:

1. Builds the package on pushes, pull requests, and manual runs
2. Runs twine check on built distributions
3. Publishes to PyPI when you push a tag matching v*

Recommended release flow:

python3 -m pip install --upgrade build twine
python3 -m build
python3 -m twine check dist/*
# bump version in pyproject.toml before tagging a new release
git tag v1.8.0
git push origin main --tags

PyPI does not allow re-uploading the same filename for an existing release. The workflow is configured to skip already-published files on reruns, but publishing a new release still requires a new version in pyproject.toml and a matching new tag.

For PyPI trusted publishing, configure PyPI to trust this GitHub repository and the pypi environment.

Package name on PyPI: nitro-ai-judge-cli Command name after install: nitro-cli

Before publishing publicly, choose and add a license file.