Divekit CLI

• 1: divekit install
• 2: divekit init
• 3: divekit doctor
• 4: divekit distribute
• 5: divekit patch
• 6: divekit index
• 7: divekit overview
• 8: divekit config
• 9: divekit passcheck
• 10: divekit update
• 11: divekit run

1 - divekit install

Installs the divekit CLI and the required modules by creating a symbolic link in the system PATH with proper executable permissions.

Usage

divekit install [flags]

Flags

• --help: Show help information

Description

The divekit install command makes the Divekit CLI globally available by creating a symbolic link to the executable in a directory included in your system’s PATH. It supports cross-platform installation and handles permissions appropriately.

Key features:

• Creates system PATH symlinks
• Cross-platform support (macOS, Linux, Windows)
• Proper permission handling
• Displays current version after installation

Examples

Basic Installation

$ divekit install

Installing divekit in home directory...
[√] divekit installed in home directory
[√] divekit executable added to PATH

Verify Installation

$ divekit --version
divekit version v1.0.0

Updates (Planned)

• Check for newer versions: divekit update --check (displays current and available versions)
• Automatic update application (future release)
• Support for package managers like Homebrew or Snap for easier distribution

Cross-Platform Support

• macOS: Symlink created in /usr/local/bin/divekit
• Linux: Symlink created in ~/bin/divekit or /usr/local/bin/divekit (depending on permissions)
• Windows: Adds to PATH via environment variable (requires admin rights for system-wide)

Notes

• Installation currently requires manual PATH setup on some systems if the symlink directory is not in PATH
• Exit codes indicate success/failure
• Supports both interactive and non-interactive modes
• Reinstallation handles existing symlinks gracefully

2 - divekit init

Initializes a new Divekit distribution by creating the necessary configuration files with the simplified Version 2.0 format under .divekit/.

Usage

divekit init [flags]

Flags

• --help: Show help information
• No other flags; the command is interactive

Description

The divekit init command guides you through setting up a new or editing/copying an existing distribution configuration. It creates the .divekit/distributions/<name>/config.json file with sensible defaults and allows customization through an interactive flow. All generated files are placed under the .divekit/ directory to ensure consistency and avoid root-level clutter.

Key features:

• Interactive initialization with validation and clear error messages
• Options to create new, edit existing, or copy from another distribution
• Automatic linking between main and test targets if secure pipeline is enabled
• Copy of additional files like individualization.json, variation.json, individuals.json (with prompts)
• Input validation for group IDs, paths, etc.
• Defaults to configuration version 2.0

Initialization Flow

1. Choose Action: Create new distribution, edit existing, or copy from another
2. Distribution Name: Prompt for name (checks for conflicts)
3. Repository Template: Customize naming pattern (e.g., assignment-{{uuid}})
4. Group IDs: Enter GitLab group ID for code repositories
5. Secure Pipeline: Optional (y/N); if enabled, prompt for test group ID
6. Members: Path to members.json (defaults to $DIVEKIT_MEMBERS/members.json) and permissions (developer/maintainer)
7. Save: Creates .divekit/distributions/<name>/config.json and optional files

Examples

Create a new distribution (interactive)

$ divekit init

Welcome to Divekit! This will help you create a new distribution.

What do you want to do?
> Create new distribution
  Edit existing distribution
  Copy from another distribution

? Distribution name: my-assignment
? Repository name template: assignment-{{uuid}}
? GitLab group ID for code repositories: 123456
? Enable secure pipeline? (y/N): y
? GitLab group ID for test repositories: 234567
? Path to members file: $DIVEKIT_MEMBERS/members.json
? Member permissions (developer/maintainer): developer

Configuration created at ./.divekit/distributions/my-assignment/config.json
Updating project index...

Edit an existing distribution

$ divekit init

What do you want to do?
  Create new distribution
> Edit existing distribution
  Copy from another distribution

Select distribution:
> my-assignment
  ws2024-java

Loaded ./.divekit/distributions/my-assignment/config.json
# You will be prompted for the same fields and can update values.
Saving configuration...
Updating project index...

Copy from another distribution (with optional file copy)

$ divekit init

What do you want to do?
  Create new distribution
  Edit existing distribution
> Copy from another distribution

