Divekit

Development Setup

Mon, 01 Jan 0001 00:00:00 +0000

This page intentionally stays short. The detailed development-setup workflow changes together with the CLI repository and is maintained there to avoid duplication.

Stable Summary

Clone divekit-cli
Use Go 1.24+
Build with make build
Run checks with make check
Use the CLI repo’s Local GitLab guide when local GitLab is required

Source of Truth

For the current step-by-step setup, use:

Error Handling

Mon, 01 Jan 0001 00:00:00 +0000

Divekit uses a centralized categorized error model built around internal/error (apperror), command middleware, and internal/shell/logging.

This page is now only a summary. The implementation-coupled source of truth lives in the CLI repository under docs/architecture/error-handling.md.

Stable Summary

commands should return typed errors, not format terminal output themselves
user messages and technical details should stay separate
exit codes are determined centrally
logging should go through the shared logging package
fallback behavior should be explicit and observable

For package paths, current examples, and maintainer-level guidance, use the CLI repository document.

Contributing Guidelines

Mon, 01 Jan 0001 00:00:00 +0000

This page keeps only the stable contribution expectations. The current contributor workflow is maintained in the CLI repository under CONTRIBUTING.md.

Stable Expectations

Make code changes in the CLI repository.
Update tests and documentation when behavior changes.
Run the relevant checks before opening a merge request.
Keep user-facing text in English.
Prefer consistency with existing command, handler, and error-handling patterns.

Source of Truth

Use the CLI repository for current details about:

config.json

Mon, 01 Jan 0001 00:00:00 +0000

config.json is the primary distribution configuration file used by divekit distribute, fetch, patch, overview, and related commands.

Default location:

.divekit/distributions/<distribution>/config.json

Current Stored Format

The current persisted format is a flat version: "2.0" document. Internally, Divekit still expands this into named targets such as work and eval.

{
 "version": "2.0",
 "remote": "gitnrw",
 "groupId": 12345,
 "members": {
 "path": "$DIVEKIT_MEMBERS/st2_members.json",
 "permissions": "developer"
 },
 "evaluationPipeline": {
 "enabled": true,
 "groupId": 67890
 },
 "snapshot": {
 "remote": "research",
 "groupId": 24680
 }
}

Keys

Key	Type	Notes
`version`	string	Current format version. Use `"2.0"`.
`remote`	string	Host alias from `~/.divekit/hosts.json`.
`groupId`	integer	Work target group ID.
`name`	string	Optional repository name template. When omitted, Divekit uses `{{distribution}}-{{uuid}}`.
`members`	object	Member source and default permissions.
`members.path`	string	Path to the `members.json` file. Supports `$DIVEKIT_MEMBERS/...` and relative paths resolved through the members base directory.
`members.permissions`	string	GitLab access level assigned to configured members, for example `guest`, `reporter`, `developer`, `maintainer`, or `owner`.
`evaluationPipeline`	object	Enables separated eval target handling.
`evaluationPipeline.enabled`	boolean	Enables the generated `eval` target and cross-repository setup.
`evaluationPipeline.groupId`	integer	Optional group ID for eval repositories.
`groupLayout`	object	Controls how student and eval groups are derived.
`groupLayout.mode`	string	Group-resolution strategy: `distribution-subgroups` (default) or `legacy`.
`groupLayout.rootGroupId`	integer	Optional root group ID used to derive distribution subgroups. Defaults to the work target’s `groupId`.
`snapshot`	object	Optional research snapshot target configuration.
`snapshot.remote`	string	Host alias from `~/.divekit/hosts.json` used for snapshot writes. Defaults to the work target remote.
`snapshot.groupId`	integer	Snapshot root group used by `divekit snapshot`. Interactive runs can store this after you choose a root group.
`deleteExistingRepositories`	boolean	Destructive reset option before distribution.
`scripting`	object	Language and file-extension mapping used by scripting and token tooling.
`scripting.languages`	array of strings	Enabled language packs. If omitted in auto mode, Divekit can discover languages.
`scripting.extensions`	object	Maps file patterns such as `*.java` to language packs.
`scripting.files`	object	File-specific mapping alias that is merged with `scripting.extensions`.
`scripting.mode`	string	Scripting mode. `auto` enables language discovery; object form may also use manual mappings.
`variables`	object	Global token delimiter and fixed values.
`variables.variableDelimiter`	string	Opening delimiter for tokens.
`variables.variableDelimiterEnd`	string	Optional closing delimiter when start and end should differ.
`variables.values`	object	Fixed token values available during distribution.

Repository Name Templates

The optional top-level name value is rendered once for each repository group. When omitted, Divekit uses {{distribution}}-{{uuid}}.

Hello there 👋

Mon, 01 Jan 0001 00:00:00 +0000

What is Divekit?

Divekit is a command-line tool for managing individualized programming assignments at scale. It helps educators create, distribute and evaluate programming exercises for large groups of students.

Visual overview: from origin to distributed repositories

Locally:

my-assignment/
├─ .divekit/
├─ src/$Vehicle$.java # placeholder - used by individualization
├─ tests_evalrepo/ # filter - excluded from work repos
└─ README.md

Gitlab: “Individualized repositories”:

gitlab.example.com/.../my-group/ # Work repositories (work target)
├─ my-assignment-4d2c0752-f400-4690-9bac-97c927e68e17/
│ ├─ src/Car.java # $Vehicle$ → Car
│ └─ README.md
├─ my-assignment-4d243142-292b-4b95-abbb-af13f102c857/
│ ├─ src/Bike.java # $Vehicle$ → Bike
│ └─ README.md
└─ my-assignment-8153ded6-ee91-4135-b59e-ace2625f83c3/
 ├─ src/Plane.java # $Vehicle$ → Plane
 └─ README.md

Gitlab: “Evaluation pipeline” (separate eval target)

How Divekit Works

Mon, 01 Jan 0001 00:00:00 +0000

Divekit turns one maintained course origin into individualized repositories and keeps the resulting distribution operable throughout an assignment. This page explains what is authored, what Divekit generates, and which boundaries need care before a real cohort is involved.

You can operate Divekit through its CLI or its web interface. Both use the same origin and distribution model.

From Origin To Results

flowchart LR
 MAINTAINER((Course maintainer))
 ORIGIN["Authored origin<br/>course files + .divekit/"]
 MEMBERS["Member input<br/>kept outside the origin"]
 DIVEKIT["Divekit<br/>CLI or web interface"]
 STATE["Generated distribution state<br/>individuals.json + remotes.json"]
 LOCAL["Local provider output"]
 WORK["GitLab work repositories"]
 STUDENT((Students))
 EVAL["GitLab eval repositories"]
 PLUGINS["Pinned plugin suites"]
 RESULTS["Plugin results<br/>reports + feedback"]

 MAINTAINER --> ORIGIN
 ORIGIN --> DIVEKIT
 MEMBERS --> DIVEKIT
 DIVEKIT --> STATE
 DIVEKIT --> LOCAL
 DIVEKIT --> WORK
 DIVEKIT --> EVAL
 STUDENT --> WORK
 WORK --> EVAL
 PLUGINS --> EVAL
 EVAL --> RESULTS
 RESULTS --> STUDENT
 RESULTS --> MAINTAINER

1. Author The Course Once

The origin repository is the maintained source for an assignment. It contains the course files and .divekit/ configuration that describe distribution, individualization, and optional evaluation behavior. Variation choices and individualization rules are authored inputs too.

Repository Name Templates

Mon, 01 Jan 0001 00:00:00 +0000

Repository names are configured with the optional top-level name key in a distribution’s config.json. Divekit renders the template once for every group in members.json. If name is omitted, the default is {{distribution}}-{{uuid}}.

{
 "name": "exercise-{{username}}"
}

Repository name templates use Go’s text/template syntax. This page documents the data and functions that Divekit provides for this specific use case.

Common Examples

Use the first configured GitLab username as the complete repository name:

Configuration Notes

Mon, 01 Jan 0001 00:00:00 +0000

The old config redesign draft was retired.

Use these pages for the current, supported model:

Scope of This Page

This page is intentionally short and only kept as a marker that the redesign draft is closed. Do not add new configuration behavior here; update the stable pages above instead.

Configuration Keys

Mon, 01 Jan 0001 00:00:00 +0000

This page summarizes the most relevant keys that users edit in current Divekit setups.

Distribution config.json

Key	Type	Notes
`version`	string	Use `"2.0"`.
`remote`	string	Host alias from `hosts.json`.
`groupId`	integer	Work distribution group ID.
`name`	string	Optional repository name template. If omitted, Divekit uses `{{distribution}}-{{uuid}}`.
`members.path`	string	Path to `members.json`.
`members.permissions`	string	Default permission level, usually `developer`.
`evaluationPipeline.enabled`	boolean	Enables the paired eval target.
`evaluationPipeline.groupId`	integer	Optional explicit eval root group.
`groupLayout.mode`	string	`distribution-subgroups` or `legacy`.
`groupLayout.rootGroupId`	integer	Optional explicit root group for derived subgroups.
`snapshot.remote`	string	Optional host alias used by `divekit snapshot` for writes. Defaults to the work target remote.
`snapshot.groupId`	integer	Optional snapshot root group used by `divekit snapshot`. Interactive runs can store this after you choose a root group.
`deleteExistingRepositories`	boolean	Deletes existing target repositories before distribution.
`scripting.languages`	array	Enabled languages for scripting/tooling.
`scripting.extensions`	object	File-pattern to language mapping.
`variables.variableDelimiter`	string	Start delimiter for token replacement.
`variables.variableDelimiterEnd`	string	Optional end delimiter.
`variables.values`	object	Fixed values shared across all UUIDs.

Notes:

Installation

Mon, 01 Jan 0001 00:00:00 +0000

Prerequisites

Before installing Divekit, ensure your system meets the following requirements:

System Requirements

Operating System: Linux, macOS, or Windows
GitLab: Access to a GitLab instance with API permissions

GitLab Setup

Access to a GitLab instance
An account that may create projects and manage members in the target group
A personal, project, or service-account access token with api scope

The api scope and the account’s GitLab role are independent. The token does not grant namespace permissions that its owner does not already have. A normal distribution does not require instance administrator access; the exact minimum group role depends on the group’s project-creation and member-management settings. See GitLab Permissions before configuring evaluation pipelines, Pages, cleanup, or subgroup creation.

members.json

Mon, 01 Jan 0001 00:00:00 +0000

members.json defines which UUIDs are distributed and which users receive access to each repository.

The file location is configured via config.json -> members.path.

The canonical member value is the GitLab username. Optional display-name metadata can preserve course-internal or local names without changing the username used for GitLab operations. Each entry in groups represents one distributed repository group.

Format

{
 "version": "2.0",
 "displayNames": {
 "myname_extern": "myname"
 },
 "groups": [
 {
 "uuid": "team-01",
 "label": "Team 01",
 "metadata": {
 "fruit": "banana"
 },
 "members": ["alice", "myname_extern"]
 },
 {
 "uuid": "team-02",
 "label": "Team 02",
 "members": ["charlie"],
 "unassignedMembers": ["dana"]
 }
 ]
}

Keys

Key	Type	Notes
`version`	string	Current format version. Use `"2.0"`.
`displayNames`	object	Optional map from GitLab username to local display name.
`groups`	array	One entry per distributed repository.
`groups[].uuid`	string	Stable identifier used in naming and state files.
`groups[].members`	array of strings	GitLab usernames that should receive access to that repository.
`groups[].unassignedMembers`	array of strings	Optional members that were known locally but could not be assigned.
`groups[].label`	string	Optional human-readable group label. Used by repository name templates such as `{{label}}` and `{{slug}}`.
`groups[].metadata`	object	Optional group-level string metadata. Used by repository name templates such as `{{metadata "fruit"}}` or `{{.Metadata.fruit}}`.

Import Input

Interactive input, text files, and stdin use one repository group per non-empty row. A row with one value creates a one-person group:

Example Origins

Mon, 01 Jan 0001 00:00:00 +0000

Example origins are small assignment repositories that show how authored source files and Divekit configuration work together. Use this guide to choose a starting point, inspect the repository it generates, and identify which parts you must adapt before a real course rollout.

The source repositories live in the public Divekit example origins group. They are not copied into this documentation site.

Choose an example

Example	Best for	Demonstrates
Vehicle Workshop Origin	Learning the smallest useful Divekit workflow	One individualization axis, local validation, and a work-repository distribution
Shape and Color Origin	Comparing your result after the beginner course’s final exercise	Two independent individualization axes and consistent replacement in one file
Example Shop Origin	Exploring a more complete Maven assignment	Multiple related individualizations, work and eval repositories, an Evaluation Pipeline, tests, and plugin configuration

Start with Vehicle Workshop when you want to understand the files in an origin repo and the effect of one placeholder. Use Shape and Color after completing the beginner course exercise and before moving to Example Shop’s paired work and eval setup.

First steps

Mon, 01 Jan 0001 00:00:00 +0000

Create Your First Project

Create and open a new directory:

mkdir my-assignment
cd my-assignment

Initialize Divekit:

divekit init

What `divekit init` does

divekit init creates the base configuration for an origin repository and prepares your project for distribution workflows.

Typical structure after init:

my-assignment/
└── .divekit/
 └── distributions/
 └── <distribution>/
 └── config.json

For command details, see divekit init.

variation.json and individualization.json are optional and can be added at project level (.divekit/) or distribution level (.divekit/distributions/<distribution>/). To scaffold a starter variation config, use divekit inject --scope variation.

GitLab Permissions

