Divekit CLI Commands on Divekit

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)

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)

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 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 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 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 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 purge

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

Synopsis

Delete repositories from configured target groups

Usage

divekit purge [flags]

Flags

-d, --distribution string Distribution name
 -n, --dry-run Preview what would be deleted (alias for --provider simulated)
 -p, --provider string Provider: gitlab (default), local, simulated
 -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)

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.

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.

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)

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 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 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 version

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

Synopsis

Display version and build information for the divekit CLI.

Shows the current version number, git commit hash, build date, and Go version used to compile the binary.

Usage

divekit version [flags]

Examples

# Show version information
divekit version

# Short form (flag)
divekit --version

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)