Select source distribution:
> ws2024-java
  ws2023-java

? New distribution name: ws2024-java-b
? Copy individualization/variation configs if present? (y/N): y
? Copy individuals.json from source distribution? (y/N): n

Created:
- ./.divekit/distributions/ws2024-java-b/config.json
- ./.divekit/distributions/ws2024-java-b/variation.json (copied)
- ./.divekit/distributions/ws2024-java-b/individualization.json (copied)

Updating project index...

Generated Files

• .divekit/distributions/<name>/config.json: Main configuration
• Optional: .divekit/distributions/<name>/individualization.json, variation.json, individuals.json
• No root-level files or directories like config/ or origin/ are created

Generated Configuration Example

{
  "version": "2.0",
  "remote": "default",
  "groupId": 123456,
  "name": "assignment-{{uuid}}",
  "members": {
    "path": "$DIVEKIT_MEMBERS/members.json",
    "permissions": "developer"
  },
  "securePipeline": {
    "enabled": true,
    "groupId": 234567
  }
}

Notes

• No config/, origin/, or root-level members.json directories/files are created; everything under .divekit/
• The CLI validates inputs and writes the distribution config by default
• After saving, the CLI updates the local project index if available
• For copy operations, confirm copying of sensitive files like individuals.json
• If secure pipeline is enabled, automatic linking from main to test is added

3 - divekit doctor

divekit doctor runs a series of focused checks to validate your local setup. It helps identify misconfigurations early and prints PASS/FAIL results for each check.

Usage

divekit doctor

What it currently checks

The current implementation performs these checks:

• Divekit Home Directory
  • Ensures your Divekit home directory exists and is initialized.
• Configuration Availability
  • Verifies that a valid Divekit home can be determined for configuration access.
• GitLab Connection (basic)
  • Attempts to read a token from the OS credential store and a default host from ~/.divekit/hosts.json, then performs a basic API connectivity check.
  • Notes:
    • Tokens are retrieved from your OS credential manager (Keychain on macOS, Credential Manager on Windows, Secret Service on Linux).
    • hosts.json stores host metadata and a token-key reference, not the token itself.
• Unresolved Token Detection (sanity)
  • Runs a lightweight sanity-check for unresolved template tokens in example content using your effective token delimiters.

Output format

The command prints a compact PASS/FAIL report:

--- Doctor Results ---
PASS Divekit Home Directory
PASS Configuration File
PASS GitLab Connection & Token (Basic Check)
PASS Unresolved Token Detection
--------------------

If a check fails, a FAIL line is printed with an error explanation.

Preparing your environment for doctor

To enable the GitLab connection check:

1. Configure a GitLab host and token

# Simplified (prompts for token and stores it in OS keychain)
divekit config set @hosts git-nrw https://gitlab.git.nrw/

# Or non-interactive with token flag
divekit config set @hosts git-nrw https://gitlab.git.nrw/ --token glpat-xxx...

2. Verify the host entry

divekit config get @hosts.git-nrw

Troubleshooting

• Token not found:
  • Add a host as shown above or open your OS credential manager and verify an entry exists for “divekit-cli”.
• Base URL unknown:
  • Ensure ~/.divekit/hosts.json contains a default host or the host you intend to use.
• Keychain inspection:
  • macOS: Keychain Access → search “divekit-cli”
  • Windows: Credential Manager → Windows Credentials → search “divekit-cli”
  • Linux: secret-tool search service divekit-cli

Notes and roadmap

• The doctor command focuses on essential checks. Additional in-depth validations (e.g., distribution remotes, module presence) may be added in future iterations.
• No subcommands are currently available; the legacy “doctor list/check …” interface mentioned in older drafts is not implemented.

4 - divekit distribute

Creates multiple repositories on GitLab based on the Version 2.0 configuration in config.json.

Usage

divekit distribute [distribution-name] [flags]

Flags