Mon, 01 Jan 0001 00:00:00 +0000

Divekit authenticates with a personal, project, or service-account access token. Two independent permission layers determine what the CLI can do:

the scopes attached to the token
the GitLab permissions of the account that owns the token

A broad token scope does not grant its owner additional access to groups or projects. A high group role cannot compensate for a token that lacks the needed API scope.

Token Scope

Current authentication and distribution workflows require the GitLab api scope. Divekit validates this scope during authentication. Additional read_api or write_repository scopes do not expand namespace access when api is already present.

Configuration Model

Mon, 01 Jan 0001 00:00:00 +0000

Divekit configuration is split across user-level and project-level files. This page explains the configuration model that course maintainers use. Detailed JSON schemas, keys, and fallback rules now live under Reference.

1. Configuration Layers

Divekit uses three practical layers:

User-level defaults in ~/.divekit/
Project-level defaults in <origin-repo>/.divekit/
Distribution-specific overrides in <origin-repo>/.divekit/distributions/<distribution>/

The CLI resolves files from the most specific layer outward. This keeps shared defaults reusable while still allowing per-distribution overrides.

2. User-Level Configuration

~/.divekit/ stores machine-wide settings:

Deployment

Mon, 01 Jan 0001 00:00:00 +0000

This page reflects the current release flow in the repository. Old deploy.sh examples and GIF-based demos are obsolete.

Release Trigger

Releases are tag-driven. A release starts when a Git tag is pushed (for example v2.3.1 or v2.4.0-rc.1).

Recommended Tag Creation

Use the helper script:

./scripts/dev/release-tag.sh

The script checks for a clean working tree, fetches tags, proposes version increments, and pushes v<version>.

Manual alternative:

git tag v2.3.1
git push origin v2.3.1

CI Pipeline Behavior

In .gitlab-ci.yml the release flow is:

divekit dev

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

Development helper for finding and fixing token issues.

Scans the current project for unresolved variation tokens and suggests values that should be added to variation.json. Essential for debugging individualization issues before distribution.

Detected Issues

Unresolved tokens (tokens without values in variation.json)
Possible variable residues from other variations
Missing token definitions
Template syntax issues like broken fragments or invalid placeholders (opt-in)
Suggested values based on context analysis

Scan Sources

 default Scan the current origin project
 --scan-latest Scan the latest output created by 'divekit distribute -p local'
 --scan-path Scan an explicit path; if it points into .divekit/local-data it is treated as local distribution output
 --group-id Restrict local distribution scans to one generated group

Usage

divekit dev [flags]

Examples

# Scan distribution for token issues
divekit dev -d ST2M4

# Watch mode for continuous development
divekit dev -d ST2M4 --watch

# Scan one generated local project or a local-data subtree
divekit dev -d ST2M4 --scan-path .divekit/local-data

# Scan the latest 'divekit distribute -p local' output for this distribution
divekit dev -d ST2M4 --scan-latest

# Restrict local distribution scanning to one generated group
divekit dev -d ST2M4 --scan-latest --group-id 8f9e52d-dcd5-44da-8bda-03ccb16a3b15

# Show only unresolved tokens
divekit dev -d ST2M4 --only-unresolved

# Show only value suggestions
divekit dev -d ST2M4 --only-suggestions

# Show only possible variable residues
divekit dev -d ST2M4 --only-residues

# Ignore generated assets in this run only
divekit dev -d ST2M4 --ignore-path '*.png,.idea/*'

# Restrict scan to selected file types
divekit dev -d ST2M4 --type-whitelist md,json,xml,java

# Export results to JSON
divekit dev -d ST2M4 --output results.json

# Scaffold missing variation objects into individualization.json
divekit dev -d ST2M4 --write-individualization

# Minimal output without context
divekit dev -d ST2M4 --no-context

# Scan for invalid placeholders and broken delimiter fragments
divekit dev -d ST2M4 --check-syntax

# Only run syntax-oriented checks
divekit dev -d ST2M4 --only-syntax

# Keep full terminal-clickable path:line links on every unresolved match line
divekit dev -d ST2M4 --terminal-links

# Show every unresolved match instead of collapsing with "... and N more"
divekit dev -d ST2M4 --show-all-matches

Flags

--check-syntax Detect invalid placeholders and broken delimiter fragments
 -d, --distribution string Distribution name (prompted if omitted)
 --group-id string Restrict local distribution scans to one generated group UUID
 --ignore-path strings Additional file/path ignore patterns for this run (repeatable or comma-separated)
 --no-context Disable context lines in console output
 --only-residues Show only possible variable residues in console output
 --only-suggestions Show only suggestions in console output
 --only-syntax Show only syntax checks (implies --check-syntax)
 --only-unresolved Show only unresolved tokens in console output
 --output string Write results JSON to this path (disabled by default)
 --scan-latest Scan the latest local distribution output created by 'divekit distribute -p local'
 --scan-path string Scan this path instead of the origin project; local-data paths are treated as local distribution output
 --show-all-matches Show every unresolved match instead of collapsing lists
 --terminal-links Repeat full path:line on each unresolved match line
 --type-whitelist strings Restrict scanned file extensions for this run (repeatable or comma-separated, without dots)
 --watch Watch files and rescan on changes
 --write-individualization Create or extend individualization.json from unresolved tokens

Inherited Flags

-l, --loglevel string log level (debug, info, warn, error, fatal) (default "info")
 --no-index skip project index update
 --non-interactive run in non-interactive mode (fails if interactive input is required)
 -y, --yes assume yes/default for all prompts (non-interactive with automatic defaults)

Individualization

Mon, 01 Jan 0001 00:00:00 +0000

Overview

Divekit individualizes repositories with three different files:

variation.json: defines available object, relation, and logic variants.
individualization.json (optional): defines replacement behavior and processing rules.
individuals.json (generated): stores the concrete selection per UUID.

Important: per-member or per-group selection is not configured via individualization.json keys like logicId, objectAssignments, or globalSettings. Those keys are outdated.

Configuration Files

`variation.json` (input)

Defines what can vary:

objects
relations
logic

Example:

{
 "objects": [
 {
 "ids": "Vehicle",
 "objectVariations": [
 { "id": "car", "type": "class", "name": "Car", "variables": { "Vehicle": "Car" } },
 { "id": "truck", "type": "class", "name": "Truck", "variables": { "Vehicle": "Truck" } }
 ]
 }
 ],
 "relations": [
 {
 "id": "ownership",
 "type": "association",
 "source": "Vehicle",
 "target": "Owner",
 "options": ["one-to-one", "one-to-many"],
 "variables": {}
 }
 ],
 "logic": [
 {
 "id": "algorithm",
 "type": "implementation",
 "location": "src/logic",
 "options": ["simple", "complex"],
 "variables": {}
 }
 ]
}

`individualization.json` (optional input)

Defines processing behavior. Current top-level keys are:

Paths and Locations

Mon, 01 Jan 0001 00:00:00 +0000

This page summarizes the default file locations and path resolution rules used by the current CLI.

User-Level Paths

~/.divekit/
├── .env
├── bin/
├── divekit.db
├── gui-runs/
├── hosts.json
├── install.json
├── members/
├── scripts/
│ └── run/
├── logs/
└── secrets/

Notes:

bin/ is the fallback managed binary installation directory (divekit or divekit.exe).
divekit.db stores central local SQLite state such as managed GUI authentication data.
gui-runs/ stores per-origin SQLite run state for queued and executed GUI actions.
hosts.json stores host aliases and secret/env lookup keys.
install.json tracks the managed install location and PATH integration for divekit uninstall.
members/ is the default base directory for members files.
scripts/run/ contains extensions resolved by divekit run <name>.
scripts/ also contains built-in hook helpers such as Java transformers.
secrets/ is a fallback storage area when no OS credential manager is available.

Project-Level Paths

<origin-repo>/.divekit/
├── variation.json
├── individualization.json
├── local-data/
│ └── <distribution>/
│ ├── local/
│ │ └── <run-id>/
│ │ ├── <target>/<project>/repo
│ │ └── remotes.json
│ ├── gitlab/
│ │ └── <timestamp>/
│ │ ├── work/<uuid>/repo
│ │ ├── artifacts/<uuid>/pages/export.json
│ │ └── remotes.json
│ └── runs/
│ └── <timestamp>/
├── eval-pipeline/
│ ├── work/
│ │ ├── .gitlab-ci.yml
│ │ └── .gitlab/
│ │ └── ci/
│ │ └── divekit/
│ │ └── eval-trigger.yml
│ ├── materialization.json
│ ├── plugins.json
│ └── eval/
│ ├── .gitlab-ci.yml
│ ├── .divekit/
│ │ └── plugins/
│ │ └── <suite>/
│ │ └── <plugin>/
│ │ └── <result.path>
│ └── .gitlab/
│ └── ci/
│ └── divekit/
│ └── plugins/ (flat pre-suite plugins only)
│ ├── <plugin-id>.yml
│ └── <plugin-id>/
│ └── feedback/
└── distributions/
 └── <distribution>/
 ├── config.json
 ├── feedback/
 │ ├── _all.json
 │ └── <uuid>.json
 ├── variation.json
 ├── individualization.json
 ├── individuals.json
 ├── remotes.json
 └── eval-pipeline/
 ├── work/
 │ ├── .gitlab-ci.yml
 │ └── .gitlab/
 │ └── ci/
 │ └── divekit/
 │ └── eval-trigger.yml
 ├── materialization.json
 ├── plugins.json
 └── eval/
 ├── .gitlab-ci.yml
 ├── .divekit/
 │ └── plugins/
 │ └── <suite>/
 │ └── <plugin>/
 │ └── <result.path>
 └── .gitlab/
 └── ci/
 └── divekit/
 └── plugins/ (flat pre-suite plugins only)
 ├── <plugin-id>.yml
 └── <plugin-id>/
 └── feedback/

Resolution Rules

individualization.json

.divekit/distributions/<distribution>/individualization.json
.divekit/individualization.json
~/.divekit/individualization.json
built-in defaults

Variation definitions

.divekit/distributions/<distribution>/individualization.json
.divekit/distributions/<distribution>/variation.json
.divekit/individualization.json
.divekit/variation.json
~/.divekit/individualization.json
built-in defaults with no variations

Omitting variations from a unified file continues this lookup. An explicitly empty variation section stops it. The obsolete ~/.divekit/templates/variation.json is no longer a runtime fallback; current versions remove an unchanged managed copy during install/update and preserve a customized copy with a warning.

variation.json

Mon, 01 Jan 0001 00:00:00 +0000

variation.json defines which content options Divekit may choose from during individualization.

This file is optional, but required if you want per-UUID variation selection.

Format

{
 "objects": [
 {
 "ids": "Vehicle",
 "objectVariations": [
 {
 "id": "car",
 "type": "class",
 "name": "Car",
 "variables": {
 "Vehicle": "Car"
 }
 },
 {
 "id": "truck",
 "type": "class",
 "name": "Truck",
 "variables": {
 "Vehicle": "Truck"
 }
 }
 ]
 }
 ],
 "relations": [
 {
 "id": "ownership",
 "type": "association",
 "source": "Vehicle",
 "target": "Owner",
 "options": ["one-to-one", "one-to-many"],
 "variables": {}
 }
 ],
 "logic": [
 {
 "id": "algorithm",
 "type": "implementation",
 "location": "src/logic",
 "options": ["simple", "complex"],
 "variables": {}
 }
 ]
}

Top-Level Sections

Key	Type	Notes
`objects`	array	Object-level choices keyed by `ids`.
`relations`	array	Relation-level choices keyed by `id`.
`logic`	array	Logic-level choices keyed by `id`.

Variation Fields and Token Overrides

Each object variation can contain more than just id, type, name, and variables.

Evaluation Pipeline

Mon, 01 Jan 0001 00:00:00 +0000

What It Is

Evaluation Pipeline is Divekit’s two-repository mode for a single assignment UUID:

work repository: student-facing code repository
eval repository: evaluation repository

When enabled, distribution creates and links both repositories for each UUID.

What It Does

For each UUID, Divekit:

Creates the work and eval repositories (depending on your target/group layout).
Individualizes content per UUID (same UUID mapping across targets).
Injects evaluation-pipeline CI assets.
Links both repositories by setting cross-repository variables and tokens.
Configures trigger/job-token scope so pipelines can communicate.
Disables GitLab’s unique Pages domain setting on eval repositories when the provider supports project-level Pages settings.

Runtime Flow

flowchart LR
 A["Student pushes to work repo"] --> B["work .gitlab-ci.yml"]
 B --> C["Trigger eval pipeline"]
 C --> D["eval pipeline prepares test env"]
 D --> E["eval runs build/tests/plugins"]
 E --> F["reports/artifacts"]

Work-To-Eval Materialization

Student edits happen in the work repository, while tests and hidden evaluation material live in the eval repository. The repositories are separate. Distribution creates their initial contents, but enabling Evaluation Pipeline does not define how later student changes replace or merge into the eval checkout. When the eval pipeline starts, Divekit runs its internal eval setup, fetches the current work repository state, and applies .divekit/materialization.json in the eval repository.

Plugins

Mon, 01 Jan 0001 00:00:00 +0000

This page documents the flat plugin model of pre-suite origins. New courses enable a plugin suite instead; existing origins migrate to it.

What Plugins Do

Evaluation Pipeline plugins add optional CI modules to eval repositories. Typical examples are PMD, Surefire, or JaCoCo/PIT analysis plugins.

Each plugin has two main controls:

add (alias use): choose the source or project, optionally pin a ref, and enable the plugin
enable or disable: toggle whether the plugin runs after it has been configured

