kradle 0.3.3 → 0.4.0

package/README.md

@@ -18,18 +18,19 @@ Kradle's CLI for managing Minecraft challenges, experiments, agents, and more!
 
 ## Installation
 
+Make sure you have [NodeJS 22.18 or higher](https://nodejs.org/en/download/current) installed.
+
 1. Install Kradle's CLI globally
 ```
 npm i -g kradle
 ```
-2. Initialize a new directory to store challenges and experiments
+2. Initialize a new directory to store challenges, and other Kradle resources:
 ```
 kradle init
 ```
-3. Congrats 🎉 You can now create a new challenge or a new experiment:
+3. Congrats 🎉 You can now create a new challenge:
 ```
 kradle challenge create <challenge-name>
-kradle experiment create <experiment-name>
 ```
 
 In addition, you can enable [autocomplete](#Autocomplete).
@@ -184,6 +185,7 @@ kradle experiment run <name>                       # Resume current version or c
 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:
@@ -207,6 +209,21 @@ kradle experiment recordings <name> <run-id> --all   # Download all participants
 
 Recordings are saved to `experiments/<name>/versions/<version>/recordings/<run-id>/`.
 
+### Download Logs
+
+Download logs and run results from completed experiment runs:
+
+```bash
+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:

package/dist/commands/challenge/list.js

@@ -13,13 +13,14 @@ export default class List extends Command {
         const { flags } = await this.parse(List);
         const api = new ApiClient(flags["api-url"], flags["api-key"]);
         this.log(pc.blue(">> Loading challenges..."));
-        const [cloudChallenges, localChallenges, human] = await Promise.all([
+        const [cloudChallenges, kradleChallenges, localChallenges, human] = await Promise.all([
             api.listChallenges(),
+            api.listKradleChallenges(),
             Challenge.getLocalChallenges(),
             api.getHuman(),
         ]);
-        // Create a map for easy lookup
-        const cloudMap = new Map(cloudChallenges.map((c) => [c.slug, c]));
+        // Create a map for easy lookup (user's challenges + team-kradle challenges)
+        const cloudMap = new Map([...cloudChallenges, ...kradleChallenges].map((c) => [c.slug, c]));
         const allSlugs = new Set([...cloudMap.keys(), ...localChallenges.map((id) => `${human.username}:${id}`)]);
         this.log(pc.bold("\nChallenges:\n"));
         this.log(`${"Status".padEnd(15)} ${"Slug".padEnd(40)} ${"Name".padEnd(30)}`);

package/dist/commands/challenge/pull.js

@@ -1,14 +1,12 @@
 import { existsSync } from "node:fs";
 import fs from "node:fs/promises";
-import path from "node:path";
 import { Command, Flags } from "@oclif/core";
 import enquirer from "enquirer";
 import { Listr } from "listr2";
 import pc from "picocolors";
-import * as tar from "tar";
 import { ApiClient } from "../../lib/api-client.js";
 import { extractShortSlug, getChallengeSlugArgument } from "../../lib/arguments.js";
-import { Challenge, SOURCE_FOLDER } from "../../lib/challenge.js";
+import { Challenge } from "../../lib/challenge.js";
 import { getConfigFlags } from "../../lib/flags.js";
 export default class Pull extends Command {
     static description = "Pull a challenge from the cloud and extract source files locally";
@@ -97,67 +95,16 @@ export default class Pull extends Command {
                 return;
             }
         }
-        const tempTarballPath = path.join(flags["challenges-path"], `${challenge.shortSlug}-pull-temp.tar.gz`);
         const tasks = new Listr([
             {
-                title: "Downloading challenge",
-                task: async (_, task) => {
-                    const { downloadUrl } = await api.getChallengeDownloadUrl(challengeSlug);
-                    const response = await fetch(downloadUrl);
-                    if (!response.ok) {
-                        throw new Error(`Failed to download: ${response.status} ${response.statusText}`);
-                    }
-                    const buffer = await response.arrayBuffer();
-                    await fs.mkdir(path.dirname(tempTarballPath), { recursive: true });
-                    await fs.writeFile(tempTarballPath, Buffer.from(buffer));
-                    task.title = "Downloaded challenge";
-                },
-            },
-            {
-                title: "Creating challenge directory",
+                title: "Downloading and extracting source files",
                 task: async (_, task) => {
                     await fs.mkdir(challenge.challengeDir, { recursive: true });
-                    task.title = `Created directory: ${challenge.challengeDir}`;
-                },
-            },
-            {
-                title: "Extracting source files",
-                task: async (_, task) => {
-                    const filesToExtract = [`${SOURCE_FOLDER}/challenge.ts`, `${SOURCE_FOLDER}/config.ts`];
-                    const tempExtractDir = path.join(flags["challenges-path"], `${challenge.shortSlug}-extract-temp`);
-                    await fs.mkdir(tempExtractDir, { recursive: true });
-                    try {
-                        await tar.extract({
-                            file: tempTarballPath,
-                            cwd: tempExtractDir,
-                            filter: (entryPath) => filesToExtract.some((f) => entryPath === f),
-                        });
-                        const srcChallengeTs = path.join(tempExtractDir, SOURCE_FOLDER, "challenge.ts");
-                        const srcConfigTs = path.join(tempExtractDir, SOURCE_FOLDER, "config.ts");
-                        let extractedCount = 0;
-                        if (existsSync(srcChallengeTs)) {
-                            await fs.copyFile(srcChallengeTs, challenge.challengePath);
-                            extractedCount++;
-                        }
-                        if (existsSync(srcConfigTs)) {
-                            await fs.copyFile(srcConfigTs, challenge.configPath);
-                            extractedCount++;
-                        }
-                        if (extractedCount === 0) {
-                            throw new Error(`No source files found in tarball. The challenge may not have been built with source files.`);
-                        }
-                        task.title = `Extracted ${extractedCount} source file(s)`;
+                    const extractedCount = await Challenge.downloadSourceFiles(api, challengeSlug, challenge.challengeDir);
+                    if (extractedCount === 0) {
+                        throw new Error("No source files found in tarball. The challenge may not have been built with source files.");
                     }
-                    finally {
-                        await fs.rm(tempExtractDir, { recursive: true, force: true });
-                    }
-                },
-            },
-            {
-                title: "Cleaning up",
-                task: async (_, task) => {
-                    await fs.rm(tempTarballPath, { force: true });
-                    task.title = "Cleaned up temporary files";
+                    task.title = `Extracted ${extractedCount} source file(s)`;
                 },
             },
             {
@@ -175,7 +122,6 @@ export default class Pull extends Command {
             this.log(pc.dim(`  → config.ts: ${challenge.configPath}`));
         }
         catch (error) {
-            await fs.rm(tempTarballPath, { force: true }).catch(() => { });
             this.error(pc.red(`Pull failed: ${error instanceof Error ? error.message : String(error)}`));
         }
     }

package/dist/commands/challenge/watch.js

@@ -33,6 +33,9 @@ export default class Watch extends Command {
             // Clear screen before subsequent rebuilds for clean output
             clearScreen();
             this.log(pc.cyan(`\n  Rebuild started...\n`));
+            // Track if config changed so we can force tarball re-upload
+            // (tarball includes source files which contain config.ts)
+            let configChanged = false;
             const tasks = new Listr([
                 {
                     title: "Checking configuration",
@@ -42,6 +45,7 @@ export default class Watch extends Command {
                             task.title = "Uploading configuration";
                             await api.updateChallenge(challenge.shortSlug, newConfig, "private");
                             lastConfig = newConfig;
+                            configChanged = true;
                             task.title = "Configuration uploaded";
                         }
                         else {
@@ -61,7 +65,8 @@ export default class Watch extends Command {
                     title: "Checking datapack changes",
                     task: async (_ctx, task) => {
                         const newHash = await challenge.getDatapackHash();
-                        if (newHash !== lastHash) {
+                        // Upload if datapack changed OR if config changed (since tarball includes source files)
+                        if (newHash !== lastHash || configChanged) {
                             task.title = "Uploading datapack";
                             await api.uploadChallengeDatapack(challenge.shortSlug, challenge.tarballPath);
                             lastHash = newHash;

package/dist/commands/experiment/logs.d.ts

@@ -0,0 +1,18 @@
+import { Command } from "@oclif/core";
+export default class Logs extends Command {
+    static description: string;
+    static examples: string[];
+    static args: {
+        experimentName: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+        runId: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;
+    };
+    static flags: {
+        "api-key": import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        "api-url": import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        all: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        version: import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+    private downloadForExperiment;
+    private downloadLogs;
+}

package/dist/commands/experiment/logs.js

@@ -0,0 +1,220 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { Args, Command, Flags } from "@oclif/core";
+import enquirer from "enquirer";
+import { Listr } from "listr2";
+import pc from "picocolors";
+import { ApiClient } from "../../lib/api-client.js";
+import { Experimenter } from "../../lib/experiment/experimenter.js";
+import { getConfigFlags } from "../../lib/flags.js";
+// Get all versions for an experiment
+async function getAllVersions(experimentDir) {
+    const versionsDir = path.join(experimentDir, "versions");
+    try {
+        const entries = await fs.readdir(versionsDir, { withFileTypes: true });
+        return entries
+            .filter((e) => e.isDirectory())
+            .map((e) => parseInt(e.name, 10))
+            .filter((n) => !Number.isNaN(n))
+            .sort((a, b) => a - b);
+    }
+    catch {
+        return [];
+    }
+}
+export default class Logs extends Command {
+    static description = "Download logs from an experiment run";
+    static examples = [
+        "<%= config.bin %> <%= command.id %> my-experiment",
+        "<%= config.bin %> <%= command.id %> my-experiment <run-id>",
+        "<%= config.bin %> <%= command.id %> my-experiment --all",
+        "<%= config.bin %> <%= command.id %> my-experiment --version 2",
+        "<%= config.bin %> <%= command.id %> my-experiment --version 1 --all",
+    ];
+    static args = {
+        experimentName: Args.string({
+            description: "Experiment name",
+            required: true,
+        }),
+        runId: Args.string({
+            description: "Specific run ID to download logs from (optional)",
+            required: false,
+        }),
+    };
+    static flags = {
+        all: Flags.boolean({
+            description: "Download logs for all runs",
+            default: false,
+        }),
+        version: Flags.integer({
+            description: "Specific experiment version to download logs from (e.g., 0, 1, 2)",
+            required: false,
+        }),
+        ...getConfigFlags("api-key", "api-url"),
+    };
+    async run() {
+        const { args, flags } = await this.parse(Logs);
+        const api = new ApiClient(flags["api-url"], flags["api-key"]);
+        const { experimentName, runId } = args;
+        await this.downloadForExperiment(experimentName, runId, api, flags.all, flags.version);
+    }
+    async downloadForExperiment(experimentName, runId, api, all, version) {
+        const experimenter = new Experimenter(experimentName, "", api);
+        // Check if experiment exists
+        if (!(await experimenter.exists())) {
+            this.error(pc.red(`Experiment '${experimentName}' does not exist. Run 'kradle experiment list' to see available experiments.`));
+        }
+        const experimentDir = experimenter.experimentDir;
+        // Get all versions
+        const allVersions = await getAllVersions(experimentDir);
+        if (allVersions.length === 0) {
+            this.error(pc.red("No experiment versions found. Run the experiment first."));
+        }
+        // Default to latest version if not specified
+        let targetVersion;
+        if (version !== undefined) {
+            if (!allVersions.includes(version)) {
+                this.error(pc.red(`Version ${version} not found in experiment '${experimentName}'. ` +
+                    `Available versions: ${allVersions.join(", ")}`));
+            }
+            targetVersion = version;
+            this.log(pc.blue(`>> Filtering to version ${version}`));
+        }
+        else {
+            // Default to latest version
+            targetVersion = Math.max(...allVersions);
+        }
+        const allRunInfos = [];
+        const completedStatuses = new Set(["completed", "finished", "game_over"]);
+        const progressPath = path.join(experimentDir, "versions", targetVersion.toString().padStart(3, "0"), "progress.json");
+        try {
+            const progressData = await fs.readFile(progressPath, "utf-8");
+            const progress = JSON.parse(progressData);
+            for (const entry of progress.entries) {
+                // Only include runs that are completed (exclude in-progress, queued, or error runs)
+                if (entry.runId && completedStatuses.has(entry.status)) {
+                    allRunInfos.push({
+                        version: targetVersion,
+                        runId: entry.runId,
+                        index: entry.index,
+                        status: entry.status,
+                        participantIds: entry.participantIds,
+                    });
+                }
+            }
+        }
+        catch { }
+        if (allRunInfos.length === 0) {
+            this.error(pc.yellow("No completed runs found. Wait for runs to finish or run the experiment first."));
+        }
+        let selectedRuns;
+        if (all && !runId) {
+            // Download all runs (--all without specific run)
+            selectedRuns = allRunInfos;
+            this.log(pc.blue(`>> Downloading logs for all ${selectedRuns.length} runs`));
+        }
+        else if (runId) {
+            // Find specific run by ID
+            const matchingRun = allRunInfos.find((r) => r.runId === runId);
+            if (!matchingRun) {
+                this.error(pc.red(`Run ID '${runId}' not found in experiment '${experimentName}'. ` +
+                    `Run 'kradle experiment logs ${experimentName}' to see available runs.`));
+            }
+            selectedRuns = [matchingRun];
+            this.log(pc.blue(`>> Downloading logs for run: ${runId}`));
+        }
+        else {
+            // Interactive run selection
+            const choices = [
+                // Only show "All runs" option if there are multiple runs
+                ...(allRunInfos.length > 1
+                    ? [
+                        {
+                            name: "all",
+                            message: `All runs (${allRunInfos.length} total)`,
+                            hint: "Download all",
+                        },
+                    ]
+                    : []),
+                ...allRunInfos.map((run) => {
+                    const participants = run.participantIds?.join(", ") || "No participants";
+                    return {
+                        name: run.runId,
+                        message: `${participants} - ${run.runId}`,
+                        hint: run.status,
+                    };
+                }),
+            ];
+            const { selectedRunId } = await enquirer.prompt({
+                type: "select",
+                name: "selectedRunId",
+                message: "Select a run to download logs from",
+                choices,
+            });
+            if (selectedRunId === "all") {
+                selectedRuns = allRunInfos;
+                this.log(pc.blue(`>> Downloading logs for all ${selectedRuns.length} runs`));
+            }
+            else {
+                const selectedRun = allRunInfos.find((r) => r.runId === selectedRunId);
+                if (!selectedRun) {
+                    this.error(pc.red("Selected run not found."));
+                }
+                selectedRuns = [selectedRun];
+            }
+        }
+        // Build download targets
+        const downloadTargets = selectedRuns.map((run) => ({
+            version: run.version,
+            runId: run.runId,
+            experimentDir,
+        }));
+        this.log(pc.blue(`>> Fetching and downloading logs for ${downloadTargets.length} run(s)...`));
+        await this.downloadLogs(api, downloadTargets);
+        const logsDir = path.join(experimentDir, "versions", targetVersion.toString().padStart(3, "0"), "logs");
+        this.log(pc.green(`\n Downloaded logs for ${downloadTargets.length} run(s) to ${logsDir}`));
+    }
+    async downloadLogs(api, targets) {
+        const allTasks = [];
+        for (const target of targets) {
+            const { version, runId, experimentDir } = target;
+            allTasks.push({
+                title: `${runId}`,
+                task: async (_, task) => {
+                    const runDir = path.join(experimentDir, "versions", version.toString().padStart(3, "0"), "logs", runId);
+                    const runPath = path.join(runDir, "run.json");
+                    const logsPath = path.join(runDir, "logs.json");
+                    // Fetch run result
+                    let runResult;
+                    try {
+                        runResult = await api.getRunResult(runId);
+                    }
+                    catch (error) {
+                        throw new Error(`Failed to fetch run result: ${error instanceof Error ? error.message : String(error)}`);
+                    }
+                    // Fetch logs
+                    let logs = [];
+                    try {
+                        logs = await api.getRunLogs(runId);
+                    }
+                    catch (error) {
+                        throw new Error(`Failed to fetch logs: ${error instanceof Error ? error.message : String(error)}`);
+                    }
+                    // Save run result and logs
+                    await fs.mkdir(runDir, { recursive: true });
+                    await fs.writeFile(runPath, JSON.stringify(runResult, null, 2));
+                    await fs.writeFile(logsPath, JSON.stringify(logs, null, 2));
+                    task.title = `${runId} (${logs.length} log entries)`;
+                },
+            });
+        }
+        if (allTasks.length === 0) {
+            return;
+        }
+        const tasks = new Listr(allTasks, {
+            concurrent: 3,
+            exitOnError: false,
+        });
+        await tasks.run();
+    }
+}

package/dist/commands/experiment/run.d.ts

@@ -12,6 +12,7 @@ export default class Run extends Command {
         "new-version": import("@oclif/core/interfaces").BooleanFlag<boolean>;
         "max-concurrent": import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
         "download-recordings": import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        "download-logs": import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     run(): Promise<void>;
 }

package/dist/commands/experiment/run.js

@@ -33,6 +33,11 @@ export default class Run extends Command {
             description: "Automatically download recordings after each run finishes",
             default: false,
         }),
+        "download-logs": Flags.boolean({
+            char: "l",
+            description: "Automatically download logs after each run finishes",
+            default: false,
+        }),
         ...getConfigFlags("api-key", "api-url", "web-url"),
     };
     async run() {
@@ -57,6 +62,7 @@ export default class Run extends Command {
                 maxConcurrent: flags["max-concurrent"],
                 openMetabase: true,
                 downloadRecordings: flags["download-recordings"],
+                downloadLogs: flags["download-logs"],
             });
             this.log(pc.green("\n✓ Experiment complete!"));
         }

package/dist/commands/world/list.js

@@ -13,12 +13,13 @@ export default class List extends Command {
         const { flags } = await this.parse(List);
         const api = new ApiClient(flags["api-url"], flags["api-key"]);
         this.log(pc.blue(">> Loading worlds..."));
-        const [cloudWorlds, localWorlds, human] = await Promise.all([
+        const [cloudWorlds, kradleWorlds, localWorlds, human] = await Promise.all([
             api.listWorlds(),
+            api.listKradleWorlds(),
             World.getLocalWorlds(),
             api.getHuman(),
         ]);
-        const cloudMap = new Map(cloudWorlds.map((w) => [w.slug, w]));
+        const cloudMap = new Map([...cloudWorlds, ...kradleWorlds].map((w) => [w.slug, w]));
         const allSlugs = new Set([...cloudMap.keys(), ...localWorlds.map((slug) => `${human.username}:${slug}`)]);
         this.log(pc.bold("\nWorlds:\n"));
         this.log(`${"Status".padEnd(15)} ${"Slug".padEnd(40)} ${"Name".padEnd(30)}`);

package/dist/lib/api-client.d.ts

@@ -1,5 +1,5 @@
 import type z from "zod";
-import { type AgentSchemaType, type ChallengeConfigSchemaType, type ChallengeSchemaType, type DashboardUrlResponse, type DownloadUrlResponse, HumanSchema, type RecordingMetadata, type RunStatusSchemaType, type WorldConfigSchemaType, type WorldSchemaType } from "./schemas.js";
+import { type AgentSchemaType, type ChallengeConfigSchemaType, type ChallengeSchemaType, type DashboardUrlResponse, type DownloadUrlResponse, HumanSchema, type ParsedLogEntry, type RecordingMetadata, type RunResultResponse, type RunStatusSchemaType, type WorldConfigSchemaType, type WorldSchemaType } from "./schemas.js";
 export declare class ApiClient {
     private apiUrl;
     private kradleApiKey;
@@ -114,6 +114,18 @@ export declare class ApiClient {
      * @returns Download URL and expiration time.
      */
     getRecordingDownloadUrl(runId: string, participantId: string, timestamp: string): Promise<DownloadUrlResponse>;
+    /**
+     * Get logs for a run, and parse the message if it is a JSON object.
+     * @param runId - The ID of the run.
+     * @returns Array of log entries.
+     */
+    getRunLogs(runId: string): Promise<ParsedLogEntry[]>;
+    /**
+     * Get the result of a run.
+     * @param runId - The ID of the run.
+     * @returns Run result with status, end_state, and participant results.
+     */
+    getRunResult(runId: string): Promise<RunResultResponse>;
     listWorlds(): Promise<WorldSchemaType[]>;
     listKradleWorlds(): Promise<WorldSchemaType[]>;
     getWorld(slug: string): Promise<WorldSchemaType>;

package/dist/lib/api-client.js

@@ -1,13 +1,13 @@
 import { existsSync } from "node:fs";
 import fs from "node:fs/promises";
-import { AgentsResponseSchema, ChallengeSchema, ChallengesResponseSchema, DashboardUrlResponseSchema, DownloadUrlResponseSchema, HumanSchema, JobResponseSchema, RecordingsListResponseSchema, RunStatusSchema, UploadUrlResponseSchema, WorldSchema, WorldsResponseSchema, } from "./schemas.js";
+import { AgentsResponseSchema, ChallengeSchema, ChallengesResponseSchema, DashboardUrlResponseSchema, DownloadUrlResponseSchema, HumanSchema, JobResponseSchema, RecordingsListResponseSchema, RunLogsResponseSchema, RunResultResponseSchema, RunStatusSchema, UploadUrlResponseSchema, WorldSchema, WorldsResponseSchema, } from "./schemas.js";
 const DEFAULT_PAGE_SIZE = 30;
 const DEFAULT_CHALLENGE_SCHEMA = {
     slug: "",
     name: "",
     visibility: "private",
     domain: "minecraft",
-    world: "team-kradle:colosseum",
+    world: "team-kradle:flat-world",
     challengeConfig: { cheat: false, datapack: true, gameMode: "survival" },
     task: ".",
     roles: { "default-role": { description: "default-role", specificTask: "do your best!" } },
@@ -277,6 +277,40 @@ export class ApiClient {
         const url = `runs/${runId}/recordings/${participantId}/downloadUrl?timestamp=${encodeURIComponent(timestamp)}`;
         return this.get(url, {}, DownloadUrlResponseSchema);
     }
+    /**
+     * Get logs for a run, and parse the message if it is a JSON object.
+     * @param runId - The ID of the run.
+     * @returns Array of log entries.
+     */
+    async getRunLogs(runId) {
+        const url = `runs/${runId}/logs`;
+        const response = await this.get(url, {}, RunLogsResponseSchema);
+        return response.logs.map((log) => {
+            const { message, ...rest } = log;
+            try {
+                const parsedMessage = JSON.parse(message);
+                return {
+                    ...rest,
+                    parsedMessage: parsedMessage,
+                };
+            }
+            catch {
+                return {
+                    ...rest,
+                    message: message,
+                };
+            }
+        });
+    }
+    /**
+     * Get the result of a run.
+     * @param runId - The ID of the run.
+     * @returns Run result with status, end_state, and participant results.
+     */
+    async getRunResult(runId) {
+        const url = `runs/${runId}`;
+        return this.get(url, {}, RunResultResponseSchema);
+    }
     async listWorlds() {
         return this.listResource("worlds", "worlds", WorldsResponseSchema);
     }

package/dist/lib/challenge.d.ts

@@ -57,4 +57,12 @@ export declare class Challenge {
      * Note: config.ts is NOT created here - it should be generated later via `challenge config download`
      */
     static createLocal(slug: string, kradleChallengesPath: string): Promise<void>;
+    /**
+     * Download challenge source files (challenge.ts and config.ts) from the cloud
+     * @param api - The API client to use
+     * @param slug - The challenge slug to download
+     * @param targetDir - The directory to save the source files to
+     * @returns The number of files extracted
+     */
+    static downloadSourceFiles(api: ApiClient, slug: string, targetDir: string): Promise<number>;
 }

package/dist/lib/challenge.js

@@ -194,4 +194,50 @@ export class Challenge {
         // Copy challenge.ts template
         await fs.copyFile(challengeTemplatePath, challenge.challengePath);
     }
+    /**
+     * Download challenge source files (challenge.ts and config.ts) from the cloud
+     * @param api - The API client to use
+     * @param slug - The challenge slug to download
+     * @param targetDir - The directory to save the source files to
+     * @returns The number of files extracted
+     */
+    static async downloadSourceFiles(api, slug, targetDir) {
+        const { downloadUrl } = await api.getChallengeDownloadUrl(slug);
+        const response = await fetch(downloadUrl);
+        if (!response.ok) {
+            throw new Error(`Failed to download challenge "${slug}": ${response.status} ${response.statusText}`);
+        }
+        // Save tarball to temp location
+        const tempTarballPath = path.join(targetDir, `${slug}-temp.tar.gz`);
+        const buffer = await response.arrayBuffer();
+        await fs.mkdir(targetDir, { recursive: true });
+        await fs.writeFile(tempTarballPath, Buffer.from(buffer));
+        const filesToExtract = [`${SOURCE_FOLDER}/challenge.ts`, `${SOURCE_FOLDER}/config.ts`];
+        const tempExtractDir = path.join(targetDir, `${slug}-extract-temp`);
+        try {
+            await fs.mkdir(tempExtractDir, { recursive: true });
+            await tar.extract({
+                file: tempTarballPath,
+                cwd: tempExtractDir,
+                filter: (entryPath) => filesToExtract.some((f) => entryPath === f),
+            });
+            const srcChallengeTs = path.join(tempExtractDir, SOURCE_FOLDER, "challenge.ts");
+            const srcConfigTs = path.join(tempExtractDir, SOURCE_FOLDER, "config.ts");
+            let extractedCount = 0;
+            if (existsSync(srcChallengeTs)) {
+                await fs.copyFile(srcChallengeTs, path.join(targetDir, "challenge.ts"));
+                extractedCount++;
+            }
+            if (existsSync(srcConfigTs)) {
+                await fs.copyFile(srcConfigTs, path.join(targetDir, "config.ts"));
+                extractedCount++;
+            }
+            return extractedCount;
+        }
+        finally {
+            // Clean up temp files
+            await fs.rm(tempExtractDir, { recursive: true, force: true });
+            await fs.rm(tempTarballPath, { force: true });
+        }
+    }
 }

package/dist/lib/experiment/experimenter.d.ts

@@ -19,6 +19,11 @@ export declare class Experimenter {
      * Get the current version directory path
      */
     getCurrentVersionDir(): string;
+    /**
+     * Download challenge source files (config.ts and challenge.ts) from the cloud
+     * and store them in the version's challenge directory
+     */
+    private downloadChallengeFiles;
     /**
      * Check if experiment exists
      */
@@ -84,6 +89,10 @@ export declare class Experimenter {
      * Open run in browser
      */
     private openRun;
+    /**
+     * Download logs and run result for a completed run
+     */
+    private downloadLogsForRun;
     /**
      * Download recordings for a completed run with smart polling
      * Polls for 90 seconds after run completion (matching pod grace period)

package/dist/lib/experiment/experimenter.js

@@ -1,6 +1,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import pc from "picocolors";
+import { Challenge } from "../challenge.js";
 import { executeNodeCommand, openInBrowser } from "../utils.js";
 import { Runner } from "./runner.js";
 import { TUI } from "./tui.js";
@@ -39,6 +40,7 @@ export class Experimenter {
             configPath: path.join(versionDir, "config.ts"),
             manifestPath: path.join(versionDir, "manifest.json"),
             progressPath: path.join(versionDir, "progress.json"),
+            challengeDir: path.join(versionDir, "challenge"),
         };
     }
     get configPath() {
@@ -53,6 +55,22 @@ export class Experimenter {
         }
         return this.getVersionPaths(this.currentVersion).versionDir;
     }
+    /**
+     * Download challenge source files (config.ts and challenge.ts) from the cloud
+     * and store them in the version's challenge directory
+     */
+    async downloadChallengeFiles(manifest, challengeDir) {
+        // Extract unique challenge slugs from manifest (typically just one per experiment)
+        const challengeSlugs = [...new Set(manifest.runs.map((run) => run.challenge_slug))];
+        for (const slug of challengeSlugs) {
+            try {
+                await Challenge.downloadSourceFiles(this.api, slug, challengeDir);
+            }
+            catch (error) {
+                console.error(pc.yellow(`Warning: Failed to download challenge files for "${slug}": ${error instanceof Error ? error.message : String(error)}`));
+            }
+        }
+    }
     /**
      * Check if experiment exists
      */
@@ -118,6 +136,8 @@ export class Experimenter {
         // Generate manifest from config
         const manifest = await this.generateManifest(paths.configPath);
         await fs.writeFile(paths.manifestPath, JSON.stringify(manifest, null, 2));
+        // Download challenge files from cloud to preserve exact state
+        await this.downloadChallengeFiles(manifest, paths.challengeDir);
         // Update metadata
         await this.saveMetadata({ currentVersion: newVersion });
         this.currentVersion = newVersion;
@@ -231,14 +251,20 @@ export class Experimenter {
             maxConcurrent: options.maxConcurrent,
             tags: tags,
             onStateChange: () => this.onRunStateChange(),
-            onRunComplete: options.downloadRecordings
+            onRunComplete: options.downloadRecordings || options.downloadLogs
                 ? async (index, runId) => {
                     const state = this.runner?.getRunState(index);
-                    if (!state?.participantIds) {
-                        console.error(pc.yellow(`Warning: Participant IDs not available for run ${runId}, skipping recording download.`));
-                        return;
+                    if (options.downloadRecordings) {
+                        if (!state?.participantIds) {
+                            console.error(pc.yellow(`Warning: Participant IDs not available for run ${runId}, skipping recording download.`));
+                        }
+                        else {
+                            await this.downloadRecordingsForRun(runId, state.participantIds, version);
+                        }
+                    }
+                    if (options.downloadLogs) {
+                        await this.downloadLogsForRun(runId, version);
                     }
-                    await this.downloadRecordingsForRun(runId, state.participantIds, version);
                 }
                 : undefined,
         });
@@ -312,6 +338,46 @@ export class Experimenter {
             openInBrowser(url);
         }
     }
+    /**
+     * Download logs and run result for a completed run
+     */
+    async downloadLogsForRun(runId, version) {
+        const runDir = path.join(this.experimentDir, "versions", version.toString().padStart(3, "0"), "logs", runId);
+        const runPath = path.join(runDir, "run.json");
+        const logsPath = path.join(runDir, "logs.json");
+        // Download run result
+        try {
+            // Check if file already exists
+            try {
+                await fs.access(runPath);
+            }
+            catch {
+                const runResult = await this.api.getRunResult(runId);
+                await fs.mkdir(runDir, { recursive: true });
+                await fs.writeFile(runPath, JSON.stringify(runResult, null, 2));
+            }
+        }
+        catch (error) {
+            console.error(pc.yellow(`Warning: Failed to download run result for ${runId}: ${error instanceof Error ? error.message : String(error)}`));
+        }
+        // Download logs
+        try {
+            // Check if file already exists
+            try {
+                await fs.access(logsPath);
+            }
+            catch {
+                const logs = await this.api.getRunLogs(runId);
+                if (logs.length > 0) {
+                    await fs.mkdir(runDir, { recursive: true });
+                    await fs.writeFile(logsPath, JSON.stringify(logs, null, 2));
+                }
+            }
+        }
+        catch (error) {
+            console.error(`Failed to download logs for run ${runId}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
     /**
      * Download recordings for a completed run with smart polling
      * Polls for 90 seconds after run completion (matching pod grace period)

package/dist/lib/experiment/types.d.ts

@@ -73,24 +73,6 @@ export declare const ProgressSchema: z.ZodObject<{
     lastUpdated: z.ZodNumber;
 }, z.core.$strip>;
 export type Progress = z.infer<typeof ProgressSchema>;
-export declare const RunResultSchema: z.ZodObject<{
-    index: z.ZodNumber;
-    runId: z.ZodString;
-    challenge_slug: z.ZodString;
-    participants: z.ZodArray<z.ZodObject<{
-        agent: z.ZodString;
-        role: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>>;
-    status: z.ZodString;
-    startTime: z.ZodNumber;
-    endTime: z.ZodNumber;
-    duration: z.ZodNumber;
-    logs: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
-    summary: z.ZodOptional<z.ZodString>;
-    error: z.ZodOptional<z.ZodString>;
-    outcome: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-}, z.core.$strip>;
-export type RunResult = z.infer<typeof RunResultSchema>;
 export interface RunState {
     index: number;
     config: RunConfig;
@@ -114,10 +96,6 @@ export declare const RunStatusResponseSchema: z.ZodObject<{
     outcome: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, z.core.$strip>;
 export type RunStatusResponse = z.infer<typeof RunStatusResponseSchema>;
-export declare const RunLogsResponseSchema: z.ZodObject<{
-    logs: z.ZodArray<z.ZodUnknown>;
-}, z.core.$strip>;
-export type RunLogsResponse = z.infer<typeof RunLogsResponseSchema>;
 export declare const ExperimentMetadataSchema: z.ZodObject<{
     currentVersion: z.ZodNumber;
 }, z.core.$strip>;
@@ -127,6 +105,7 @@ export interface ExperimentOptions {
     maxConcurrent: number;
     openMetabase?: boolean;
     downloadRecordings?: boolean;
+    downloadLogs?: boolean;
 }
 export declare const STATUS_ICONS: Record<RunStatus, {
     icon: string;

package/dist/lib/experiment/types.js

@@ -42,21 +42,6 @@ export const ProgressSchema = z.object({
     entries: z.array(ProgressEntrySchema),
     lastUpdated: z.number(),
 });
-// Run result with logs and summary
-export const RunResultSchema = z.object({
-    index: z.number(),
-    runId: z.string(),
-    challenge_slug: z.string(),
-    participants: z.array(ParticipantSchema),
-    status: z.string(),
-    startTime: z.number(),
-    endTime: z.number(),
-    duration: z.number(),
-    logs: z.array(z.unknown()).optional(),
-    summary: z.string().optional(),
-    error: z.string().optional(),
-    outcome: z.record(z.string(), z.unknown()).optional(),
-});
 // API response schemas for run status
 export const RunStatusResponseSchema = z.object({
     id: z.string(),
@@ -65,9 +50,6 @@ export const RunStatusResponseSchema = z.object({
     updatedAt: z.string().optional(),
     outcome: z.record(z.string(), z.unknown()).optional(),
 });
-export const RunLogsResponseSchema = z.object({
-    logs: z.array(z.unknown()),
-});
 // Experiment metadata stored in .experiment.json
 export const ExperimentMetadataSchema = z.object({
     currentVersion: z.number(),

package/dist/lib/schemas.d.ts

@@ -190,6 +190,57 @@ export declare const RecordingsListResponseSchema: z.ZodObject<{
         sizeBytes: z.ZodNumber;
     }, z.core.$strip>>;
 }, z.core.$strip>;
+export declare const LogEntrySchema: z.ZodObject<{
+    participantId: z.ZodString;
+    message: z.ZodString;
+    level: z.ZodString;
+    creationTime: z.ZodString;
+}, z.core.$strip>;
+export declare const RunLogsResponseSchema: z.ZodObject<{
+    logs: z.ZodArray<z.ZodObject<{
+        participantId: z.ZodString;
+        message: z.ZodString;
+        level: z.ZodString;
+        creationTime: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const RunParticipantResultSchema: z.ZodObject<{
+    agent: z.ZodString;
+    winner: z.ZodBoolean;
+    score: z.ZodOptional<z.ZodNumber>;
+    timeToSuccess: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const RunAggregatedResultsSchema: z.ZodObject<{
+    participantCount: z.ZodNumber;
+    successfulParticipantCount: z.ZodNumber;
+    successfulParticipantIds: z.ZodArray<z.ZodString>;
+    unsuccessfulParticipantCount: z.ZodNumber;
+    unsuccessfulParticipantIds: z.ZodArray<z.ZodString>;
+    totalTime: z.ZodNumber;
+}, z.core.$strip>;
+export declare const RunResultResponseSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    challenge: z.ZodOptional<z.ZodString>;
+    status: z.ZodString;
+    endState: z.ZodOptional<z.ZodString>;
+    finishedStatus: z.ZodOptional<z.ZodString>;
+    totalTime: z.ZodOptional<z.ZodNumber>;
+    endTime: z.ZodOptional<z.ZodString>;
+    aggregatedResults: z.ZodOptional<z.ZodObject<{
+        participantCount: z.ZodNumber;
+        successfulParticipantCount: z.ZodNumber;
+        successfulParticipantIds: z.ZodArray<z.ZodString>;
+        unsuccessfulParticipantCount: z.ZodNumber;
+        unsuccessfulParticipantIds: z.ZodArray<z.ZodString>;
+        totalTime: z.ZodNumber;
+    }, z.core.$strip>>;
+    participantResults: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        agent: z.ZodString;
+        winner: z.ZodBoolean;
+        score: z.ZodOptional<z.ZodNumber>;
+        timeToSuccess: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
 export declare const WorldSchema: z.ZodObject<{
     id: z.ZodString;
     slug: z.ZodString;
@@ -239,6 +290,14 @@ export type AgentsResponseType = z.infer<typeof AgentsResponseSchema>;
 export type RecordingMetadata = z.infer<typeof RecordingMetadataSchema>;
 export type RecordingsListResponse = z.infer<typeof RecordingsListResponseSchema>;
 export type RunParticipant = z.infer<typeof RunParticipantSchema>;
+export type LogEntry = z.infer<typeof LogEntrySchema>;
+export type ParsedLogEntry = LogEntry | (Omit<LogEntry, "message"> & {
+    parsedMessage: Record<string, unknown>;
+});
+export type RunLogsResponse = z.infer<typeof RunLogsResponseSchema>;
+export type RunParticipantResult = z.infer<typeof RunParticipantResultSchema>;
+export type RunAggregatedResults = z.infer<typeof RunAggregatedResultsSchema>;
+export type RunResultResponse = z.infer<typeof RunResultResponseSchema>;
 export type DownloadUrlResponse = z.infer<typeof DownloadUrlResponseSchema>;
 export type WorldSchemaType = z.infer<typeof WorldSchema>;
 export type WorldConfigSchemaType = z.infer<typeof WorldConfigSchema>;

package/dist/lib/schemas.js

@@ -90,6 +90,40 @@ export const RecordingMetadataSchema = z.object({
 export const RecordingsListResponseSchema = z.object({
     recordings: z.array(RecordingMetadataSchema),
 });
+export const LogEntrySchema = z.object({
+    participantId: z.string(),
+    message: z.string(),
+    level: z.string(),
+    creationTime: z.string(),
+});
+export const RunLogsResponseSchema = z.object({
+    logs: z.array(LogEntrySchema),
+});
+export const RunParticipantResultSchema = z.object({
+    agent: z.string(),
+    winner: z.boolean(),
+    score: z.number().optional(),
+    timeToSuccess: z.number().optional(),
+});
+export const RunAggregatedResultsSchema = z.object({
+    participantCount: z.number(),
+    successfulParticipantCount: z.number(),
+    successfulParticipantIds: z.array(z.string()),
+    unsuccessfulParticipantCount: z.number(),
+    unsuccessfulParticipantIds: z.array(z.string()),
+    totalTime: z.number(),
+});
+export const RunResultResponseSchema = z.object({
+    id: z.string().optional(),
+    challenge: z.string().optional(),
+    status: z.string(),
+    endState: z.string().optional(),
+    finishedStatus: z.string().optional(),
+    totalTime: z.number().optional(),
+    endTime: z.string().optional(),
+    aggregatedResults: RunAggregatedResultsSchema.optional(),
+    participantResults: z.record(z.string(), RunParticipantResultSchema).optional(),
+});
 export const WorldSchema = z.object({
     id: z.string(),
     slug: z.string(),

package/oclif.manifest.json

@@ -86,6 +86,62 @@
         "list.js"
       ]
     },
+    "ai-docs:challenges-sdk": {
+      "aliases": [],
+      "args": {
+        "version": {
+          "description": "SDK version to fetch docs for. If not specified, the locally installed version will be used if available, otherwise the latest version will be used.",
+          "name": "version",
+          "required": false
+        }
+      },
+      "description": "Output the @kradle/challenges-sdk API reference documentation for LLMs",
+      "examples": [
+        "<%= config.bin %> <%= command.id %>",
+        "<%= config.bin %> <%= command.id %> 0.2.1",
+        "<%= config.bin %> <%= command.id %> latest"
+      ],
+      "flags": {},
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "ai-docs:challenges-sdk",
+      "pluginAlias": "kradle",
+      "pluginName": "kradle",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "ai-docs",
+        "challenges-sdk.js"
+      ]
+    },
+    "ai-docs:cli": {
+      "aliases": [],
+      "args": {},
+      "description": "Output the Kradle CLI reference documentation for LLMs",
+      "examples": [
+        "<%= config.bin %> <%= command.id %>"
+      ],
+      "flags": {},
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "ai-docs:cli",
+      "pluginAlias": "kradle",
+      "pluginName": "kradle",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "ai-docs",
+        "cli.js"
+      ]
+    },
     "challenge:build": {
       "aliases": [],
       "args": {
@@ -661,6 +717,79 @@
         "list.js"
       ]
     },
+    "experiment:logs": {
+      "aliases": [],
+      "args": {
+        "experimentName": {
+          "description": "Experiment name",
+          "name": "experimentName",
+          "required": true
+        },
+        "runId": {
+          "description": "Specific run ID to download logs from (optional)",
+          "name": "runId",
+          "required": false
+        }
+      },
+      "description": "Download logs from an experiment run",
+      "examples": [
+        "<%= config.bin %> <%= command.id %> my-experiment",
+        "<%= config.bin %> <%= command.id %> my-experiment <run-id>",
+        "<%= config.bin %> <%= command.id %> my-experiment --all",
+        "<%= config.bin %> <%= command.id %> my-experiment --version 2",
+        "<%= config.bin %> <%= command.id %> my-experiment --version 1 --all"
+      ],
+      "flags": {
+        "all": {
+          "description": "Download logs for all runs",
+          "name": "all",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "version": {
+          "description": "Specific experiment version to download logs from (e.g., 0, 1, 2)",
+          "name": "version",
+          "required": false,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "api-key": {
+          "description": "Kradle API key",
+          "env": "KRADLE_API_KEY",
+          "name": "api-key",
+          "required": true,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "api-url": {
+          "description": "Kradle Web API URL",
+          "env": "KRADLE_API_URL",
+          "name": "api-url",
+          "required": true,
+          "default": "https://api.kradle.ai/v0",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "experiment:logs",
+      "pluginAlias": "kradle",
+      "pluginName": "kradle",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "experiment",
+        "logs.js"
+      ]
+    },
     "experiment:recordings": {
       "aliases": [],
       "args": {
@@ -774,6 +903,13 @@
           "allowNo": false,
           "type": "boolean"
         },
+        "download-logs": {
+          "char": "l",
+          "description": "Automatically download logs after each run finishes",
+          "name": "download-logs",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "api-key": {
           "description": "Kradle API key",
           "env": "KRADLE_API_KEY",
@@ -1105,63 +1241,7 @@
         "world",
         "push.js"
       ]
-    },
-    "ai-docs:challenges-sdk": {
-      "aliases": [],
-      "args": {
-        "version": {
-          "description": "SDK version to fetch docs for. If not specified, the locally installed version will be used if available, otherwise the latest version will be used.",
-          "name": "version",
-          "required": false
-        }
-      },
-      "description": "Output the @kradle/challenges-sdk API reference documentation for LLMs",
-      "examples": [
-        "<%= config.bin %> <%= command.id %>",
-        "<%= config.bin %> <%= command.id %> 0.2.1",
-        "<%= config.bin %> <%= command.id %> latest"
-      ],
-      "flags": {},
-      "hasDynamicHelp": false,
-      "hiddenAliases": [],
-      "id": "ai-docs:challenges-sdk",
-      "pluginAlias": "kradle",
-      "pluginName": "kradle",
-      "pluginType": "core",
-      "strict": true,
-      "enableJsonFlag": false,
-      "isESM": true,
-      "relativePath": [
-        "dist",
-        "commands",
-        "ai-docs",
-        "challenges-sdk.js"
-      ]
-    },
-    "ai-docs:cli": {
-      "aliases": [],
-      "args": {},
-      "description": "Output the Kradle CLI reference documentation for LLMs",
-      "examples": [
-        "<%= config.bin %> <%= command.id %>"
-      ],
-      "flags": {},
-      "hasDynamicHelp": false,
-      "hiddenAliases": [],
-      "id": "ai-docs:cli",
-      "pluginAlias": "kradle",
-      "pluginName": "kradle",
-      "pluginType": "core",
-      "strict": true,
-      "enableJsonFlag": false,
-      "isESM": true,
-      "relativePath": [
-        "dist",
-        "commands",
-        "ai-docs",
-        "cli.js"
-      ]
     }
   },
-  "version": "0.3.3"
+  "version": "0.4.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "kradle",
-	"version": "0.3.3",
+	"version": "0.4.0",
 	"description": "Kradle's CLI. Manage challenges, experiments, agents and more!",
 	"keywords": [
 		"cli"

package/static/ai_docs/LLM_CLI_REFERENCE.md

@@ -436,6 +436,7 @@ kradle experiment run <name>
 kradle experiment run <name> --new-version
 kradle experiment run <name> --max-concurrent 10
 kradle experiment run <name> --download-recordings
+kradle experiment run <name> --download-logs
 ```
 
 **Arguments:**
@@ -449,6 +450,7 @@ kradle experiment run <name> --download-recordings
 | `--new-version` | `-n` | Start a fresh version instead of resuming | false |
 | `--max-concurrent` | `-m` | Maximum parallel runs | 5 |
 | `--download-recordings` | `-d` | Auto-download recordings as runs complete | false |
+| `--download-logs` | `-l` | Auto-download logs as runs complete | false |
 
 **Behavior:**
 1. Creates new version or resumes existing incomplete version
@@ -471,8 +473,11 @@ kradle experiment run benchmark-v1 --max-concurrent 10
 # Auto-download recordings
 kradle experiment run benchmark-v1 --download-recordings
 
+# Auto-download logs
+kradle experiment run benchmark-v1 --download-logs
+
 # Combine flags
-kradle experiment run benchmark-v1 -n -m 10 -d
+kradle experiment run benchmark-v1 -n -m 10 -d -l
 ```
 
 ---
@@ -536,6 +541,77 @@ kradle experiment recordings benchmark-v1 --version 2 --all
 
 ---
 
+### `kradle experiment logs <name>`
+
+Downloads logs and run results from completed experiment runs.
+
+**Usage:**
+```bash
+kradle experiment logs <name>
+kradle experiment logs <name> <run-id>
+kradle experiment logs <name> --all
+kradle experiment logs <name> --version 2
+```
+
+**Arguments:**
+| Argument | Description | Required |
+|----------|-------------|----------|
+| `name` | Experiment name | Yes |
+| `run-id` | Specific run ID to download | No |
+
+**Flags:**
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--all` | Download logs for all runs (skips interactive selection) | false |
+| `--version` | Specific experiment version number | Latest version |
+
+**Interactive mode (no flags):**
+1. Select a run from completed runs list
+
+**Output location:**
+```
+experiments/<name>/versions/<version>/logs/<run-id>/
+```
+
+**Downloaded files:**
+
+1. `run.json` - Run result containing:
+   - `id`: Run ID
+   - `challenge`: Challenge slug
+   - `status`: Run status
+   - `end_state`: Final game state
+   - `finished_status`: How the run finished
+   - `total_time`: Total run duration
+   - `end_time`: When the run ended
+   - `aggregated_results`: Summary with participant counts, successful/unsuccessful IDs
+   - `participant_results`: Per-participant results (agent, winner, score, time_to_success)
+
+2. `logs.json` - Array of log entries containing:
+   - `participant_id`: The participant that generated the log
+   - `message`: The log message content
+   - `level`: Log level (debug, info, warning, error)
+   - `creation_time`: Timestamp when the log was created
+
+**Examples:**
+```bash
+# Interactive selection
+kradle experiment logs benchmark-v1
+
+# Download specific run
+kradle experiment logs benchmark-v1 abc123-run-id
+
+# Download all logs from all runs
+kradle experiment logs benchmark-v1 --all
+
+# Download from specific version
+kradle experiment logs benchmark-v1 --version 1
+
+# Combine version and all flags
+kradle experiment logs benchmark-v1 --version 2 --all
+```
+
+---
+
 ### `kradle experiment list`
 
 Lists all local experiments.
@@ -952,6 +1028,7 @@ kradle challenge build --all --visibility public
 | `kradle experiment create <name>` | Create new experiment |
 | `kradle experiment run <name>` | Run/resume experiment |
 | `kradle experiment recordings <name>` | Download recordings |
+| `kradle experiment logs <name>` | Download logs |
 | `kradle experiment list` | List experiments |
 | `kradle world import <path>` | Import Minecraft world folder |
 | `kradle world push <slug...>` | Push world(s) to cloud |