• --base-url <url>: Base URL for the GitLab instance
• --token <value>: GitLab access token (required for GitLab provider)
• --distribution <name>, -d <name>: Specify which distribution to use (or as argument)
• --members-file <path>: Path to a file with member names (one per line)
• --add: Add users to an existing distribution
• --fresh: Delete remotes.json/individuals.json before distributing
• --message <text>, -m <text>: Commit message for initial commit
• --max-workers <int>: Maximum number of concurrent workers (0 = default: 3)
• --rate-limit-delay <duration>: Delay between GitLab API requests (0 = default: 100ms)
• --provider <type>: Provider to use: gitlab (default), local (filesystem), simulated (dry-run)
• --concurrent: Enable concurrent execution (default: true)
• --warn-unresolved-tokens <mode>: Warn about unresolved tokens: auto|true|false (overrides config)
• --dangerously-delete-group-projects: Enable deletion of existing projects without prompting (use with caution)
• --help: Show help information

Credentials

• Tokens are stored in your operating system’s credential manager (macOS Keychain, Windows Credential Manager, Linux Secret Service).
• Configure hosts via:

  divekit config set @hosts git-nrw https://gitlab.git.nrw/  # prompts for token and stores it in OS keychain
  

• The flags --token and --base-url are optional overrides. If omitted, Divekit resolves credentials and base URL from your configured hosts (hosts.json contains only host metadata and a token-key reference).

Description

The divekit distribute command creates individualized repositories for each student or group based on your configuration. It is idempotent, meaning it skips existing repositories and only processes new members. The command supports concurrent processing with configurable worker pools and automatic rate limit handling with exponential backoff.

Key features:

• Repository creation and configuration from origin templates
• Member permission assignment with validation
• Idempotent operations for safe re-execution
• Concurrent processing (default 3 workers)
• Automatic rate limit handling with exponential backoff (up to 5 retries)
• Custom commit message support
• Provider support (GitLab, local, simulated for dry-run)
• Individualization using variables and content variations
• Linking between code and sandbox repositories

The flow:

1. Validates the configuration and member data
2. Loads members from file or config
3. Creates code repositories in the specified GitLab group (or simulates)
4. Optionally creates secure pipeline repositories
5. Sets up repository linking between code and test repos
6. Assigns members with appropriate permissions
7. Applies individualization rules to content
8. Handles unresolved tokens with configurable warnings

Examples

Distribute with interactive confirmation

$ divekit distribute --distribution my-assignment

starting distribution (provider="gitlab", add=false, fresh=false, workers=3, concurrent=true, non-interactive=false, delete=false)
Loading configuration: ./.divekit/distributions/my-assignment/config.json
Resolving credentials from host config...

Pre-checks:
[√] Members loaded (27)
[√] Configuration valid
[√] Targets detected: main, test

Plan (summary):
- Create 27 code repositories in group #123456
- Create 27 test repositories in group #234567
- Link code→test repositories
- Assign members with role: developer

Continue? [y/N]: y

Creating code repositories...
Creating test repositories...
Linking repositories...
Assigning members...

Done.

Adding to existing distribution (latecomers)

$ divekit distribute --dirstibution my-assignment --add --members-file ./new-members.txt

What Gets Created

• Code Repositories: Main repositories where students work on their assignments, with individualized content
• Test Repositories: Optional secure repositories for automated testing (if securePipeline enabled)
• Repository Links: Automatic linking between code and test repositories
• Member Assignments: Students assigned with configured permissions (developer/maintainer)
• Initial Commits: With custom message and origin content variations

5 - divekit patch

The divekit patch command applies local file changes to all remote repositories of a chosen distribution. It uses the same distribution configuration and authentication resolution as divekit distribute, including token retrieval from the OS credential manager.

Usage

divekit patch [files...] [flags]

• At least one file path must be provided.
• If --distribution is omitted, you will be prompted to select one (interactive flow).

Flags

• --distribution <name>, -d <name>: Distribution to patch (prompt if omitted)
• --dry-run <mode>: Simulate changes without committing
  • empty or true: simulated provider (no remote changes)
  • fs: use local filesystem provider for previewing changes
• --message <text>, -m <text>: Commit message (default is a timestamped “Patch applied …”)
• --warn-unresolved-tokens <auto|true|false>: Warn about unresolved tokens in content (default: auto)
• Concurrency:
  • --max-workers <int>: Max concurrent workers (0 = default: 3)
  • --rate-limit-delay <duration>: Delay between API requests (0 = default: 100ms)
  • --concurrent <bool>: Enable/disable concurrency (default: true)