Use pin when you only want to change the Git ref for an already configured plugin.

Manual Feedback

Mon, 01 Jan 0001 00:00:00 +0000

Manual feedback lets course staff add direct notes to generated evaluation reports without changing plugin output. It is meant for human feedback such as “try extracting this into a helper” or “this applies to everyone in this milestone”.

Unlike plugin feedback, manual feedback is authored in the origin repository and then patched into generated eval repositories. The report renders it as a separate teaching-team thread, above generic plugin feedback.

Author Feedback

Use the interactive command when selecting a distribution or members manually:

Plugin Suites

Mon, 01 Jan 0001 00:00:00 +0000

Available from divekit v2.45.0; per-plugin wizards run from the suite since v2.47.0. Earlier releases use the flat plugin model documented in the command pages.

What A Suite Is

A plugin suite bundles one build ecosystem and everything that analyzes its output. The maven suite ships the build stage of the evaluation pipeline (the job and the container image that compiles a student project) together with the analysis plugins that run against that build: PMD, Surefire, JaCoCo/PIT. A gradle suite does the same for Gradle projects, and the custom suite is the generic fallback for courses that build something else.

Migrate To Plugin Suites

Mon, 01 Jan 0001 00:00:00 +0000

Available from divekit v2.45.0; earlier releases use the flat plugin model documented in the command pages.

Who Needs This

Origins that were set up before plugin suites list their plugins by a flat name such as pmd or jacoco-pit, without a suite in front of it. Those origins have to be converted once. An origin created with a current Divekit is already on the new model and needs nothing.

Distribution

Mon, 01 Jan 0001 00:00:00 +0000

Overview

divekit distribute creates individualized repositories from an existing distribution config. In a typical run it:

reads .divekit/distributions/<name>/config.json
creates repositories in the configured target group(s)
individualizes content for each UUID
assigns members and permissions
writes state files: remotes.json and individuals.json

If the evaluation pipeline is enabled, Divekit also creates the linked eval repositories.

Prerequisites

divekit init is a one-time setup step and does not need to be repeated before every distribution.

Environment Variables

Mon, 01 Jan 0001 00:00:00 +0000

This page lists the environment variables that are relevant in normal Divekit CLI usage.

User and Configuration Variables

Variable	Purpose
`DIVEKIT_HOME`	Overrides the base location used for `~/.divekit`-style user data resolution.
`DIVEKIT_MEMBERS`	Base directory used for `members.path` resolution when paths use `$DIVEKIT_MEMBERS/...`.
`DIVEKIT_API_TOKEN`	Default token key used by host entries when no host-specific token key is derived.
`DIVEKIT_API_TOKEN_<HOST>`	Derived host-specific token key, for example `DIVEKIT_API_TOKEN_GITLAB`.

Interaction Mode Variables

These are typically set by CLI flags, but they can also be set explicitly:

individualization.json

Mon, 01 Jan 0001 00:00:00 +0000

individualization.json controls advanced processing behavior for variable replacement, solution deletion, warnings, file handling, artifact processors, and compatibility variation settings.

This file is optional. If it is missing, Divekit falls back to built-in defaults.

Minimal Example

{
 "variables": {
 "variableDelimiter": "$"
 }
}

Common Example

{
 "variables": {
 "variableDelimiter": "$",
 "values": {
 "semester": "SS2026"
 }
 },
 "solutionDeletion": {
 "enabled": true,
 "files": ["src/main/java/Solution.java"]
 },
 "warnings": {
 "enabled": true,
 "ignore": ["*.tmp"],
 "variationResidues": {
 "typeWhiteList": ["java", "md"],
 "ignoreList": ["UUID"],
 "matchMode": "word",
 "ignoreRules": [
 {
 "paths": ["src/test/java/**"],
 "values": ["Dish"]
 },
 {
 "values": ["Dish|Meal"],
 "matchMode": "regex"
 }
 ]
 }
 },
 "processors": {
 "uml": {
 "mode": "both",
 "imageFormat": "jpg"
 },
 "tableHash": {
 "solutionTableFileName": "${id}.solution.md",
 "hashedSolutionTableFileName": "${id}.hashed.md",
 "tableConfigFileName": "${id}.config.json"
 }
 }
}

Top-Level Keys

Key	Type	Notes
`variables`	object	Token delimiters and fixed values.
`solutionDeletion`	object	Files, directories, and markers used to remove solution content.
`warnings`	object	Validation and unresolved-token warning behavior.
`fileManipulation`	object	Target-specific file naming conventions such as `_workrepo`.
`processors`	object	Built-in artifact processors such as UML source/image generation.
`relations`	object	Object-relation metadata.
`variableExtensions`	object	Prefix, suffix, and transformation maps.
`variations`	object	Unified compatibility container for variation data.
`objectVariations`	array	Legacy flattened object variations.
`relationVariations`	array	Legacy flattened relation variations.
`logicVariations`	array	Legacy flattened logic variations.

`variables`

This section controls token delimiters and fixed token values.

Authoring Guide

Mon, 01 Jan 0001 00:00:00 +0000

Authoring contracts are still experimental and may evolve.

This page is now only a stable pointer.

Source of Truth

Plugin authoring and CI conventions should be maintained in the plugin template repository:

divekit/plugins/divekit-plugin-template

That repository should define:

repository layout: manifest.json, job.yaml, Dockerfile, code under src/
the plugin image, derived from the suite’s build image
optional reusable feedback assets under feedback/
release-template usage
plugin artifact-writing conventions
FAQ artifact conventions
copyable examples for new plugin repositories

Stable Summary

A plugin is one repository inside its suite’s GitLab group, named after the plugin id. Every plugin repository provides:

Configuration Wizards

Mon, 01 Jan 0001 00:00:00 +0000

Plugins can expose their own CLI configuration flow with a declarative wizard. The plugin repository keeps the questions and the JSON shape its job reads; Divekit CLI provides the terminal UI and writes the result where the plugin job finds it.

The intended workflow for a course maintainer is:

divekit plugin add maven
divekit plugin configure maven

divekit plugin configure <suite> runs the wizards of the suite’s enabled plugins in one session, in plugin order; divekit plugin configure <suite>/<plugin> runs one of them. Divekit reads each wizard at the plugin release the course has locked, so the questions always match the plugin version that evaluates the answers. A plugin without a wizard simply contributes no questions.

Contract Reference

Mon, 01 Jan 0001 00:00:00 +0000

Use this as the current contract baseline for new plugins.

This page is now a short summary of the CLI-consumed plugin contract. The implementation-coupled source of truth belongs in the Divekit CLI repository.

Stable Summary

Plugins are organized in plugin suites. A suite owns one build ecosystem and its build stage (maven, gradle, the generic custom suite); a plugin is one analysis inside a suite. On GitLab a suite is a group under divekit/plugins/, its builder repository is the coordinator, and every plugin is one repository next to it. The CLI currently expects the following:

Troubleshooting

Mon, 01 Jan 0001 00:00:00 +0000

This page stays as a quick maintainer-facing checklist. Detailed contract and authoring rules live elsewhere.

Discovery Fails

Check:

divekit plugin source list
divekit plugin discover --verbose

Verify:

the source is configured and trusted
the suite’s builder repository exposes manifest.json with "kind": "plugin-suite" on its default branch
the plugin repository exposes manifest.json with "kind": "plugin" and is pinned in the suite manifest
the pinned range matches a published tag, and that tag has an image in the plugin’s container registry

Plugin Does Not Run

Check:

Member Aliases

Mon, 01 Jan 0001 00:00:00 +0000

Member aliases are useful when a local members file contains course-internal names, but the corresponding GitLab accounts use different usernames.

Keep GitLab usernames in groups[].members. Divekit uses those values for GitLab access, repository membership, distribute, patch, members list, overview, and the GUI. The optional displayNames map only controls how those members are shown locally.

Set an Alias

If a member currently appears as myname in members.json, but the GitLab username is myname_extern, set the alias before rerunning distribution:

Plugin Configuration JSON

Mon, 01 Jan 0001 00:00:00 +0000

Plugin configuration files are owned by individual Evaluation Pipeline plugins. Divekit writes them when a plugin declares a configuration wizard and a user runs divekit plugin configure <suite> for all plugins of a suite or divekit plugin configure <suite>/<plugin> for one of them.

The exact keys belong to the plugin. Divekit only controls where the file is stored, how wizard fields are converted to JSON, and optional result metadata such as schemaVersion.

Run Extensions

Mon, 01 Jan 0001 00:00:00 +0000

divekit run executes local extensions against repositories from a distribution. Typical uses are static analysis, report extraction, custom checks, or orchestration around external tools.

Before running an extension, make repositories available locally:

divekit fetch -d ST2M4

Then run an extension from .divekit/scripts/run/ or by path:

divekit run analyze.lua -d ST2M4
divekit run ./scripts/analyze.py -d ST2M4

Use --fetch-first when Divekit should fetch before executing:

divekit run analyze.lua -d ST2M4 --fetch-first

Simple Lua Extensions

A simple Lua extension returns a function. Divekit calls that function once for every selected repository.

Safe Rollout Checklist

Mon, 01 Jan 0001 00:00:00 +0000

Use this checklist before the first rollout to a real cohort and before a later patch that sends new content to student repositories. After completing it, you should have private repositories for the intended students, with only the required access and without an accidental copy of the cohort member list.

Before distribution

Confirm that groupId and any evaluation target point to the intended GitLab groups. Use a separate non-production group for the rehearsal.
Run the complete workflow once with a small members file containing only synthetic test accounts controlled by the course team. The --count option does not assign users, so it does not test access control.
Confirm that the target namespace permits private projects. For any existing or reused project, check its effective project visibility in GitLab. A private project inside a public group remains private, so inspect the project rather than inferring its visibility from the parent group.
Store the real members file outside the origin repo. Check that it is not tracked by Git and is not among the files that distribution can copy. DIVEKIT_MEMBERS can point Divekit at a dedicated members directory outside the origin repo.
Authenticate with divekit auth. Keep tokens out of the origin repo, committed configuration, shell history, and ordinary environment files. Prefer Divekit’s credential-store integration or a protected CI secret. Grant the token owner only the GitLab permissions required for this rollout.

The relevant distribution settings are described in the config.json reference. GitLab documents how project visibility affects who can see repository content.

divekit doctor

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

Diagnose potential issues with your Divekit CLI setup and configuration.

Runs a series of checks to verify that Divekit is properly configured and all dependencies are available. Use this command to troubleshoot issues or verify your setup after installation.

Checks Performed

Configuration file validity
GitLab authentication and token validity
Distribution configuration integrity
Required system dependencies
Network connectivity to configured hosts

Usage

divekit doctor [flags]

Examples

# Run all checks and display results
divekit doctor

# Run checks with detailed output
divekit doctor --verbose

# Strict mode for CI/CD pipelines
divekit doctor --strict

Flags

--output-format string Output format: table|json (default "table")
 --strict Return non-zero exit code if any check fails
 -v, --verbose Show additional details for successful checks

Inherited Flags

-l, --loglevel string log level (debug, info, warn, error, fatal) (default "info")
 --no-index skip project index update
 --non-interactive run in non-interactive mode (fails if interactive input is required)
 -y, --yes assume yes/default for all prompts (non-interactive with automatic defaults)

Glossary

Mon, 01 Jan 0001 00:00:00 +0000

This glossary defines core Divekit terms used across Quick Start, Reference, and CLI docs.

Term	Definition
Divekit	Command-line tool for creating, distributing, and operating individualized programming assignments.
CLI	Command Line Interface. The primary way to use Divekit (`divekit ...`).
Personal Access Token	GitLab token used by Divekit to call the GitLab API for operations such as creating groups, repositories, and memberships.
Divekit Home Directory	User-level Divekit directory, usually `~/.divekit`, for local configuration, generated state, and fallback storage.
Origin Repository	Source repository containing assignment template files and `.divekit` configuration.
Distribution	Named setup in `.divekit/distributions/<name>/` that controls one rollout.
Distribution Config	`.divekit/distributions/<name>/config.json`, the main runtime config for distribution commands.
Target	Logical repository target in a distribution (for example `work` or `eval`).
Work Target	Student-facing code repository target (`work`).
Eval Target	Evaluation-pipeline repository target (`eval`) used for separated CI and evaluation flows.
Evaluation Pipeline	Optional paired `work`/`eval` model for separated CI and evaluation workflows. See Evaluation Pipeline.
Linking	Automatic connection between paired targets (variables/tokens/trigger URLs, job-token scope, UUID pairing).
Member	GitLab user account assigned to a distributed repository with a configured permission level.
Members File	JSON file referenced by `members.path`. It contains `groups`; each group has a stable `uuid` and the GitLab usernames that should receive access to that repository.
Members Directory	Base directory used to resolve members files. It is configured with `DIVEKIT_MEMBERS` and defaults to `~/.divekit/members`.
Group Label	Optional human-readable label on a members group. It can be used in repository name templates with `{{label}}` or as a GitLab-safe `{{slug}}`.
Group Metadata	Optional key/value metadata on a members group. It can be imported from member tables and used in repository name templates with `{{metadata "key"}}`.
UUID	Stable unique identifier used for one student/group repository pair across targets.
Individualization	Process of generating per-UUID content variants during distribution.
Variation Config	`variation.json` containing selectable object/relation/logic options.
Individualization Config	`individualization.json` containing delimiter, solution-deletion, warnings, file-manipulation and related rules.
Individuals File	`individuals.json`, generated state of concrete selections per UUID.
Remotes File	`remotes.json`, generated mapping of UUIDs to created remote repositories/project IDs.
Placeholder / Variable	Token in template files (for example $Vehicle$ ) replaced during individualization.
Host Alias	Named host entry in `~/.divekit/hosts.json` used by distribution targets (`remote`).
Provider	Backend used for execution, for example `gitlab`, `local`, or `simulated`.
Dry Run	Preview mode without remote changes (`--dry-run`, often via simulated provider).
Add Mode	`divekit distribute --add`: only process new UUIDs/members, keep existing distributed repos.
Fresh Mode	`divekit distribute --fresh`: rebuild distribution state files (`remotes.json`, `individuals.json`) while preserving stable repository indexes.
Fetch Snapshot	Timestamped GitLab repository snapshot under `.divekit/local-data/<distribution>/gitlab/<timestamp>/`, populated by `divekit fetch` or `divekit run --fetch-first` and reused by `run`/analysis commands.
Research Snapshot	History-stripped GitLab copy created by `divekit snapshot`. It contains the repository tree from distributed work repositories as one neutral initial commit, but it does not scrub UUIDs, names, paths, or file contents.
Local Provider Output	Filesystem distribution output under `.divekit/local-data/<distribution>/local/<run-id>/`, created by `divekit distribute -p local`.
Extension	A program executed across fetched or pulled repositories, typically via `divekit run`. Named run extensions live under `.divekit/scripts/run/`.
Run Workflow	Lifecycle extension form for `divekit run`. Lua workflows register `dk.run.prepare`, `dk.run.each`, and/or `dk.run.cleanup`; external workflow directories contain `workflow.json` and runtime functions such as `prepare`, `each`, and `cleanup`.
Plugin	CI plugin switch in evaluation-pipeline templates, executed in the eval pipeline and managed as described in Plugins.
Variable Extensions	`individualization.json -> variableExtensions`: token transformation rules (prefixes/suffixes/transformations). Not the same as runtime script extensions.
Inject	`divekit inject` command to scaffold default assets (CI templates, variation template, scripts).
Group Layout	Strategy for deriving work/eval groups (`distribution-subgroups` or `legacy`).

