Command reference
This page documents every command of the Forge CLI. Examples
assume a forge command available in your PATH; if you run the CLI from the
repository, prefix them with uv run (e.g. uv run forge activities list).
Commands are grouped by topic. Every group and every command accepts --help:
forge --help
forge activities --help
forge activities submissions download-traces --help
Most commands take URIs as arguments.
forge --help lists a few more commands than this page does. The ones that are
missing here are reserved for the Forge team: they need elevated permissions
and are not meant to be used from the outside.
Global options
| Option | Description |
|---|---|
--version | Print the version of the CLI and exit. |
--help | Print the help of a command and exit. |
forge auth
forge auth token
Print a valid JWT on stdout, logging you in first if needed.
forge auth token
See Authentication for the login flow and for the caveats of using it inside a command substitution.
forge activities
Commands for the activities you manage. They all go through Operator, so you need the matching permissions on the tenant.
forge activities list
List the activities you have access to.
$ forge activities list
Found 2 activities
[my-tenant] 42sh - https://intra.forge.epita.fr/my-tenant/42sh/root
[my-tenant] Malloc - https://intra.forge.epita.fr/my-tenant/malloc/root
| Option | Description |
|---|---|
--json | Output the full activity objects as JSON. |
--csv | Output as CSV (uri,slug,tenantSlug,name,version,versionHash). |
--file <path> | Write the output to a file instead of stdout. |
forge activities groups list
List the groups of an activity, with their members and the URL of their intranet-hosted Git repository.
$ forge activities groups list my-tenant/42sh
Found 1 groups
[login_x] (<git remote url of the group>)
- login_x
| Option | Description |
|---|---|
--json | Output the full group objects as JSON. |
--file <path> | Write the output to a file instead of stdout. |
forge activities groups clone
Clone the repository of every group of an activity, in parallel, into a folder named after the activity slug.
forge activities groups clone my-tenant/42sh
| Option | Description |
|---|---|
--zip | Archive the folder as a .zip and delete it afterwards. |
This clones one repository per group. On a large activity, this is a lot of repositories and a lot of disk: run it in a dedicated directory.
forge activities submissions list
List the submission definition URIs of an activity. These are the URIs expected by the trace commands below.
$ forge activities submissions list my-tenant/42sh
Found 1 submissions
my-tenant/42sh/step-1/final
| Option | Description |
|---|---|
--json | Output as a JSON array. |
--csv | Output as CSV. |
--file <path> | Write the output to a file instead of stdout. |
forge activities submissions download-traces
Download one trace per group for a given submission definition. Traces are
written in a folder named after the submission definition URI (slashes replaced
by dashes), as <submission-id>.<group-slug>.xml.
forge activities submissions download-traces my-tenant/42sh/step-1/final
| Option | Default | Description |
|---|---|---|
--method <name> | BEST | How to pick the trace of a group, see below. |
--zip | Archive the folder as a .zip and delete it afterwards. |
Groups whose selected submission has no job (for example, a submission that never ran) are listed in a table and skipped.
The resulting file names follow the *.<login/groupSlug>.xml convention
expected by trace-to-grade.
forge activities submissions download-user-traces
Download the traces of a single group across every submission definition of an
activity. Files are written in a <activity-uri>-<group-slug> folder as
<submission-id>.<submission-definition-uri>.xml.
forge activities submissions download-user-traces my-tenant/42sh login_x
| Option | Default | Description |
|---|---|---|
--method <name> | BEST | How to pick the trace of a group, see below. |
--zip | Archive the folder as a .zip and delete it afterwards. |
Trace picking methods
Several commands have to choose one submission per group among all the ones
that were sent. The --method option controls that choice:
| Method | Behaviour |
|---|---|
BEST | Keep the submission with the highest success percentage. |
LAST | Keep the most recent submission that succeeded, falling back to the other one. |
forge activities get-notion-validation
Check, for each group, how many of the assignments that give points for a notion have been validated.
forge activities get-notion-validation my-tenant/42sh my-notion \
--csv_output notion.csv
| Option | Description |
|---|---|
--group_file <path> | File containing one group slug per line. Defaults to every group of the activity. |
--csv_output <path> | Write the report as CSV. |
--json_output <path> | Write the report as JSON. |
At least one of --csv_output and --json_output must be given. Each row
contains the group slug, a validated/required ratio and a boolean telling
whether the notion is fully validated.
forge submissions
Reporting and maintenance commands around student submissions.
forge submissions generate-report
Build a CSV matrix of the validated assignments of an activity: one row per
group, one column per assignment, 1 when the assignment is validated.
forge submissions generate-report my-tenant/42sh -o report.csv
| Option | Required | Description |
|---|---|---|
-o, --output-file | yes | CSV file to write into. |
forge submissions tags-report
Dump every submission of an activity to a CSV file, with the status, the reference that was pushed, the author and the current job of each one.
forge submissions tags-report my-tenant/42sh submissions.csv
forge submissions success-report
For a given assignment, write a CSV of the best success percentage obtained by each login. Only jobs that uploaded a result are taken into account.
forge submissions success-report my-tenant/42sh my-tenant/42sh/step-1 \
success.csv
forge submissions rerun
Rerun the moulinette on one submission per group for a submission definition. The CLI prints how many submissions it picked and asks for a confirmation before sending anything.
$ forge submissions rerun -s my-tenant/42sh/step-1/final
Found 120 submissions on my-tenant/42sh/step-1/final, picked 40.
Confirm to rerun 40 submissions for my-tenant/42sh/step-1/final on method LAST? [y/N]:
| Option | Default | Description |
|---|---|---|
-s, --submission-definition-uri | Required. Submission definition to rerun. | |
--method <name> | LAST | How to pick the submission of a group. |
Rerunning schedules one job per picked group on the test infrastructure. Do not run it on a whole promotion during a rush unless you know what you are doing.
forge submissions reaggregate
Re-send the aggregation of the latest submission of every group of an activity.
This rebuilds the validation state on the intranet when it has drifted, for
example after fixing an activity.yml.
forge submissions reaggregate -a my-tenant/42sh
forge skel
forge skel activity
Generate a minimal activity.yml and its .gitlab-ci.yml in an existing
directory, as a starting point for a new activity.
forge skel activity -o . -t my-tenant -s 42sh -m login_x -n "42sh"
| Option | Required | Description |
|---|---|---|
-o, --output-dir | yes | Existing directory to write the two files into. |
-s, --slug | yes | Slug of the activity. |
-t, --tenant | yes | Slug of the tenant owning the activity. |
-m, --manager | yes | Login of a manager. Repeat the option for several ones. |
-n, --name | no | Display name. Defaults to the slug. |
The generated activity opens immediately, closes in 30 days and contains a dummy assignment that you are expected to replace. See the activity reference for everything you can put in that file.
Existing activity.yml and .gitlab-ci.yml files in the output directory are
overwritten.