• GitLab credentials (usually resolved automatically):
  • --token, -t: GitLab token (optional; retrieved from OS credential store if not provided)
  • --remote, -r: GitLab base URL (optional; resolved from host configuration)
• --help: Show help

Notes:

• Tokens are stored in the OS credential manager (Keychain on macOS, Credential Manager on Windows, Secret Service on Linux). Host metadata and token-key references are stored in ~/.divekit/hosts.json. Configure hosts via:

  divekit config set @hosts git-nrw https://gitlab.git.nrw/   # prompts for token, stores in OS keychain
  

Description

For each remote repository in the selected distribution:

1. The command loads the provided patch files from your local working directory.
2. It individualizes the content per target/remote (respecting distribution tokens and routing markers).
3. It compares against the current remote content and creates commits with only the necessary changes.

Patches are applied safely and idempotently:

• Missing files are created.
• Changed files are updated.
• Unchanged files are skipped.

Content is individualized per repository (e.g., tokens replaced, target routing markers stripped) before comparison and commit.

Examples

Apply two files to the “supervisor” distribution

divekit patch --distribution supervisor E2WhateverTests.java pom.xml -m "Make some tests optional"

Dry-run (simulate without committing)

# Simulated provider (no remote changes, logs planned actions)
divekit patch --distribution supervisor E2WhateverTests.java pom.xml --dry-run true

# Filesystem preview mode (fs)
divekit patch --distribution supervisor E2WhateverTests.java pom.xml --dry-run fs

Interactive distribution selection

divekit patch E2WhateverTests.java pom.xml
# Prompts to select a distribution if multiple are detected

Control concurrency

divekit patch --distribution supervisor E2WhateverTests.java --max-workers 5 --rate-limit-delay 250ms

Handle unresolved tokens more strictly

divekit patch --distribution supervisor README.md --warn-unresolved-tokens true

Behavior details

• Individualization: Patch content is individualized per project using the configured token delimiters and per-project selections before diff/commit.
• Routing markers: Target/no-repo routing markers (as configured) are stripped from patch content before commit.
• Commit message: Uses -m/--message if provided; otherwise uses a default, timestamped message.

Troubleshooting

• “No remote projects found”:
  • Ensure the distribution has remotes configured (remotes.json) and that you selected the correct distribution.
• “Credentials not resolved”:
  • Configure a host and token via:

    divekit config set @hosts git-nrw https://gitlab.git.nrw/
    

  • Verify token exists in your OS credential manager under “divekit-cli”.
• API rate limits:
  • Increase --rate-limit-delay and/or reduce --max-workers, or disable concurrency with --concurrent=false.

6 - divekit index

Manage the Divekit project index, which allows you to quickly find and navigate to your Divekit projects.

Usage

divekit index <command> [flags]

Available Commands

• add — Add projects to the index

  • Usage: divekit index add [path]
  • Flags:
    • --find-up Find and add projects in the current or parent directories
    • --find-down Find and add projects recursively in the specified or current directory

• search — Search for projects in the index

  • Usage: divekit index search [term...] [flags]
  • Flags:
    • -i, --interactive Launch in interactive mode (prints selected project path)
    • --user <name> Filter by user
    • --distribution <name> Filter by distribution

• refresh — Update the index with current project information

  • Usage: divekit index refresh

Description

The project index helps you manage multiple Divekit projects efficiently. It maintains a searchable database of your projects, allowing you to:

• Quickly find projects by name, distribution, or user
• Navigate to project directories with auto-completion
• Keep track of all your Divekit projects in one place

Examples

Adding Projects

# Add current project to index
divekit index add

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

# Find and add all projects in current directory tree
divekit index add --find-down

# Find and add projects in parent directories
divekit index add --find-up

Searching Projects

# Interactive search
divekit index search -i

# Search by name
divekit index search "assignment-1"

# Search by distribution
divekit index search --distribution "ws2024"

# Search by user
divekit index search --user "john.doe"

# Combine filters
divekit index search "java" --distribution "ws2024"

Refreshing the Index

# Update all projects in index
divekit index refresh

Index Location

The project index is stored as a SQLite database at ~/.divekit/index.db. It contains:

• Project paths (absolute)
• Distributions detected per project
• Optional metadata used for searching and filtering