State Files

Mon, 01 Jan 0001 00:00:00 +0000

Divekit writes distribution state into the distribution directory. These files are generated and updated by commands such as distribute, fetch, patch, overview, and passcheck.

Default location:

.divekit/distributions/<distribution>/

individuals.json

individuals.json stores the concrete per-UUID variation selection that was actually used during distribution.

{
 "version": "2.0",
 "individuals": [
 {
 "uuid": "team-01",
 "selection": {
 "objects": {
 "Vehicle": "car"
 },
 "relations": {
 "ownership": "one-to-many"
 },
 "logic": {
 "algorithm": "simple"
 }
 }
 }
 ]
}

Use this file to inspect what was assigned. Do not treat it as the source of possible options; that belongs in variation.json.

materialization.json

Mon, 01 Jan 0001 00:00:00 +0000

materialization.json tells an Evaluation Pipeline run which files or directories from the work repository should be copied into the eval repository before tests and plugins run.

There are three related locations:

Location	Kind	Purpose
`.divekit/eval-pipeline/materialization.json`	Authoring config	Optional origin-side rules read during distribution or patching.
`.divekit/distributions/<distribution>/eval-pipeline/materialization.json`	Authoring config	Optional distribution-specific rules.
`.divekit/materialization.json`	Generated runtime manifest	Written into generated `eval` repositories and applied by the eval setup job.

For most projects, prefer the path-marker form described below. Use explicit JSON rules when the source and target paths should differ or when the source path should be optional. If all rules come from path markers, no authoring materialization.json file is needed.

hosts.json

Mon, 01 Jan 0001 00:00:00 +0000

hosts.json stores named remote host entries used by remote fields in distribution config.

Default location:

~/.divekit/hosts.json

Recommended management command:

divekit auth

Format

{
 "version": "1.0",
 "hosts": {
 "gitnrw": {
 "host": "https://gitlab.git.nrw/",
 "tokenAt": "DIVEKIT_API_TOKEN",
 "maxWorkers": 8,
 "rateLimitDelayMs": 250,
 "enableConcurrency": true
 }
 }
}

Keys

Key	Type	Notes
`version`	string	Current format version. Use `"1.0"`.
`hosts`	object	Map of host alias to host definition.
`hosts.<alias>.host`	string	Base URL of the GitLab or Git provider instance.
`hosts.<alias>.tokenAt`	string	Key name used to resolve the stored token.
`hosts.<alias>.maxWorkers`	integer	Optional per-host concurrency limit.
`hosts.<alias>.rateLimitDelayMs`	integer	Optional delay between requests in milliseconds.
`hosts.<alias>.enableConcurrency`	boolean	Optional concurrency toggle for that host.

Security Notes

hosts.json stores metadata and token references, not raw token values.
Divekit prefers the OS credential manager for actual token storage and falls back only when no keychain/keyring integration is available.
divekit auth unset <host> removes the configured host and deletes the stored token entry.

divekit fetch

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

Download distributed repositories to a local cache for offline access.

Fetches all or selected repositories from a distribution into a local cache directory. Cached repositories can then be used by other commands like ‘run’ or ‘passcheck’ without requiring network access.

WHAT HAPPENS:

Reads distribution config and remotes.json
Connects to GitLab and syncs repositories via git clone/pull
Downloads additional artifacts (currently pages/export.json)
Stores data in .divekit/distributions/<distribution>/.cache/

Usage

divekit fetch [flags]

Examples

# Fetch all repositories for a distribution
divekit fetch -d ST2M4

# Fetch only specific repositories by UUID
divekit fetch -d ST2M4 --uuid abc123 --uuid def456

# Fetch repositories for specific users
divekit fetch -d ST2M4 --user alice --user bob

# Fetch only specific file types
divekit fetch -d ST2M4 --files "*.java" --files "*.md"

# Preview what would be downloaded
divekit fetch -d ST2M4 --dry-run

# Control download concurrency
divekit fetch -d ST2M4 --workers 3 --rate-limit 5

# Fetch to a custom directory
divekit fetch -d ST2M4 --output-dir ./repos

Flags

