Kradle CLI

Kradle's CLI for managing Minecraft challenges, experiments, agents, and more!

• Installation
• Autocomplete
• Configuration
• Challenge
• Experiments
• Worlds
• Agents
• AI Docs
• Publishing a New Version
• Development
• Architecture

Installation

Make sure you have NodeJS 22.18 or higher installed.

1. Install Kradle's CLI globally

npm i -g kradle@latest

2. Initialize a new directory to store challenges, and other Kradle resources:

kradle init

3. Congrats 🎉 You can now create a new challenge:

kradle challenge create <challenge-name>

In addition, you can enable autocomplete.

Autocomplete

Kradle CLI supports shell autocomplete for faster command entry. After installation, enable autocomplete for your shell:

kradle autocomplete
# Follow the instructions printed

The command will display instructions for your specific shell.

After setup, you will be able to use Tab to autocomplete:

kradle challenge <TAB>        # Shows: build, create, list, run, upload, watch, etc.

Configuration

The CLI requires a .env file with your Kradle API key and environment settings.

For new projects: Run kradle init which will prompt for your API key and create the .env automatically.

Manual setup: Create a .env file in your project root:

KRADLE_API_KEY=your-api-key-here
KRADLE_API_URL=https://dev.kradle.ai/api

Get your API key at: https://dev.kradle.ai/settings#api-keys

Challenge Commands

Create Challenge

Create a new challenge locally and in the cloud:

kradle challenge create <challenge-name>

This creates a challenges/<challenge-name>/ folder with:

• challenge.ts: The entrypoint defining challenge behavior
• config.ts: TypeScript file with challenge metadata (auto-generated from cloud API)

Build Challenge

Build challenge datapack and upload both config and datapack:

kradle challenge build <challenge-name>

This command:

1. Creates the challenge in the cloud (if it doesn't already exists)
2. Uploads config.ts to cloud (if it exists)
3. Builds the datapack by executing challenge.ts
4. Uploads the datapack to GCS

Delete Challenge

Delete a challenge locally, from the cloud, or both:

# Will ask confirmation for local & cloud deletion
kradle challenge delete <challenge-name>

# Doesn't ask for confirmation
kradle challenge delete <challenge-name> --yes

List Challenges

List all challenges (local and cloud):

kradle challenge list

Pull Challenge

Download a challenge from the cloud and extract source files locally:

kradle challenge pull                                  # Interactive selection
kradle challenge pull <challenge-name>                 # Pull your own challenge
kradle challenge pull <team-name>:<challenge-name>     # Pull a public challenge from another team
kradle challenge pull <challenge-name> --yes           # Skip confirmation when overwriting

This downloads the challenge tarball, extracts challenge.ts and config.ts, and builds the datapack locally.

Watch Challenge

Watch a challenge for changes and auto-rebuild/upload:

kradle challenge watch <challenge-name>

Uses file watching with debouncing (300ms) and hash comparison to minimize unnecessary rebuilds.

Run Challenge

Run a challenge with agents specified inline or via interactive selection:

# Interactive mode - prompts for agent selection
kradle challenge run <challenge-name>

# Inline agent specification
kradle challenge run <challenge-name> team-kradle:gemini-3-flash,team-kradle:grok-4-1-fast

# Team-based challenge with roles
kradle challenge run capture-the-flag \
  red=team-kradle:gemini-3-flash \
  blue=team-kradle:claude-sonnet-4

# Other options
kradle challenge run <challenge-name> --studio     # Run in local studio environment
kradle challenge run <team-name>:<challenge-name>  # Run a public challenge from another team
kradle challenge run <challenge-name> --no-open    # Don't open browser
kradle challenge run <challenge-name> --no-wait    # Fire and forget (don't wait for completion)

Inline Agent Syntax:

• agent1,agent2 - Assign agents to the "default" role
• role=agent1,agent2 - Assign agents to a specific role
• Same role can be specified multiple times and agents are merged

When no agents are specified, the command enters interactive mode, fetching the challenge configuration and prompting for agent selection for each role.

By default, the command opens the run URL in your browser and polls until the run completes, then displays the outcome.

List Runs

List your recent runs:

kradle challenge runs list              # List 10 most recent runs
kradle challenge runs list --limit 20   # List 20 most recent runs

Get Run Details

Get details and logs for a specific run:

kradle challenge runs get <run-id>
kradle challenge runs get <run-id> --no-logs      # Skip fetching logs
kradle challenge runs get <run-id> --no-summary   # Skip AI summary

This displays:

• Run metadata (status, duration, end state)
• Participant results (agent, winner status, score)
• AI-generated summary (unless --no-summary is used)
• Log entries with timestamps and levels (unless --no-logs is used)

Experiment Commands

Experiments allow you to run batches of challenge runs with different agents and configurations, then analyze the results. This is useful for benchmarking agents, testing challenge difficulty, or gathering statistics across many runs.

Concepts

Experiment: A named collection of run configurations defined in a config.ts file. Each experiment lives in experiments/<name>/.

Version: A snapshot of an experiment execution. When you run an experiment, it creates a version containing:

• A copy of the config.ts at that point in time
• A manifest.json with the generated list of runs
• A progress.json tracking the status of each run

Versions are stored in experiments/<name>/versions/001/, 002/, etc. This allows you to:

• Resume an interrupted experiment from where it left off
• Re-run the same experiment with --new to create a fresh version
• Compare results across different versions

Create Experiment

Create a new experiment with a template config file:

kradle experiment create <name>

This creates experiments/<name>/config.ts with a template that you can customize. The config exports a main() function that returns a manifest with:

• runs: Array of run configurations (challenge + participants)
• tags: Optional tags applied to all runs for filtering in analytics

Run Experiment

Execute or resume an experiment:

kradle experiment run <name>                       # Resume current version or create first one
kradle experiment run <name> --new-version         # Start a new version
kradle experiment run <name> --max-concurrent 10   # Control parallelism (default: 5)
kradle experiment run <name> --download-recordings # Auto-download recordings as runs complete
kradle experiment run <name> --download-logs       # Auto-download logs as runs complete

The run command:

1. Creates a new version (or resumes the current one)
2. Generates a manifest by executing config.ts
3. Displays an interactive TUI showing run progress
4. Saves progress periodically (allows resuming if interrupted)
5. Opens Metabase dashboard with results when complete

Download Recordings

Download gameplay recordings from completed experiment runs:

kradle experiment recordings <name>                  # Interactive selection of run and participant
kradle experiment recordings <name> <run-id>         # Download specific run
kradle experiment recordings <name> --all            # Download all runs and participants
kradle experiment recordings <name> --version 2      # Download from specific version
kradle experiment recordings <name> <run-id> --all   # Download all participants for a run

Recordings are saved to experiments/<name>/versions/<version>/recordings/<run-id>/.

Download Logs

Download logs and run results from completed experiment runs:

kradle experiment logs <name>                  # Interactive selection of run
kradle experiment logs <name> <run-id>         # Download specific run
kradle experiment logs <name> --all            # Download all runs
kradle experiment logs <name> --version 2      # Download from specific version

Files are saved to experiments/<name>/versions/<version>/logs/<run-id>/:

• run.json - Run result with status, end_state, and participant results
• logs.json - Log entries from the run

List Experiments

List all local experiments:

kradle experiment list

World Commands

Worlds are Minecraft world saves that can be used as starting points for challenges.

Import World

Import a Minecraft world folder from your local filesystem:

kradle world import ~/minecraft/saves/MyWorld              # Auto-generate slug from folder name
kradle world import ~/minecraft/saves/MyWorld --as my-world  # Specify custom slug

This validates the folder contains level.dat, packages it as a tarball, creates a config.ts, and uploads to the cloud.

Push World

Upload world config and tarball to the cloud:

kradle world push my-world                     # Push single world
kradle world push my-world another-world       # Push multiple worlds
kradle world push --all                        # Push all local worlds
kradle world push my-world --public            # Push and set visibility to public

Pull World

Download a world from the cloud:

kradle world pull                              # Interactive selection
kradle world pull my-world                     # Pull specific world
kradle world pull username:their-world         # Pull from another user
kradle world pull my-world --yes               # Skip confirmation when overwriting

List Worlds

List all worlds (local and cloud):

kradle world list

Shows sync status for each world (synced, cloud only, or local only).

Delete World

Delete a world locally, from the cloud, or both:

kradle world delete my-world          # Interactive confirmation
kradle world delete my-world --yes    # Skip confirmation

Agent Commands

List Agents

List all agents registered in the system:

kradle agent list

AI Docs Commands

Output LLM-focused documentation to stdout. These commands are designed to provide AI agents with comprehensive reference material about the Kradle CLI and API.

CLI Reference

Output the CLI reference documentation:

kradle ai-docs cli

Challenges SDK Reference

Output the API reference documentation for the @kradle/challenges-sdk package:

kradle ai-docs challenges-sdk              # Uses locally installed or latest version
kradle ai-docs challenges-sdk 0.2.1        # Uses specific version

This fetches the documentation from unpkg.com, matching the SDK version in your project.

Publishing a New Version

The CLI uses GitHub Actions for automated releases. To publish a new version:

1. Go to Actions in the GitHub repository
2. Select "Create Release PR" workflow from the sidebar
3. Click "Run workflow" and choose the release type:
   • patch - Bug fixes (0.0.5 → 0.0.6)
   • minor - New features (0.0.5 → 0.1.0)
   • major - Breaking changes (0.0.5 → 1.0.0)
4. Review and merge the automatically created PR
5. Done! The package is automatically published to npm when the PR is merged

Development

Setup

This CLI requires linking to be used locally:

npm install
npm run build
npm link

The repository provides the kradle CLI command. It runs compiled JavaScript from dist/:

• It requires running npm run build after every code change
• You can use npm run watch to make sure your code automatically recompiles after any change

Build & Lint

npm run build              # Compile TypeScript to dist/
npm run lint               # Check for linting issues
npm run lint:fix           # Auto-fix linting issues
npm run format             # Format code with Biome

Running Tests

The CLI has integration tests that verify commands work correctly with the dev API.

Setup:

1. Copy .env.test.example to .env.test
2. Add your Kradle API key (from https://dev.kradle.ai/settings/api-keys)

cp .env.test.example .env.test
# Edit .env.test and add your API key

Run tests:

npm test                   # Run all tests
npm run test:watch         # Run tests in watch mode
npm run test:integration   # Run integration tests

Note: Integration tests make real API calls to the dev environment and may create/delete challenges.

CI Configuration: Integration tests run in GitHub Actions on PRs. The KRADLE_API_KEY secret must be configured in the repository settings.

Challenge Structure

Each challenge is a folder in challenges/<slug>/ containing:

• challenge.ts: Entrypoint that defines challenge behavior using the Sandstone API
• config.ts: TypeScript file exporting challenge metadata (name, visibility, roles, objectives, etc.)

Workflow:

1. kradle challenge create <slug> creates the folder with challenge.ts
2. The create command automatically builds, uploads, and downloads the config from the cloud API
3. The downloaded JSON is converted into a typed TypeScript config.ts file
4. kradle challenge build <slug> automatically uploads config.ts (if it exists) before building the datapack
5. You can modify config.ts locally and run build to sync changes to the cloud

Architecture

The CLI is built with:

• oclif: CLI framework
• enquirer: Interactive prompts
• listr2: Task list UI
• ink: React-based terminal UI (for experiments)
• react: UI components for ink
• picocolors: Terminal colors
• zod: Schema validation
• chokidar: File watching
• biome: Linting and formatting

Project Structure

kradle-cli/
├── src/
│   ├── commands/             # CLI commands
│   │   ├── agent/            # Agent commands
│   │   ├── ai-docs/          # AI documentation commands
│   │   ├── challenge/        # Challenge management commands
│   │   │   └── runs/         # Run listing and logs commands
│   │   ├── experiment/       # Experiment commands
│   │   └── world/            # World management commands
│   └── lib/                  # Core libraries
│       └── experiment/       # Experiment system
├── tests/                    # Integration tests
│   ├── helpers/              # Test utilities
│   └── integration/          # Integration test suites
│       ├── challenge/        # Challenge command tests
│       ├── experiment/       # Experiment command tests
│       └── world/            # World command tests
└── static/                   # Template files
    └── project_template/     # Files for kradle init