Note:

• The database is managed by the CLI; manual editing is not required or recommended.
• The index is updated via divekit index add ... and divekit index refresh.

Integration with Shell

The index integrates well with shell commands:

# Navigate to project found interactively
cd $(divekit index search -i)

# Open project in editor
code $(divekit index search "assignment-1")

7 - divekit overview

The divekit overview command loads a distribution configuration from .divekit/distributions/<name>/config.json, resolves credentials, and displays information about remote repositories (e.g., targets, UUIDs, users). With --serve, it starts a local web server to present an interactive HTML overview.

Usage

divekit overview [flags]

Flags

• --distribution <name>, -d <name>: Select the distribution to overview (prompt if omitted)
• --token <value>: GitLab token (optional; typically resolved from OS credential store)
• --remote <url>: GitLab base URL (optional; typically resolved from host config)
• --serve, -s: Serve the overview as an HTML page
• --dry-run: Perform a dry run without making API calls
• --help: Show help

Notes:

• Tokens are stored in your OS credential manager (Keychain on macOS, Credential Manager on Windows, Secret Service on Linux). Host metadata and token-key references are kept in ~/.divekit/hosts.json. Configure hosts via:

  divekit config set @hosts git-nrw https://gitlab.git.nrw/   # prompts for token and stores it in OS keychain
  

Description

When executed, the command:

1. Determines the project root (directory containing .divekit/).
2. Selects a distribution (via --distribution or prompt).
3. Loads its config from .divekit/distributions/<name>/config.json.
4. Resolves credentials for a target (host URL + token).
5. Displays or serves an overview of repositories for the distribution.

With --serve, an HTTP server is started and the default browser is opened. The HTML template lives in the CLI and is rendered at runtime.

Examples

Basic CLI Output

# Show overview for a chosen distribution (prompt if not provided)
divekit overview

Specific Distribution

divekit overview --distribution students

Serve an HTML Overview

divekit overview --distribution students --serve
# Serving on http://localhost:8080
# Opening browser...

Dry Run (no API calls)

divekit overview --distribution students --dry-run

Troubleshooting

• “Distribution not found”:
  • Ensure you are inside a Divekit project (has .divekit/).
  • Verify .divekit/distributions/<name>/config.json exists.
• “Credentials not resolved”:
  • Configure a host and token via:

    divekit config set @hosts git-nrw https://gitlab.git.nrw/
    

  • Check OS keychain entries for “divekit-cli”.
• “Cannot serve/port in use”:
  • Ensure port 8080 is free or set an alternate port if supported in your environment.

8 - divekit config

Usage

divekit config <command> [flags]

Available Commands

• get [key] - Get a configuration value
• set [key] [value] - Set a configuration value

Flags

• --token <value> - Set the access token directly (for host URLs, only in set command; usually resolved from OS credential manager)
• --help - Show help information

Description

The divekit config command allows you to view and modify your Divekit configuration settings using subcommands get and set. It supports aliases for targeting different configuration files and provides validation for all changes.

Key features:

• Configuration management
• CLI access for getting and setting values
• Schema validation
• Security best practices for sensitive data
• Environment variable override support (e.g., DIVEKIT_MEMBERS)

$ divekit config

Usage:
  divekit config <command>

Available Commands:
  get          Get configuration values
  set          Set configuration values

For more information about a command, run:
  divekit config <command> --help

Configuration Aliases

The divekit config command uses special aliases to target different configuration files:

• @hosts: Targets the global hosts.json file for GitLab remote configurations
• @origin.<distribution>: Targets the config.json for a specific distribution
• @origin.<distribution>.remotes.*: Targets the remotes.json for that distribution

Examples

Managing GitLab Hosts

Simplified Hosts Syntax

# Set up a new GitLab host (automatic token prompt)
divekit config set @hosts git-nrw https://gitlab.git.nrw/

# With direct token
divekit config set @hosts git-nrw https://gitlab.git.nrw/ --token glpat-xxx...

# Get host information
divekit config get @hosts.git-nrw

Traditional Syntax

# Set host URL
divekit config set @hosts.git-nrw.host https://gitlab.git.nrw/

# Set token
divekit config set @hosts.git-nrw.token glpat-xxx...