-d, --distribution string Distribution name
 -n, --dry-run Show what would be downloaded without downloading
 --files strings Specific files to download (glob patterns)
 -o, --output-dir string Custom output directory (default: use local-data GitLab store)
 --rate-limit float Maximum downloads per second (0 = unlimited)
 -r, --remote string Remote repository URL (e.g. GitLab instance)
 --task-timeout duration Maximum time per download task (0 = use preset)
 -t, --token string GitLab token or token file path (file:///...)
 --user strings Only fetch repositories for these usernames (repeatable)
 --uuid strings Only fetch repositories with these UUIDs (repeatable)
 -w, --workers int Number of concurrent downloads (0 = use preset)

Inherited Flags

-l, --loglevel string log level (debug, info, warn, error, fatal) (default "info")
 --no-index skip project index update
 --non-interactive run in non-interactive mode (fails if interactive input is required)
 -y, --yes assume yes/default for all prompts (non-interactive with automatic defaults)

divekit gui

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

Start the Divekit graphical interface.

This command is experimental and may still change.

By default, this starts local single-user mode on this computer without login. Use –mode managed for authenticated server operation. Managed mode binds to 127.0.0.1 unless –host is set explicitly.

Usage

divekit gui [flags]

Examples

# Start local single-user mode
divekit gui

# Start managed server mode on the local interface
divekit gui --mode managed

# Expose managed mode on all interfaces, for example behind a TLS reverse proxy
divekit gui --mode managed --host 0.0.0.0

Flags

--assets-dir string GUI assets directory override (default: embedded web/gui/dist assets in binary) (default "auto")
 --auth-config string Persisted GUI server auth database path
 --auth-subject string Subject name for generated admin credentials (default "server-admin")
 --auth-token string Static bearer token for managed mode
 --auth-token-env string Environment variable containing the static bearer token (default "DIVEKIT_SERVER_TOKEN")
 --host string GUI server host (default: 127.0.0.1)
 --mode string GUI startup mode: local|managed (default: local)
 --open-browser Open browser automatically after startup (default: true in local mode, false in managed mode)
 --port int GUI server port (default 8787)
 --reset-auth Replace persisted managed-mode auth database and print a newly generated admin token
 --setup-auth Create persisted managed-mode auth database when missing and print the admin token

Inherited Flags

-l, --loglevel string log level (debug, info, warn, error, fatal) (default "info")
 --no-index skip project index update
 --non-interactive run in non-interactive mode (fails if interactive input is required)
 -y, --yes assume yes/default for all prompts (non-interactive with automatic defaults)

divekit init

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

Initialize a new Divekit origin repository in the current directory.

Creates the required .divekit directory structure and configuration files needed for managing distributions. This is typically the first command you run when setting up a new Divekit project.

Created Structure

 .divekit/
 distributions/ Distribution configurations
 &lt;name&gt;/
 config.json Distribution settings

Optional Files

.divekit/variation.json
.divekit/individualization.json
.divekit/eval-pipeline/materialization.json Work-to-eval rules

Usage

divekit init [flags]

Examples

# Initialize with interactive prompts
divekit init

# Initialize with defaults (no prompts)
divekit init --non-interactive

Inherited Flags

-l, --loglevel string log level (debug, info, warn, error, fatal) (default "info")
 --no-index skip project index update
 --non-interactive run in non-interactive mode (fails if interactive input is required)
 -y, --yes assume yes/default for all prompts (non-interactive with automatic defaults)

divekit feedback add

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

Add manual feedback for one distribution member

Usage

divekit feedback add [flags]

Examples

divekit feedback add -d ST2M4 --member 5c8fc911-c4da-44be-b76d-c6d2d1c9e1f1 --message "Try extracting this into a helper function."
divekit feedback add -d ST2M4 --all --message "Remember to explain your design choices."
divekit feedback add -d ST2M4 --member 5c8fc911-c4da-44be-b76d-c6d2d1c9e1f1 --message-file feedback/note.md

Flags

--all Author feedback for all members in the distribution
 -d, --distribution string Distribution name
 --id string Feedback item id (default: generated)
 --member stringArray Distribution member UUID (or configured member alias; repeatable or comma-separated)
 --message string Feedback message to render in the report page
 --message-file string Read feedback message from a Markdown file
 --user stringArray Alias for --member

Inherited Flags

-l, --loglevel string log level (debug, info, warn, error, fatal) (default "info")
 --no-index skip project index update
 --non-interactive run in non-interactive mode (fails if interactive input is required)
 -y, --yes assume yes/default for all prompts (non-interactive with automatic defaults)

Parent Command

divekit feedback

divekit index add

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

Add a Divekit project to the local index for fast discovery.

Registers a project path in the index database so it can be found by the search command. If no path is provided, the current directory is used.

Usage

divekit index add [path] [flags]

Examples

# Add current directory to index
divekit index add

# Add a specific project by path
divekit index add /path/to/project

# Find and add all projects recursively
divekit index add --recursive

# Find sibling projects (go up one dir, scan siblings)
divekit index add --siblings

# Combine: go up one dir, then search recursively
divekit index add --siblings --recursive

Flags

--recursive Search recursively in subdirectories
 --siblings Go up one directory and find all sibling projects

Inherited Flags

-l, --loglevel string log level (debug, info, warn, error, fatal) (default "info")
 --no-index skip project index update
 --non-interactive run in non-interactive mode (fails if interactive input is required)
 -y, --yes assume yes/default for all prompts (non-interactive with automatic defaults)

Parent Command

divekit index

divekit members add

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

Add members to a distribution before creating or updating repositories.

The command writes a new members file with new users appended, preserves UUIDs for existing groups, and updates the distribution config to point at the new file.

Input Sources

 Interactive (default):
 Opens the multiline member input prompt when no arguments, --members-file,
 or stdin input are provided.

 Arguments:
 Provide one or more usernames as positional arguments.

 File:
 Use --members-file to read usernames to add from a file.

 Stdin:
 Pipe usernames into the command.

Usage

divekit members add [member...] [flags]

Examples

# Add two users to the next distribution
divekit members add -d ST2M5 alice bob

# Add users listed in a file
divekit members add -d ST2M5 --members-file additional-members.txt

# Preview additions without changing config.json or members files
divekit members add -d ST2M5 --members-file additional-members.txt --dry-run

Flags

--dry-run Preview added members without writing a new members file
 --members-file string Path to a file with member names to add (one per line)

Inherited Flags

-d, --distribution string Distribution name (required or prompted)
 -l, --loglevel string log level (debug, info, warn, error, fatal) (default "info")
 --no-index skip project index update
 --non-interactive run in non-interactive mode (fails if interactive input is required)
 -y, --yes assume yes/default for all prompts (non-interactive with automatic defaults)

Parent Command

divekit members

divekit plugin add

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

Add or update one plugin and enable it for the evaluation pipeline

Usage

divekit plugin add <plugin> [flags]

Flags

--host string Host alias from 'divekit config hosts list' when using --project
 --project string Plugin project path (for direct custom plugin setup)
 --ref string Optional ref to pin while adding the plugin
 --source string Advanced: source name from 'divekit plugin source list'

Inherited Flags

-d, --distribution string Target distribution override (default: project-level eval overrides and .divekit state)
 -l, --loglevel string log level (debug, info, warn, error, fatal) (default "info")
 --no-index skip project index update
 --non-interactive run in non-interactive mode (fails if interactive input is required)
 -y, --yes assume yes/default for all prompts (non-interactive with automatic defaults)

Parent Command

divekit plugin

divekit patch ci

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

Apply the authored work/eval CI and evaluation-pipeline runtime files to distributed repositories.

This command collects existing files from .divekit/eval-pipeline and delegates to the regular patch workflow.

Usage

divekit patch ci [flags]

Examples

divekit patch ci -d ST2M4
divekit patch ci -d ST2M4 --dry-run

Flags

-d, --distribution string Distribution name
 -n, --dry-run string[="true"] Preview changes without applying (alias for --provider simulated)
 -m, --message string Commit message for the CI patch
 -p, --provider string Provider to use: gitlab (default), local (filesystem), simulated (dry-run)
 -r, --remote string Remote repository URL (e.g. GitLab instance)
 -t, --token string GitLab token or token file path (file:///...)

Inherited Flags

-l, --loglevel string log level (debug, info, warn, error, fatal) (default "info")
 --no-index skip project index update
 --non-interactive run in non-interactive mode (fails if interactive input is required)
 -y, --yes assume yes/default for all prompts (non-interactive with automatic defaults)

Parent Command

divekit patch

divekit config explain

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

Display documentation for Divekit configuration options.

Shows available configuration keys, their types, and descriptions. Without a topic, displays an overview of all configuration areas.

Topics

 origin Distribution configuration
 - remote, groupId, targetGroupPath
 - members, scripting options
 - evaluationPipeline settings

 hosts Authentication host configuration
 - url, token, tokenKey
 - concurrency settings (maxWorkers, rateLimitDelayMs)

Usage

divekit config explain [topic] [flags]

Examples

# Show configuration overview
divekit config explain

# Show origin configuration keys
divekit config explain origin

# Show hosts configuration keys
divekit config explain hosts

Flags

-d, --dist string distribution to resolve for the effective topic

Inherited Flags

-l, --loglevel string log level (debug, info, warn, error, fatal) (default "info")
 --no-index skip project index update
 --non-interactive run in non-interactive mode (fails if interactive input is required)
 -y, --yes assume yes/default for all prompts (non-interactive with automatic defaults)

Parent Command

divekit config

divekit run init

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

Create a workflow extension in .divekit/scripts/run/.

Lua workflows are generated as .divekit/scripts/run/<name>.lua. Other languages are generated as workflow folders under .divekit/scripts/run/<name>/. If name or language are omitted, Divekit prompts for them. Existing files are not overwritten unless –force is used or overwrite is confirmed interactively.

Usage

divekit run init [name] [flags]

Examples

divekit run init
divekit run init has_readme --language lua
divekit run init used_ai --language javascript --runner bun

Flags

--force Overwrite generated files if they already exist
 --language string Workflow language: lua|shell|python|javascript|typescript|go|java|kotlin
 --runner string Optional JavaScript or TypeScript runner, for example node|bun|deno

Inherited Flags

-l, --loglevel string log level (debug, info, warn, error, fatal) (default "info")
 --no-index skip project index update
 --non-interactive run in non-interactive mode (fails if interactive input is required)
 -y, --yes assume yes/default for all prompts (non-interactive with automatic defaults)

Parent Command

divekit run

divekit inject

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

Copy Divekit default assets into the project.

Injects pre-configured templates and default files into your Divekit project. Useful for setting up evaluation pipelines, default variation configurations, or Lua transformation scripts.

Available Scopes

 ci GitLab CI configuration for evaluation pipelines
 → .divekit/eval-pipeline/{work,eval}/.gitlab-ci.yml

 variation Small example variation.json
 → .divekit/variation.json (or distribution path)

 scripts Lua transformation scripts for Java
 → .divekit/scripts/java/*.lua

 all All of the above

Usage

divekit inject [flags]

Examples

# Interactive asset selection
divekit inject

# Inject CI configuration for evaluation pipelines
divekit inject --scope ci

# Inject a variation example
divekit inject --scope variation

# Inject Lua transformation scripts
divekit inject --scope scripts

# Inject everything
divekit inject --scope all

# Inject into a specific distribution
divekit inject --scope variation -d ST2M4

# Force overwrite existing files
divekit inject --scope ci --force

Flags

-d, --distribution string Write to distribution overrides (name); default writes to project-level .divekit/eval-pipeline state
 --force Overwrite existing files
 --scope string Comma-separated scopes: ci,variation,scripts,all; 'scripts' covers Lua transformers

Inherited Flags

-l, --loglevel string log level (debug, info, warn, error, fatal) (default "info")
 --no-index skip project index update
 --non-interactive run in non-interactive mode (fails if interactive input is required)
 -y, --yes assume yes/default for all prompts (non-interactive with automatic defaults)

divekit distribute recover-project-checkpoint

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

Acknowledge one project create only when the journal records an exact observed-success identity. The command rereads that recorded provider identity with the configured read-only provider before writing the local mapping. Missing, changed, deleted, or unavailable provider evidence leaves the mapping untouched; the operation remains recovery_required for review of other boundaries.

Usage

divekit distribute recover-project-checkpoint [flags]

Flags

--distribution string Optional distribution name to verify against the journal
 --operation-id string Exact operation ID from the journal
 --origin string Origin directory containing the operation journal (default ".")
 --provider string Optional provider name to verify against the journal
 --step-id string Exact project step ID from the journal

Inherited Flags

-l, --loglevel string log level (debug, info, warn, error, fatal) (default "info")
 --no-index skip project index update
 --non-interactive run in non-interactive mode (fails if interactive input is required)
 -y, --yes assume yes/default for all prompts (non-interactive with automatic defaults)

Parent Command

divekit distribute

divekit auth register

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

Interactively register a new GitLab instance.

Guides you through entering the hostname, URL, and authentication token for a new GitLab instance. The token is stored in the system keychain; without a working keychain, saving it fails unless plaintext storage is allowed with DIVEKIT_ALLOW_PLAINTEXT_SECRETS=1.

Usage

divekit auth register [flags]

Examples

divekit auth register

# Same command under the name other CLIs use
divekit auth login

Inherited Flags

-l, --loglevel string log level (debug, info, warn, error, fatal) (default "info")
 --no-index skip project index update
 --non-interactive run in non-interactive mode (fails if interactive input is required)
 -y, --yes assume yes/default for all prompts (non-interactive with automatic defaults)

Parent Command

divekit auth

divekit plugin configure

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

Run the configuration wizards of a suite’s plugins.

Each plugin declares its own wizard, read at the release the course locked. ‘configure <suite>’ runs the wizards of every enabled plugin in one session, ‘configure <suite>/<plugin>’ one of them; each writes its JSON below .divekit/plugins/<suite>/<plugin>/ in the evaluation-pipeline authoring area of this project or distribution, with existing values pre-filled. A plain plugin id runs the wizard of a flat pre-suite plugin.

divekit feedback copy

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

Copy manual feedback from one member to other members

Usage

divekit feedback copy <source-member> [flags]

Examples

divekit feedback copy -d ST2M4 5c8fc911-c4da-44be-b76d-c6d2d1c9e1f1 --member a70decaf-bad7-4c95-b211-d0bc95f48204
divekit feedback copy -d ST2M4 5c8fc911-c4da-44be-b76d-c6d2d1c9e1f1 --id feedback-20260601T100000Z --member a70decaf-bad7-4c95-b211-d0bc95f48204

Flags

-d, --distribution string Distribution name
 --id string Copy only one feedback item id
 --member stringArray Distribution member UUID (or configured member alias; repeatable or comma-separated)
 --user stringArray Alias for --member

Inherited Flags

-l, --loglevel string log level (debug, info, warn, error, fatal) (default "info")
 --no-index skip project index update
 --non-interactive run in non-interactive mode (fails if interactive input is required)
 -y, --yes assume yes/default for all prompts (non-interactive with automatic defaults)

Parent Command

divekit feedback

divekit patch feedback

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

Apply locally authored manual feedback to evaluation repositories.

Use ‘divekit feedback add’ first to author feedback in the origin repository. Without –member or –user, all authored feedback is patched.

Usage

divekit patch feedback [flags]

Examples

divekit feedback add -d ST2M4 --member 5c8fc911-c4da-44be-b76d-c6d2d1c9e1f1 --message "Try extracting this into a helper function."
divekit patch feedback -d ST2M4
divekit patch feedback -d ST2M4 --member 5c8fc911-c4da-44be-b76d-c6d2d1c9e1f1 --dry-run

Flags

--all Patch all authored feedback (default when no --member or --user is given)
 -d, --distribution string Distribution name
 -n, --dry-run string[="true"] Preview changes without applying (alias for --provider simulated)
 --member stringArray Member UUIDs whose eval repositories should receive feedback (or configured member aliases; repeatable or comma-separated)
 -m, --message string Commit message for the feedback patch
 -p, --provider string Provider to use: gitlab (default), local (filesystem), simulated (dry-run)
 -r, --remote string Remote repository URL (e.g. GitLab instance)
 -t, --token string GitLab token or token file path (file:///...)
 --user stringArray Alias for --member

Inherited Flags

-l, --loglevel string log level (debug, info, warn, error, fatal) (default "info")
 --no-index skip project index update
 --non-interactive run in non-interactive mode (fails if interactive input is required)
 -y, --yes assume yes/default for all prompts (non-interactive with automatic defaults)

Parent Command

divekit patch

divekit install

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

Install divekit into a managed user-level bin directory for easy access from any directory.

By default, Divekit prefers ~/.local/bin on Unix when that directory already exists or is already part of your PATH. Otherwise it falls back to ~/.divekit/bin. On Windows, Divekit installs into %USERPROFILE%.divekit\bin\divekit.exe.

Set DIVEKIT_INSTALL_DIR to override the install directory when needed.

Usage

divekit install [flags]

Examples

# Install divekit into the preferred managed user bin directory
divekit install

# Non-interactive installation
divekit install --non-interactive

Inherited Flags

-l, --loglevel string log level (debug, info, warn, error, fatal) (default "info")
 --no-index skip project index update
 --non-interactive run in non-interactive mode (fails if interactive input is required)
 -y, --yes assume yes/default for all prompts (non-interactive with automatic defaults)

divekit index refresh

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

Refresh the project index by validating all entries.

Iterates through all indexed projects and:

Verifies that each project path still exists
Checks that each path is a valid Divekit project
Updates the list of distributions for valid projects
Removes invalid or deleted projects from the index

Usage

divekit index refresh [flags]

Examples

# Refresh the entire project index
divekit index refresh

# Refresh without interactive prompts
divekit index refresh --non-interactive

Inherited Flags

-l, --loglevel string log level (debug, info, warn, error, fatal) (default "info")
 --no-index skip project index update
 --non-interactive run in non-interactive mode (fails if interactive input is required)
 -y, --yes assume yes/default for all prompts (non-interactive with automatic defaults)

Parent Command

divekit index

divekit auth unset

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

Remove a configured GitLab instance and its stored token.

If no hostname is provided, you will be prompted to select from configured instances.

Usage

divekit auth unset [hostname] [flags]

Examples

# Remove interactively (select from list)
divekit auth unset

# Remove a specific instance
divekit auth unset gitnrw

Inherited Flags

-l, --loglevel string log level (debug, info, warn, error, fatal) (default "info")
 --no-index skip project index update
 --non-interactive run in non-interactive mode (fails if interactive input is required)
 -y, --yes assume yes/default for all prompts (non-interactive with automatic defaults)

Parent Command

divekit auth

divekit plugin disable

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

Disable a configured plugin in the evaluation pipeline

Usage

divekit plugin disable [plugin] [flags]

Flags

--all Disable all configured plugins

Inherited Flags

-d, --distribution string Target distribution override (default: project-level eval overrides and .divekit state)
 -l, --loglevel string log level (debug, info, warn, error, fatal) (default "info")
 --no-index skip project index update
 --non-interactive run in non-interactive mode (fails if interactive input is required)
 -y, --yes assume yes/default for all prompts (non-interactive with automatic defaults)

Parent Command

divekit plugin

divekit members exclude

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

Exclude configured members from a distribution before creating repositories.

The command writes a new members file with the excluded users removed, preserves UUIDs for all remaining groups, drops empty groups, and updates the distribution config to point at the new file.

Input Sources

 Arguments:
 Provide one or more usernames as positional arguments.

 File:
 Use --members-file to read usernames to exclude from a file.

 Stdin:
 Pipe usernames into the command.

Usage

divekit members exclude [member...] [flags]

Examples

# Exclude two users from the next distribution
divekit members exclude -d ST2M4 alice bob

# Exclude users listed in a file
divekit members exclude -d ST2M4 --members-file excluded.txt

# Preview exclusions without changing config.json or members files
divekit members exclude -d ST2M4 --members-file excluded.txt --dry-run

Flags

--dry-run Preview excluded members without writing a new members file
 --members-file string Path to a file with member names to exclude (one per line)
 -r, --remote string Remote repository URL (e.g. GitLab instance)
 -t, --token string GitLab token or token file path (file:///...)

Inherited Flags

-d, --distribution string Distribution name (required or prompted)
 -l, --loglevel string log level (debug, info, warn, error, fatal) (default "info")
 --no-index skip project index update
 --non-interactive run in non-interactive mode (fails if interactive input is required)
 -y, --yes assume yes/default for all prompts (non-interactive with automatic defaults)

Parent Command

divekit members

divekit patch files

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

Apply file updates and explicit file operations to all repositories in a distribution.

This is the explicit form of the legacy file patch command:

divekit patch files README.md

The legacy shorthand remains available:

divekit patch README.md

Usage

divekit patch files [file1] [file2...] [flags]

Flags

--delete stringArray Delete a repository-relative file path from distributed repositories (repeatable)
 --delete-dir stringArray Delete all files below a repository-relative directory path from distributed repositories (repeatable)
 --disable-eval-pages-unique-domain Disable unique GitLab Pages domains for eval repositories
 -d, --distribution string Distribution name
 -n, --dry-run string[="true"] Preview changes without applying (alias for --provider simulated)
 --force Force writing patch files even when remote content already matches
 -m, --message string Commit message for the patch
 --move stringArray Move a repository-relative file path using old/path:new/path (repeatable)
 -p, --provider string Provider to use: gitlab (default), local (filesystem), simulated (dry-run)
 --rate-limit float Maximum tasks per second (0 = unlimited)
 -r, --remote string Remote repository URL (e.g. GitLab instance)
 --task-timeout duration Maximum time per task (0 = use preset)
 -t, --token string GitLab token or token file path (file:///...)
 --warn-unresolved-tokens string Warn about unresolved tokens: auto|true|false (default "auto")
 -w, --workers int Number of concurrent workers (0 = use preset)

Inherited Flags

-l, --loglevel string log level (debug, info, warn, error, fatal) (default "info")
 --no-index skip project index update
 --non-interactive run in non-interactive mode (fails if interactive input is required)
 -y, --yes assume yes/default for all prompts (non-interactive with automatic defaults)

Parent Command

divekit patch

divekit feedback list

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

List locally authored manual feedback

Usage

divekit feedback list [flags]

Flags

--all List feedback authored for all members
 -d, --distribution string Distribution name
 --member stringArray Distribution member UUID (or configured member alias; repeatable or comma-separated)
 --user stringArray Alias for --member

Inherited Flags

-l, --loglevel string log level (debug, info, warn, error, fatal) (default "info")
 --no-index skip project index update
 --non-interactive run in non-interactive mode (fails if interactive input is required)
 -y, --yes assume yes/default for all prompts (non-interactive with automatic defaults)

Parent Command

divekit feedback

divekit plugin discover

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

Advanced: discover available plugins from trusted sources.

Most users do not need this command. Use ‘divekit plugin add <plugin>’ for the normal workflow, and only use discovery when you need to browse or resolve plugins from non-default sources.

Usage

divekit plugin discover [flags]

Flags

--source string Only discover plugins from one source name
 --verbose Show detailed discover output

Inherited Flags

-d, --distribution string Target distribution override (default: project-level eval overrides and .divekit state)
 -l, --loglevel string log level (debug, info, warn, error, fatal) (default "info")
 --no-index skip project index update
 --non-interactive run in non-interactive mode (fails if interactive input is required)
 -y, --yes assume yes/default for all prompts (non-interactive with automatic defaults)

Parent Command

divekit plugin

divekit members filter

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

Filter members in a distribution before creating or updating repositories.

Use –include to keep only listed users. Use –exclude to remove listed users. The aliases retain, keep, and intersect use –include semantics.

Input Sources

 Interactive (default):
 Opens the multiline member input prompt when no arguments, --members-file,
 or stdin input are provided.

 Arguments:
 Provide one or more usernames as positional arguments.

 File:
 Use --members-file to read usernames from a file.

 Stdin:
 Pipe usernames into the command.

Usage

divekit members filter [member...] [flags]

Examples

# Keep only users listed in a file
divekit members filter -d ST2M5 --include --members-file passed-members.txt

# Equivalent include aliases
divekit members keep -d ST2M5 --members-file passed-members.txt
divekit members retain -d ST2M5 --members-file passed-members.txt

# Remove listed users
divekit members filter -d ST2M5 --exclude --members-file skipped-members.txt

# Preview filtering without changing config.json or members files
divekit members filter -d ST2M5 --include --members-file passed-members.txt --dry-run

Flags

--dry-run Preview filtered members without writing a new members file
 --exclude Remove listed members
 --include Keep only listed members
 --members-file string Path to a file with member names to filter (one per line)
 -r, --remote string Remote repository URL (e.g. GitLab instance)
 -t, --token string GitLab token or token file path (file:///...)

Inherited Flags

-d, --distribution string Distribution name (required or prompted)
 -l, --loglevel string log level (debug, info, warn, error, fatal) (default "info")
 --no-index skip project index update
 --non-interactive run in non-interactive mode (fails if interactive input is required)
 -y, --yes assume yes/default for all prompts (non-interactive with automatic defaults)

Parent Command

divekit members

divekit patch name

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

Reconcile provider-side repository names and URL paths for an existing distribution.

The expected repository name is derived from the distribution config.json field “name” or the default “{{distribution}}-{{uuid}}”. When URL paths change, Divekit also refreshes remotes.json, cross-repository variables, and files that contain PagesURL/pagesUrl tokens.

Usage

divekit patch name [flags]

Flags

--apply Apply the planned changes
 -d, --distribution string Distribution name
 -r, --remote string Remote repository URL (e.g. GitLab instance)
 --scope string Metadata scope to update: name, path, both
 -t, --token string GitLab token or token file path (file:///...)

Inherited Flags

-l, --loglevel string log level (debug, info, warn, error, fatal) (default "info")
 --no-index skip project index update
 --non-interactive run in non-interactive mode (fails if interactive input is required)
 -y, --yes assume yes/default for all prompts (non-interactive with automatic defaults)

Parent Command

divekit patch

divekit overview

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

Display a comprehensive overview of distributed repositories.

Shows information about all repositories in a distribution including UUIDs, target URLs, assigned users, and current status. Can display as a table in the terminal or open the GUI focused on the selected distribution.

Information Displayed

Repository UUID and name
Target URL on GitLab
Assigned members
Repository status and activity

Usage

divekit overview [flags]

Examples

# Show overview for a distribution
divekit overview -d ST2M4

# Fetch fresh data (bypass cache)
divekit overview -d ST2M4 --no-cache

# Open the GUI focused on this distribution
divekit overview -d ST2M4 --serve

# Control API concurrency
divekit overview -d ST2M4 --workers 5

Flags

-d, --distribution string Distribution name
 --no-cache Ignore cached members file and fetch fresh data from API
 --output-format string Output format: table|json (default "table")
 --rate-limit-delay duration Delay between per-UUID API requests (0 = default)
 -r, --remote string Remote repository URL (e.g. GitLab instance)
 -s, --serve Open the GUI focused on this distribution
 -t, --token string GitLab token or token file path (file:///...)
 -w, --workers int Number of concurrent API workers (0 = default)

Inherited Flags

-l, --loglevel string log level (debug, info, warn, error, fatal) (default "info")
 --no-index skip project index update
 --non-interactive run in non-interactive mode (fails if interactive input is required)
 -y, --yes assume yes/default for all prompts (non-interactive with automatic defaults)

divekit feedback remove

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

Remove one manual feedback item

Usage

divekit feedback remove <id> [flags]

Flags

--all Remove feedback authored for all members
 -d, --distribution string Distribution name
 --member stringArray Distribution member UUID (or configured member alias; repeatable or comma-separated)
 --user stringArray Alias for --member

Inherited Flags

-l, --loglevel string log level (debug, info, warn, error, fatal) (default "info")
 --no-index skip project index update
 --non-interactive run in non-interactive mode (fails if interactive input is required)
 -y, --yes assume yes/default for all prompts (non-interactive with automatic defaults)

Parent Command

divekit feedback

divekit plugin enable

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

Enable a configured plugin in the evaluation pipeline

Usage

divekit plugin enable <plugin> [flags]

Inherited Flags

-d, --distribution string Target distribution override (default: project-level eval overrides and .divekit state)
 -l, --loglevel string log level (debug, info, warn, error, fatal) (default "info")
 --no-index skip project index update
 --non-interactive run in non-interactive mode (fails if interactive input is required)
 -y, --yes assume yes/default for all prompts (non-interactive with automatic defaults)

Parent Command

divekit plugin

divekit members list

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

Show configured members and their current GitLab roles

Usage

divekit members list [flags]

Flags

--offline Show configured members without checking GitLab roles
 -r, --remote string Remote repository URL (e.g. GitLab instance)
 -t, --token string GitLab token or token file path (file:///...)

Inherited Flags

-d, --distribution string Distribution name (required or prompted)
 -l, --loglevel string log level (debug, info, warn, error, fatal) (default "info")
 --no-index skip project index update
 --non-interactive run in non-interactive mode (fails if interactive input is required)
 -y, --yes assume yes/default for all prompts (non-interactive with automatic defaults)

Parent Command

divekit members

divekit passcheck

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

Check and aggregate test results from evaluation pipeline repositories.

Connects to GitLab and retrieves test results from evaluation pipeline repositories. Provides an overview of passed/failed tests across all students and can generate detailed reports in various formats.

Requirements

Distribution must have an evaluation pipeline enabled
Evaluation repositories must be configured in the distribution
Valid GitLab authentication

Report Formats

 excel Microsoft Excel spreadsheet (.xlsx)
 csv Comma-separated values (.csv)
 html HTML report with styling
 md Markdown table format

Usage

divekit passcheck [flags]

Examples

# Check test results for a distribution
divekit passcheck -d ST2M4

# Show detailed results per student
divekit passcheck -d ST2M4 --detail

# Generate all report formats
divekit passcheck -d ST2M4 --report

# Generate specific report formats
divekit passcheck -d ST2M4 --report --report-format excel,csv

# Default report output path
divekit passcheck -d ST2M4 --report
# -> .divekit/local-data/reports/ST2M4/<timestamp>/

# Save reports to custom directory
divekit passcheck -d ST2M4 --report --output-dir ./results/

Flags

--detail Show detailed test results per student
 -d, --distribution string Distribution name (auto-detect if not provided)
 --output-dir string Output directory for generated reports (default: .divekit/local-data/reports/<distribution>/<timestamp>/)
 -r, --remote string Remote repository URL (GitLab instance)
 --report Generate report files (xlsx, csv, html, md)
 --report-format strings Report formats: excel,csv,html,md (default: all when --report is set)
 -t, --token string GitLab token

Inherited Flags

-l, --loglevel string log level (debug, info, warn, error, fatal) (default "info")
 --no-index skip project index update
 --non-interactive run in non-interactive mode (fails if interactive input is required)
 -y, --yes assume yes/default for all prompts (non-interactive with automatic defaults)

divekit plugin install

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

Install plugin-ready evaluation-pipeline assets

Usage

divekit plugin install [flags]

Flags

--force Overwrite existing injected CI templates

Inherited Flags

-d, --distribution string Target distribution override (default: project-level eval overrides and .divekit state)
 -l, --loglevel string log level (debug, info, warn, error, fatal) (default "info")
 --no-index skip project index update
 --non-interactive run in non-interactive mode (fails if interactive input is required)
 -y, --yes assume yes/default for all prompts (non-interactive with automatic defaults)

Parent Command

divekit plugin

divekit members role

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

Update GitLab access level for members in a distribution.

Changes the permission level for all project members across all repositories in a distribution by default. Pass specific members to update only those users. Downgrades also revoke overprivileged Project Access Tokens on affected work projects. Useful for adjusting access after deadlines or during different phases of an assignment.

Access Levels

 guest Can view project but not clone/download
 reporter Can clone and view issues
 developer Can push to non-protected branches
 maintainer Full access including protected branches

Use Cases

Restrict access after submission deadline (developer → guest)
Grant access for collaboration phase (guest → developer)
Emergency lockdown of all repositories

Usage

divekit members role [access-level] [member...] [flags]

Examples

# Set all members to developer access
divekit members role -d ST2M4 developer

# Restrict all members to guest (read-only)
divekit members role -d ST2M4 guest

# Using flag instead of positional argument
divekit members role -d ST2M4 --access-level reporter

# Re-enable specific members only
divekit members role -d ST2M4 developer alice bob

# Re-enable specific members with an interactive access-level prompt
divekit members role -d ST2M4 --member alice --member bob

# Interactive access level selection
divekit members role -d ST2M4

# Deprecated alias, still supported
divekit role -d ST2M4 developer alice bob

Flags

--access-level string New access level: guest|reporter|developer|maintainer
 --member strings GitLab username to update; may be used multiple times

Inherited Flags

-d, --distribution string Distribution name (required or prompted)
 -l, --loglevel string log level (debug, info, warn, error, fatal) (default "info")
 --no-index skip project index update
 --non-interactive run in non-interactive mode (fails if interactive input is required)
 -y, --yes assume yes/default for all prompts (non-interactive with automatic defaults)

Parent Command

divekit members

divekit plugin list

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

List configured plugins for evaluation pipelines

Usage

divekit plugin list [flags]

Flags

--verbose Show detailed plugin list output

Inherited Flags

-d, --distribution string Target distribution override (default: project-level eval overrides and .divekit state)
 -l, --loglevel string log level (debug, info, warn, error, fatal) (default "info")
 --no-index skip project index update
 --non-interactive run in non-interactive mode (fails if interactive input is required)
 -y, --yes assume yes/default for all prompts (non-interactive with automatic defaults)

Parent Command

divekit plugin

divekit members show

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

Show groups matching a member name or UUID

Usage

divekit members show [member-or-uuid] [flags]

Inherited Flags

-d, --distribution string Distribution name (required or prompted)
 -l, --loglevel string log level (debug, info, warn, error, fatal) (default "info")
 --no-index skip project index update
 --non-interactive run in non-interactive mode (fails if interactive input is required)
 -y, --yes assume yes/default for all prompts (non-interactive with automatic defaults)

Parent Command

divekit members

divekit plugin migrate

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

Convert flat v1 plugin state and its materialized layout to plugin suites.

The command prints the full plan and changes nothing until ‘–apply’ is passed. An applied migration copies every file it overwrites into ‘.divekit/backup/plugin-migrate-<timestamp>/’, which ‘–rollback’ restores.

Before writing, apply verifies the published suite, resolves enabled plugins to release tags and image digests, and composes the resulting pipeline. If the suite is incomplete, the origin stays unchanged on contract v1.

divekit purge

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

Delete the repositories a distribution created in its target groups.

WARNING: This operation is destructive and cannot be undone. All repository content is permanently deleted.

WHAT HAPPENS:

Reads remotes.json to identify the distributed repositories
Lists the target group projects and keeps only the recorded ones; other projects in the same groups are reported as skipped
Shows the deletion plan for confirmation
Deletes the confirmed repositories

–dry-run shows the plan for the real target groups and exits before the confirmation, so nothing is deleted. –all-group-projects widens the plan to every project in the target groups, including ones Divekit did not create.

divekit members status

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

Show member assignment status without changing anything

Usage

divekit members status [flags]

Flags

-r, --remote string Remote repository URL (e.g. GitLab instance)
 -t, --token string GitLab token or token file path (file:///...)

Inherited Flags

-d, --distribution string Distribution name (required or prompted)
 -l, --loglevel string log level (debug, info, warn, error, fatal) (default "info")
 --no-index skip project index update
 --non-interactive run in non-interactive mode (fails if interactive input is required)
 -y, --yes assume yes/default for all prompts (non-interactive with automatic defaults)

Parent Command

divekit members

divekit plugin outdated

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

Show plugins with newer stable versions available

Usage

divekit plugin outdated [flags]

Inherited Flags

-d, --distribution string Target distribution override (default: project-level eval overrides and .divekit state)
 -l, --loglevel string log level (debug, info, warn, error, fatal) (default "info")
 --no-index skip project index update
 --non-interactive run in non-interactive mode (fails if interactive input is required)
 -y, --yes assume yes/default for all prompts (non-interactive with automatic defaults)

Parent Command

divekit plugin

divekit role

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

DEPRECATED: Please use ‘divekit members role’ instead.

Update GitLab access level for members in a distribution.

divekit members sync

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

Synchronize configured members with distributed work repositories

Usage

divekit members sync [flags]

Flags

-r, --remote string Remote repository URL (e.g. GitLab instance)
 -t, --token string GitLab token or token file path (file:///...)

Inherited Flags

-d, --distribution string Distribution name (required or prompted)
 -l, --loglevel string log level (debug, info, warn, error, fatal) (default "info")
 --no-index skip project index update
 --non-interactive run in non-interactive mode (fails if interactive input is required)
 -y, --yes assume yes/default for all prompts (non-interactive with automatic defaults)

Parent Command

divekit members

divekit members validate

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

Validate the configured members file

Usage

divekit members validate [flags]

Inherited Flags

-d, --distribution string Distribution name (required or prompted)
 -l, --loglevel string log level (debug, info, warn, error, fatal) (default "info")
 --no-index skip project index update
 --non-interactive run in non-interactive mode (fails if interactive input is required)
 -y, --yes assume yes/default for all prompts (non-interactive with automatic defaults)

Parent Command

divekit members

divekit plugin override add

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

Add a manual report override to selected evaluation repositories.

The override is stored as a JSON file in .divekit/overrides and is applied by the report renderer after plugin reports are collected.

Usage

divekit plugin override add <plugin> [flags]

Examples

# Override one JaCoCo-PIT test for two groups
divekit plugin override add jacoco-pit -d ST2M4 --test-id coverage-threshold --group-ids b8520e99-2bad-c0de-b61c-1249a10f7a5a,a70decaf-bad7-4c95-b211-d0bc95f48204

# Match an existing report entry by category and name
divekit plugin override add jacoco-pit -d ST2M4 --category JaCoCo --name Coverage --group-ids 5f5c... --reason "Accepted after manual review"

# Override every test result from one plugin for one group
divekit plugin override add jacoco-pit -d ST2M4 --all-tests --group-ids b8520e99-2bad-c0de-b61c-1249a10f7a5a

# Preview the patch for all eval repositories
divekit plugin override add jacoco-pit -d ST2M4 --test-id coverage-threshold --all --dry-run

Flags

--all Patch all eval repositories in the distribution
 --all-tests Override every test result produced by the plugin
 --category string Report category to override when no test id is available
 -n, --dry-run string[="true"] Preview changes without applying (alias for --provider simulated)
 --group-ids stringArray Group UUIDs from the members file to patch (repeatable or comma-separated)
 --id string Override id and file name (default: generated)
 --members stringArray Member names whose repositories should be patched (repeatable or comma-separated)
 --members-file string Path to a file with member names (one per line)
 --name string Report name to narrow a category override
 -p, --provider string Provider to use: gitlab (default), local (filesystem), simulated (dry-run)
 --reason string Optional reason for the manual override
 --status string Status to force: success|warning|failure|fatal (default "success")
 --test-id string Stable plugin test id to override

Inherited Flags

-d, --distribution string Target distribution override (default: project-level eval overrides and .divekit state)
 -l, --loglevel string log level (debug, info, warn, error, fatal) (default "info")
 --no-index skip project index update
 --non-interactive run in non-interactive mode (fails if interactive input is required)
 -y, --yes assume yes/default for all prompts (non-interactive with automatic defaults)

Parent Command

divekit plugin override

divekit plugin source add

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

Add a trusted plugin source

Usage

divekit plugin source add <name> [flags]

Flags

--disabled Add source as disabled
 --group string GitLab group path (e.g. divekit/plugins)
 --host string Host alias from 'divekit config hosts list' (default "gitnrw")
 --project string Single GitLab project path (e.g. my-org/divekit-plugin-foo)
 --trusted Confirm this source is trusted

Inherited Flags

-d, --distribution string Target distribution override (default: project-level eval overrides and .divekit state)
 -l, --loglevel string log level (debug, info, warn, error, fatal) (default "info")
 --no-index skip project index update
 --non-interactive run in non-interactive mode (fails if interactive input is required)
 -y, --yes assume yes/default for all prompts (non-interactive with automatic defaults)

Parent Command

divekit plugin source

Go Testing Guide (Legacy)

Mon, 01 Jan 0001 00:00:00 +0000

Legacy material: this document is preserved for historical context and is not the current testing standard for Divekit CLI.

What should be tested in this project?

Given that this CLI is the entry point for the user to interact with Divekit, it is essential to test all commands. Currently, there is only one command patch, but all commands should be tested with the following aspects in mind:

Command Syntax: Verify that the command syntax is correct
Command Execution: Ensure that executing the command produces the expected behavior or output
Options and Arguments: Test each option and argument individually to ensure they are processed correctly and test various combinations of options and arguments
Error Handling: Test how the command handles incorrect syntax, invalid options, or missing arguments

Additionally, testing the utility functions is necessary, as they are used throughout the entire project. For that the following aspects should be considered:

divekit config hosts list

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

List all configured authentication hosts with their URLs and settings.

Shows host name, URL, concurrency settings, and token status for each configured host.

Usage

divekit config hosts list [flags]

Examples

divekit config hosts list

Inherited Flags

-l, --loglevel string log level (debug, info, warn, error, fatal) (default "info")
 --no-index skip project index update
 --non-interactive run in non-interactive mode (fails if interactive input is required)
 -y, --yes assume yes/default for all prompts (non-interactive with automatic defaults)

Parent Command

divekit config hosts

divekit config origin list

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

List all available distributions in the current Divekit project.

Scans the .divekit/distributions directory and shows all configured distributions.

Usage

divekit config origin list [flags]

Examples

divekit config origin list

Inherited Flags

-l, --loglevel string log level (debug, info, warn, error, fatal) (default "info")
 --no-index skip project index update
 --non-interactive run in non-interactive mode (fails if interactive input is required)
 -y, --yes assume yes/default for all prompts (non-interactive with automatic defaults)

Parent Command

divekit config origin

divekit members alias list

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

List configured member display names

Usage

divekit members alias list [flags]

Inherited Flags

-d, --distribution string Distribution name (required or prompted)
 -l, --loglevel string log level (debug, info, warn, error, fatal) (default "info")
 --no-index skip project index update
 --non-interactive run in non-interactive mode (fails if interactive input is required)
 -y, --yes assume yes/default for all prompts (non-interactive with automatic defaults)

Parent Command

divekit members alias

divekit plugin pin

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

Pin one plugin to a Git reference (branch, tag, or commit), or pin a plugin of a plugin suite to a version.

A suite plugin is named by its runtime identity <suite>/<plugin>. Its pin is one of: an exact version (1.2.1), patch updates (~1.2 or ~1.2.1), or updates within a major version (^1 or ^1.2.1). The pin replaces the pin of the suite manifest for this origin. The locked version only moves when it no longer matches the pin; ‘divekit plugin update’ picks up newer releases that the pin allows. Use –clear to follow the suite manifest again.

divekit search

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

Search for Divekit projects by name, distribution, or user.

Provides both interactive and non-interactive modes for finding projects in the local index. Selected projects can be navigated to or have actions executed on them.

Modes

 Interactive (default when no arguments):
 Launches a TUI to browse and select projects.
 Output: prints selected project path to stdout.

 Non-Interactive (when search terms or filters provided):
 Searches with provided terms/filters and prints matching paths.

Available Actions

 distribute Run distribute on selected project
 doctor Run doctor on selected project
 fetch-all Fetch all repositories
 fetch-one Fetch single repository
 overview Show project overview
 passcheck Run passcheck
 run Run an extension (requires --run-script)

Usage

divekit search [term...] [flags]

Examples

# Launch interactive search (default)
divekit search

# Search by project name
divekit search my-project

# Filter by user
divekit search --user alice

# Filter by distribution
divekit search -d ST2M4

# Navigate to selected project
cd $(divekit search)

# Search and run distribute on selection
divekit search --action distribute

# Search and run an extension
divekit search --action run --run-script analyze

Flags

--action string Action to run on selection: distribute|doctor|fetch-all|fetch-one|overview|passcheck|run
 -d, --distribution string Filter by distribution name
 -r, --remote string Remote repository URL (e.g. GitLab instance)
 --run-script string Extension to run when --action=run (path or extension name)
 -t, --token string GitLab token or token file path (file:///...)
 --user string Filter by username

Inherited Flags

-l, --loglevel string log level (debug, info, warn, error, fatal) (default "info")
 --no-index skip project index update
 --non-interactive run in non-interactive mode (fails if interactive input is required)
 -y, --yes assume yes/default for all prompts (non-interactive with automatic defaults)

Testrepo Notes (Legacy)

Mon, 01 Jan 0001 00:00:00 +0000

Legacy material: this page is no longer part of the active testing documentation.

Testing Package structure

ExampleFile

static final String PACKAGE_PREFIX = "thkoeln.divekit.archilab.";

@Test
public void testPackageStructure() {
 try {
 Class.forName(PACKAGE_PREFIX + "domainprimitives.StorageCapacity");
 Class.forName(PACKAGE_PREFIX + "notebook.application.NotebookDto");
 Class.forName(PACKAGE_PREFIX + "notebook.application.NotebookController");
 Class.forName(PACKAGE_PREFIX + "notebook.domain.Notebook");
 // using individualization and the variableExtensionConfig.json this could be simplified to
 // Class.forName("$entityPackage$.domain.$entityClass$");
 // ==> Attention: If used, the test can't be tested in the orgin repo itself
 } catch (ClassNotFoundException e) {
 Assertions.fail("At least one of your entities is not in the right package, or has a wrong name. Please check package structure and spelling!");
 }
}

Testing REST Controller

ExampleFile

divekit plugin source list

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

List configured plugin sources

Usage

divekit plugin source list [flags]

Inherited Flags

-d, --distribution string Target distribution override (default: project-level eval overrides and .divekit state)
 -l, --loglevel string log level (debug, info, warn, error, fatal) (default "info")
 --no-index skip project index update
 --non-interactive run in non-interactive mode (fails if interactive input is required)
 -y, --yes assume yes/default for all prompts (non-interactive with automatic defaults)

Parent Command

divekit plugin source

divekit plugin refresh

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

Refresh installed evaluation-pipeline assets and optionally pin one plugin ref

Usage

divekit plugin refresh [plugin] [flags]

Flags

--ref string Optional ref to pin when updating one plugin

Inherited Flags

-d, --distribution string Target distribution override (default: project-level eval overrides and .divekit state)
 -l, --loglevel string log level (debug, info, warn, error, fatal) (default "info")
 --no-index skip project index update
 --non-interactive run in non-interactive mode (fails if interactive input is required)
 -y, --yes assume yes/default for all prompts (non-interactive with automatic defaults)

Parent Command

divekit plugin

divekit plugin override remove

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

Remove a manual report override from selected eval repositories

Usage

divekit plugin override remove <override-id> [flags]

Examples

divekit plugin override remove coverage-threshold-20260529T091500Z -d ST2M4 --members alice,bob
divekit plugin override remove coverage-threshold-20260529T091500Z -d ST2M4 --all --dry-run

Flags

--all Patch all eval repositories in the distribution
 -n, --dry-run string[="true"] Preview changes without applying (alias for --provider simulated)
 --group-ids stringArray Group UUIDs from the members file to patch (repeatable or comma-separated)
 --members stringArray Member names whose repositories should be patched (repeatable or comma-separated)
 --members-file string Path to a file with member names (one per line)
 -p, --provider string Provider to use: gitlab (default), local (filesystem), simulated (dry-run)

Inherited Flags

-d, --distribution string Target distribution override (default: project-level eval overrides and .divekit state)
 -l, --loglevel string log level (debug, info, warn, error, fatal) (default "info")
 --no-index skip project index update
 --non-interactive run in non-interactive mode (fails if interactive input is required)
 -y, --yes assume yes/default for all prompts (non-interactive with automatic defaults)

Parent Command

divekit plugin override

divekit config hosts rename

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

Rename a host entry while preserving all its settings and tokens.

Usage

divekit config hosts rename [flags]

Examples

divekit config hosts rename --from oldname --to newname

Flags

--from string Current host name
 --to string New host name

Inherited Flags

-l, --loglevel string log level (debug, info, warn, error, fatal) (default "info")
 --no-index skip project index update
 --non-interactive run in non-interactive mode (fails if interactive input is required)
 -y, --yes assume yes/default for all prompts (non-interactive with automatic defaults)

Parent Command

divekit config hosts

divekit config origin rm

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

Remove a configuration value from config.json.

Usage

divekit config origin rm [flags]

Examples

# Remove a key from config
divekit config origin rm -d ST2M4 --key unusedSetting

# Remove createMergeRequest setting
divekit config origin rm -d ST2M4 --key createMergeRequest

Flags

-d, --distribution string Distribution name
 --key string Configuration key to remove (prefix with remotes. to target remotes.json)

Inherited Flags

-l, --loglevel string log level (debug, info, warn, error, fatal) (default "info")
 --no-index skip project index update
 --non-interactive run in non-interactive mode (fails if interactive input is required)
 -y, --yes assume yes/default for all prompts (non-interactive with automatic defaults)

Parent Command

divekit config origin

divekit members alias set

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

Set a local display name for a GitLab username.

The local name is the name already used in a local members file, for example a student name or internal account name. The GitLab username is the account name that should be stored in members.json and used for GitLab operations.

You can pass both values as positional arguments or with explicit flags.

divekit snapshot

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

Create research snapshots from a Divekit distribution.

Snapshots clone the selected work repositories, remove Git history, create a single neutral initial commit, and push the result into a target GitLab group.

Privacy note: this removes commit history and commit metadata only. UUIDs, file contents, file paths, and other in-repository data are not anonymized or scrubbed.

Usage

divekit snapshot [flags]

Examples

# Snapshot all repositories into an explicit research group
divekit snapshot -d ST2M4 --target-group research/course-2026

# Preview without creating subgroups, projects, clones, or pushes
divekit snapshot -d ST2M4 --target-group research/course-2026 --dry-run

# Snapshot selected UUIDs and overwrite existing targets
divekit snapshot -d ST2M4 --uuid abc123 --uuid def456 --on-existing overwrite

Flags

--author-email string Neutral snapshot commit author email (default "divekit@invalid.local")
 --author-name string Neutral snapshot commit author name (default "Divekit")
 --branch string Target branch to push (default "main")
 --commit-message string Snapshot commit message (default "Initial snapshot")
 -d, --distribution string Distribution name
 -n, --dry-run Show what would happen without cloning, creating GitLab resources, or pushing
 --label string Snapshot label (default: local timestamp YYYYMMDD-HHMMSS)
 --name-pattern string Target project name template (default: {{distribution}}-{{uuid}})
 --on-existing string Existing target behavior: skip, overwrite, or fail (default "skip")
 -o, --output-dir string Local staging output directory to keep after push
 --rate-limit float Maximum snapshot tasks per second (unset = preset, 0 = unlimited)
 -r, --remote string Remote repository URL (e.g. GitLab instance)
 --source-ref string Source branch or tag to clone (default: source default branch)
 --target-group string Target GitLab group path or ID
 -t, --token string GitLab token or token file path (file:///...)
 --user strings Only snapshot repositories for these usernames (repeatable)
 --uuid strings Only snapshot repositories with these UUIDs (repeatable)
 --visibility string Target project visibility (default "private")
 -w, --workers int Number of concurrent snapshot workers (0 = use preset)

Inherited Flags

-l, --loglevel string log level (debug, info, warn, error, fatal) (default "info")
 --no-index skip project index update
 --non-interactive run in non-interactive mode (fails if interactive input is required)
 -y, --yes assume yes/default for all prompts (non-interactive with automatic defaults)

divekit plugin source remove

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

Remove a plugin source

Usage

divekit plugin source remove <name> [flags]

Inherited Flags

-d, --distribution string Target distribution override (default: project-level eval overrides and .divekit state)
 -l, --loglevel string log level (debug, info, warn, error, fatal) (default "info")
 --no-index skip project index update
 --non-interactive run in non-interactive mode (fails if interactive input is required)
 -y, --yes assume yes/default for all prompts (non-interactive with automatic defaults)

Parent Command

divekit plugin source

divekit config hosts rm

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

Remove a host configuration from the settings.

By default, only the host entry is removed. Use –remove-token to also delete the stored authentication token from the system keychain or the plaintext fallback store.

Usage

divekit config hosts rm [flags]

Examples

# Remove host entry only
divekit config hosts rm --name gitlab

# Remove host entry and stored token
divekit config hosts rm --name gitlab --remove-token

Flags

--name string Host name to remove
 --remove-token Also remove stored token

Inherited Flags

-l, --loglevel string log level (debug, info, warn, error, fatal) (default "info")
 --no-index skip project index update
 --non-interactive run in non-interactive mode (fails if interactive input is required)
 -y, --yes assume yes/default for all prompts (non-interactive with automatic defaults)

Parent Command

divekit config hosts

divekit config origin set

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

Set or update a configuration value in config.json.

Values are parsed as JSON when possible, otherwise stored as strings.

Usage

divekit config origin set [flags]

Examples

# Set target group ID
divekit config origin set -d ST2M4 --key groupId --value 123

# Set repository name pattern
divekit config origin set -d ST2M4 --key name --value "ST2-{{uuid}}"

# Change remote provider
divekit config origin set -d ST2M4 --key remote --value gitlab

Flags

-d, --distribution string Distribution name
 --key string Configuration key (prefix with remotes. to target remotes.json)
 --value string Value to set (parsed as JSON when possible)

Inherited Flags

-l, --loglevel string log level (debug, info, warn, error, fatal) (default "info")
 --no-index skip project index update
 --non-interactive run in non-interactive mode (fails if interactive input is required)
 -y, --yes assume yes/default for all prompts (non-interactive with automatic defaults)

Parent Command

divekit config origin

divekit plugin show

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

Show the resolved state for one evaluation-pipeline plugin

Usage

divekit plugin show <plugin> [flags]

Inherited Flags

-d, --distribution string Target distribution override (default: project-level eval overrides and .divekit state)
 -l, --loglevel string log level (debug, info, warn, error, fatal) (default "info")
 --no-index skip project index update
 --non-interactive run in non-interactive mode (fails if interactive input is required)
 -y, --yes assume yes/default for all prompts (non-interactive with automatic defaults)

Parent Command

divekit plugin

divekit uninstall

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

Remove the managed Divekit installation from this user account.

By default, this removes the installed divekit binary, cleans up PATH entries managed by Divekit, and removes the install manifest.

Use –purge-user-data to also remove ~/.divekit, including configuration, templates, scripts, logs, and fallback secret storage.

Use –remove-tokens to also delete stored authentication tokens from the system keychain or Divekit fallback secret storage.

divekit members alias unset

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

Remove display-name metadata for a GitLab username

Usage

divekit members alias unset [gitlab-username] [flags]

Flags

--dry-run Preview alias removal without writing a new members file

Inherited Flags

-d, --distribution string Distribution name (required or prompted)
 -l, --loglevel string log level (debug, info, warn, error, fatal) (default "info")
 --no-index skip project index update
 --non-interactive run in non-interactive mode (fails if interactive input is required)
 -y, --yes assume yes/default for all prompts (non-interactive with automatic defaults)

Parent Command

divekit members alias

divekit config hosts set

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

Add a new host or update an existing host configuration.

Use this command to configure GitLab instances or other Git providers. Tokens can be provided directly, read from environment variables, or entered interactively.

Usage

divekit config hosts set [flags]

Examples

# Add a host with interactive token prompt (recommended)
divekit config hosts set --name gitlab --url https://gitlab.com --ask-token

# Add a host with token from command line
divekit config hosts set --name gitlab --url https://gitlab.com --token glpat-xxx

# Update concurrency settings for an existing host
divekit config hosts set --name gitlab --max-workers 5 --enable-concurrency

Flags

--ask-token Prompt for token interactively
 --disable-concurrency Disable concurrency for this host
 --enable-concurrency Enable concurrency for this host
 --max-workers int Override per-host concurrency workers (0 = leave unchanged)
 --name string Host alias (e.g. gitlab)
 --rate-limit-delay-ms int Delay between requests in milliseconds (0 = leave unchanged)
 --token string API token to store securely
 --token-key string Override token key (defaults to derived DIVEKIT_API_TOKEN_* env var)
 --url string Host URL (e.g. https://gitlab.com)

Inherited Flags

-l, --loglevel string log level (debug, info, warn, error, fatal) (default "info")
 --no-index skip project index update
 --non-interactive run in non-interactive mode (fails if interactive input is required)
 -y, --yes assume yes/default for all prompts (non-interactive with automatic defaults)

Parent Command

divekit config hosts

divekit config origin show

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

Display the origin configuration for a specific distribution.

Shows the contents of config.json and optionally remotes.json.

Usage

divekit config origin show [flags]

Examples

# Show config as JSON
divekit config origin show -d ST2M4

# Show config and remotes
divekit config origin show -d ST2M4 --remotes

# Show config in table format
divekit config origin show -d ST2M4 --format table

Flags

-d, --distribution string Distribution name
 --format string Output format: json|table (default "json")
 --remotes Also show remotes.json

Inherited Flags

-l, --loglevel string log level (debug, info, warn, error, fatal) (default "info")
 --no-index skip project index update
 --non-interactive run in non-interactive mode (fails if interactive input is required)
 -y, --yes assume yes/default for all prompts (non-interactive with automatic defaults)

Parent Command

divekit config origin

divekit update

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

Check for and install updates to the divekit CLI.

Downloads and installs the latest version from the configured GitLab remote. Supports both stable and pre-release update channels.

Update Channels

 stable Production-ready releases (default)
 pre Pre-release versions for testing new features

Usage

divekit update [flags]

Examples

# Check and apply updates
divekit update

# Only check for available updates
divekit update --check

# Update to latest pre-release
divekit update --channel pre

# Update with explicit credentials
divekit update --token glpat-xxx --remote https://gitlab.git.nrw

Flags

--channel string Update channel: stable or pre (default "stable")
 --check Only check and print versions without updating
 -r, --remote string GitLab base URL (e.g., https://gitlab.git.nrw)
 -t, --token string GitLab token or token file path (file:///...)

Inherited Flags

-l, --loglevel string log level (debug, info, warn, error, fatal) (default "info")
 --no-index skip project index update
 --non-interactive run in non-interactive mode (fails if interactive input is required)
 -y, --yes assume yes/default for all prompts (non-interactive with automatic defaults)

divekit plugin upgrade

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

Upgrade plugins to the newest stable version

Usage

divekit plugin upgrade [plugin] [flags]

Flags

--all Upgrade all configured plugins with newer stable versions

Inherited Flags

-d, --distribution string Target distribution override (default: project-level eval overrides and .divekit state)
 -l, --loglevel string log level (debug, info, warn, error, fatal) (default "info")
 --no-index skip project index update
 --non-interactive run in non-interactive mode (fails if interactive input is required)
 -y, --yes assume yes/default for all prompts (non-interactive with automatic defaults)

Parent Command

divekit plugin

divekit version

Mon, 01 Jan 0001 00:00:00 +0000

Synopsis

Display version and build information for the divekit CLI.

Shows the version number, the git commit, and the build date.

Release builds report the metadata injected at release time. Development builds report the commit and commit time Go records from the checkout, with a “-dirty” suffix when the tree had uncommitted changes, and say so explicitly when no VCS metadata was recorded.

Search Results

Mon, 01 Jan 0001 00:00:00 +0000

Divekit

Development Setup

Stable Summary

Source of Truth

Error Handling

Stable Summary

Contributing Guidelines

Stable Expectations

Source of Truth

config.json

Current Stored Format

Keys

Repository Name Templates

Hello there 👋

What is Divekit?

Visual overview: from origin to distributed repositories

How Divekit Works

From Origin To Results

1. Author The Course Once

Repository Name Templates

Common Examples

Configuration Notes

Scope of This Page

Configuration Keys

Distribution config.json

Installation

Prerequisites

System Requirements

GitLab Setup

members.json

Format

Keys

Import Input

Example Origins

Choose an example

First steps

Create Your First Project

What divekit init does

GitLab Permissions

Token Scope

Configuration Model

1. Configuration Layers

2. User-Level Configuration

Deployment

Release Trigger

Recommended Tag Creation

CI Pipeline Behavior

divekit dev

Synopsis

Detected Issues

Scan Sources

Usage

Examples

Flags

Inherited Flags

Individualization

Overview

Configuration Files

variation.json (input)

individualization.json (optional input)

Paths and Locations

User-Level Paths

Project-Level Paths

Resolution Rules

individualization.json

Variation definitions

variation.json

Format

Top-Level Sections

Variation Fields and Token Overrides

Evaluation Pipeline

What It Is

What It Does

Runtime Flow

Work-To-Eval Materialization

Plugins

What Plugins Do

Manual Feedback

Author Feedback

Plugin Suites

What `divekit init` does

`variation.json` (input)

`individualization.json` (optional input)

`variables`