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
`

In addition, you can enable autocomplete.

Autocomplete

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

`bash
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:
`bash
kradle challenge # 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:
`bash
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

$3

Create a new challenge locally and in the cloud:

`bash
kradle challenge create
`

This creates a challenges// folder with:
- challenge.ts: The entrypoint defining challenge behavior
- config.ts: TypeScript file with challenge metadata (auto-generated from cloud API)

$3

Build, validate, and upload challenge datapack:

`bash
kradle challenge build
kradle challenge build --no-validate # Skip validation
kradle challenge build --public # Upload as public
kradle challenge build --all # Build all local challenges
`

This command:
1. Creates the challenge in the cloud (if it doesn't already exist)
2. Builds the datapack by executing challenge.ts
3. Validates the datapack using Spyglass (blocks upload if errors found)
4. Uploads config.ts to cloud
5. Uploads the datapack to GCS

Validation checks .mcfunction files for syntax errors, invalid commands, and other issues. Use --no-validate to skip this step.

$3

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

`bash


Will ask confirmation for local & cloud deletion

kradle challenge delete

Doesn't ask for confirmation

kradle challenge delete --yes
`

$3

List all challenges (local and cloud):

`bash
kradle challenge list
`

$3

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

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

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

$3

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

`bash
kradle challenge watch
kradle challenge watch --no-validate # Skip validation
kradle challenge watch --verbose # Verbose output
`

Uses file watching with debouncing (1 second) and hash comparison to minimize unnecessary rebuilds. Validation runs after each build but doesn't block uploads in watch mode (errors are displayed but the upload continues).

$3

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

`bash


Interactive mode - prompts for agent selection

kradle challenge run

Inline agent specification

kradle challenge run 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 --studio # Run in local studio environment
kradle challenge run : # Run a public challenge from another team
kradle challenge run --no-open # Don't open browser
kradle challenge run --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.

$3

List your recent runs:

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

$3

Get details and logs for a specific run:

`bash
kradle challenge runs get
kradle challenge runs get --no-logs # Skip fetching logs
kradle challenge runs get --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.

$3

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

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

$3

Create a new experiment with a template config file:

`bash
kradle experiment create
`

This creates experiments//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

$3

Execute or resume an experiment:

`bash
kradle experiment run # Resume current version or create first one
kradle experiment run --new-version # Start a new version
kradle experiment run --max-concurrent 10 # Control parallelism (default: 5)
kradle experiment run --download-recordings # Auto-download recordings as runs complete
kradle experiment run --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

$3

Download gameplay recordings from completed experiment runs:

`bash
kradle experiment recordings # Interactive selection of run and participant
kradle experiment recordings # Download specific run
kradle experiment recordings --all # Download all runs and participants
kradle experiment recordings --version 2 # Download from specific version
kradle experiment recordings --all # Download all participants for a run
`

Recordings are saved to experiments//versions//recordings//.

$3

Download logs and run results from completed experiment runs:

`bash
kradle experiment logs # Interactive selection of run
kradle experiment logs # Download specific run
kradle experiment logs --all # Download all runs
kradle experiment logs --version 2 # Download from specific version
`

Files are saved to experiments//versions//logs//:
- run.json - Run result with status, end_state, and participant results
- logs.json - Log entries from the run

$3

List all local experiments:

`bash
kradle experiment list
`

World Commands

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

$3

Import a Minecraft world folder from your local filesystem:

`bash
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.

$3

Upload world config and tarball to the cloud:

`bash
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
`

$3

Download a world from the cloud:

`bash
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
`

$3

List all worlds (local and cloud):

`bash
kradle world list
`

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

$3

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

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

$3

Each world has a config.ts file in worlds//config.ts. You can define named locations with coordinates:

`typescript
export const config = {
name: "My World",
description: "A custom Minecraft world",
domain: "minecraft",
worldConfig: {
locations: {
spawn: {
name: "Spawn Point",
coordinates: { x: 0, y: 64, z: 0 }
},
goal: {
name: "Goal Location",
coordinates: { x: 100, y: 70, z: 200 }
}
}
}
};
`

Locations are synced to the cloud when you push the world.

Agent Commands

$3

List all agents registered in the system:

`bash
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.

$3

Output the CLI reference documentation:

`bash
kradle ai-docs cli
`

$3

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

`bash
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

$3

This CLI requires linking to be used locally:

`bash
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




$3

`bash
npm run build # Compile TypeScript to dist/
npm run lint # Check for linting issues
npm run format # Format code + auto-fix linting issues with Biome
`

$3

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)

`bash
cp .env.test.example .env.test


Edit .env.test and add your API key


`

Run tests:

`bash
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.

$3

Each challenge is a folder in challenges// 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 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 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

$3

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