Managing Distribution Configuration

# Set repository name template
divekit config set @origin.my-distribution.name "assignment-{{uuid}}"

# Get current group ID
divekit config get @origin.my-distribution.groupId

# Update member permissions
divekit config set @origin.my-distribution.members.permissions "maintainer"

# Set remote URL for distribution
divekit config set @origin.main.remotes.gitlab.url https://gitlab.com/my-group/my-project

Managing Members

Members are typically managed through the members.json file referenced in your distribution configuration. The file should contain an array of member objects:

{
  "members": [
    {"username": "alice", "name": "Alice Johnson"},
    {"username": "bob", "name": "Bob Smith"},
    {"username": "charlie", "name": "Charlie Brown"}
  ]
}

Credentials and Security

• Tokens are stored in your operating system’s credential manager (macOS Keychain, Windows Credential Manager, Linux Secret Service). They are NOT written to hosts.json.
• The file ~/.divekit/hosts.json stores only host metadata and a token-key reference (the key used to retrieve the token from the OS credential store).
• Configure hosts using:

  # Prompts for token and stores it in the OS credential manager
  divekit config set @hosts git-nrw https://gitlab.git.nrw/
  
  # Or provide the token explicitly (useful for non-interactive setups)
  divekit config set @hosts git-nrw https://gitlab.git.nrw/ --token glpat-xxx...
  

• Optional: DIVEKIT_MEMBERS can be used to provide a global default path to your members.json (can also be configured per distribution):

  export DIVEKIT_MEMBERS="/path/to/members.json"
  

Configuration Migration (Planned)

• Automatic migration from v1.0 to v2.0 format when reading legacy files
• Schema validation and auto-migration capabilities
• Security warnings for sensitive member data placement with suggested secure alternatives

Configuration File Structure

The config.json file uses the Version 2.0 flat format:

{
  "version": "2.0",
  "remote": "default",
  "groupId": 123456,
  "name": "assignment-{{uuid}}",
  "members": {
    "path": "$DIVEKIT_MEMBERS/members.json",
    "permissions": "developer"
  },
  "securePipeline": {
    "enabled": true,
    "groupId": 234567
  }
}

Notes

• Supports dot notation for nested keys (e.g., members.permissions)
• Invalid values trigger specific error messages with correction guidance
• Automatic backup of configuration files before modifications
• Environment variable overrides for CI/CD scenarios

9 - divekit passcheck

Check test results for secure pipeline repositories and generate reports.

Usage

divekit passcheck [flags]

Flags

• --distribution <name>: Specific distribution to check (auto-detect if not provided)
• --detail: Show detailed test results per student
• --report: Generate Excel report
• --output-path <path>: Output path for generated reports (default: “./reports/”)
• --token <token>: GitLab token
• --remote <url>: Remote repository URL (GitLab Instance)

Credentials

• Tokens are stored in your operating system’s credential manager (macOS Keychain, Windows Credential Manager, Linux Secret Service).
• Prefer configuring hosts via:

  divekit config set @hosts git-nrw https://gitlab.git.nrw/  # prompts for token and stores it in OS keychain
  

• The flags --token and --remote are optional overrides. If omitted, credentials and base URL are resolved from your configured hosts.

Description

The passcheck command automatically detects the current distribution, validates that secure pipeline is enabled, and checks test results from test repositories. It provides an overview of passed/failed tests and can generate detailed reports.

Features

• Automatic Detection: Finds the current distribution and secure pipeline setup
• Test Result Analysis: Checks test results from secure pipeline repositories
• Detailed Reporting: Shows per-student test results when using --detail
• Excel Reports: Generates comprehensive Excel reports with --report
• Flexible Output: Customizable output paths for reports

Examples

Basic Usage

# Check test results for current distribution
divekit passcheck

# Check specific distribution
divekit passcheck --distribution my-assignment

Detailed Analysis

# Show detailed results per student
divekit passcheck --detail

# Generate Excel report
divekit passcheck --report

# Both detailed and report
divekit passcheck --detail --report

Custom Output

# Save reports to custom directory
divekit passcheck --report --output-path ./my-reports/

# Use specific GitLab instance
divekit passcheck --remote https://gitlab.example.com --token glpat-xxxxx

Output Format

Summary View (Default)

Distribution: my-assignment
Test Results Summary:
├── Total Students: 25
├── Passed: 20 (80%)
├── Failed: 3 (12%)
└── Not Submitted: 2 (8%)

Recent Activity:
├── alice.jones: PASSED (2 hours ago)
├── bob.smith: FAILED (4 hours ago)
└── charlie.brown: PASSED (1 day ago)

Detailed View (--detail)

Distribution: my-assignment
Detailed Test Results:

Student: alice.jones
├── Status: PASSED
├── Test Suites: 5/5
├── Last Run: 2024-01-15 14:30:00
└── Test Details:
    ├── Unit Tests: 25/25 passed
    ├── Integration Tests: 8/8 passed
    └── Code Quality: 95% score

Student: bob.smith
├── Status: FAILED
├── Test Suites: 3/5
├── Last Run: 2024-01-15 10:15:00
└── Test Details:
    ├── Unit Tests: 20/25 passed
    ├── Integration Tests: 2/8 passed
    └── Code Quality: 78% score

Report Generation

When using --report, the command generates an Excel file with:

• Student overview with pass/fail status
• Detailed test results per student
• Historical trends and statistics
• Charts and visualizations
• Timestamp and metadata

Prerequisites

• Secure pipeline must be enabled in the distribution configuration
• Test repositories must exist and be accessible
• Valid GitLab token with API access
• Network connectivity to GitLab instance

Integration

The passcheck command integrates with:

• Secure Pipeline: Works with test repositories created by divekit distribute
• CI/CD Systems: Reads results from automated test pipelines
• GitLab API: Fetches test results and repository information
• Excel Generation: Creates formatted reports for instructors

10 - divekit update

Status: Planned

The divekit update command is planned but not yet implemented in the current CLI. When implemented, this command is intended to:

• Check the currently installed Divekit CLI version
• Compare against the latest available release
• Offer a non-interactive flag to auto-apply updates
• Provide clear logs and exit codes suitable for CI usage

Planned flags (subject to change):

• -y, --yes — Auto-confirm applying an available update
• --check — Only check and print the current/latest versions without applying

Current approach:

• Download the latest binary from the releases page and re-run divekit install
• Verify installation with:

  divekit --version
  

Release downloads:

• https://gitlab.git.nrw/divekit/divekit-cli/-/tags

11 - divekit run

Execute a single Lua script for custom automation. The command resolves a script by name from trusted directories or accepts an absolute path.

Usage

divekit run <script|/absolute/path/to/script.lua>

• Exactly one argument is required.
• When a name (without path) is provided, Divekit searches in trusted directories.
• When an absolute path is provided, the script is executed directly (if it exists and is a .lua file).

Script Resolution

Resolution happens in this order:

1. Absolute path (when you pass an absolute path)

• Accepted as-is if it points to an existing .lua file.

2. Trusted directories in the current Divekit project (highest priority)

• .divekit/scripts/
• .divekit/lua/
• .divekit/hooks/

3. Trusted directories in the user’s home

• ~/.divekit/scripts/
• ~/.divekit/lua/
• ~/.divekit/hooks/

For name-only arguments (e.g., my-script), Divekit will try both my-script and my-script.lua in each trusted directory.

Security and Guards

• Only .lua files are executed.
• Symlinks are resolved and the resolved path must remain within the trusted root being checked (prevents path traversal).
• Relative paths are not executed directly; they must resolve from trusted directories.

Examples

Run by name (search in trusted locations)

# Looks up ".divekit/scripts/my-script.lua", then other trusted directories
divekit run my-script

Run by name with extension

divekit run my-script.lua

Run by absolute path

divekit run /full/path/to/my-script.lua

Run a script from the user’s home

# If placed under ~/.divekit/lua/report.lua
divekit run report

Troubleshooting

• Script not found:
  • Ensure the file exists in one of the trusted directories or pass an absolute path.
  • If using a name, try adding the .lua extension.
• Permission denied:
  • Check file permissions and ownership of the script file.
• Wrong file type:
  • Only .lua files are accepted.

Notes

• This command executes a single Lua file; there are no additional subcommands or flags for run.
• If your script depends on project context, run the command from inside a Divekit project (a directory that contains .divekit/).