@kradle/cli 0.0.17 → 0.1.0

package/README.md

@@ -1,12 +1,13 @@
 # Kradle CLI
 
-Kradle's CLI for managing Minecraft challenges, evaluations, agents, and more!
+Kradle's CLI for managing Minecraft challenges, experiments, agents, and more!
 
 * [Installation](#installation)
 * [Autocomplete](#autocomplete)
 * [Configuration](#configuration)
 * [Challenge](#challenge-commands)
-* [Evaluations](#evaluation-commands)
+* [Experiments](#experiment-commands)
+* [Agents](#agent-commands)
 * [Publishing a New Version](#publishing-a-new-version)
 * [Development](#development)
 * [Architecture](#architecture)
@@ -17,14 +18,14 @@ Kradle's CLI for managing Minecraft challenges, evaluations, agents, and more!
 ```
 npm i -g @kradle/cli
 ```
-2. Initialize a new directory to store challenges and evaluations
+2. Initialize a new directory to store challenges and experiments
 ```
 kradle init
 ```
-3. Congrats 🎉 You can now create a new challenge or a new evaluation:
+3. Congrats 🎉 You can now create a new challenge or a new experiment:
 ```
 kradle challenge create <challenge-name>
-kradle evaluation create <evaluation-name>
+kradle experiment create <experiment-name>
 ```
 
 In addition, you can enable [autocomplete](#Autocomplete).
@@ -45,6 +46,20 @@ 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:
+```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
 
 ### Create Challenge
@@ -122,59 +137,69 @@ kradle challenge multi-upload
 
 Provides an interactive UI to select multiple challenges and uploads them in parallel.
 
-## Evaluation Commands
+## Experiment Commands
 
-Evaluations 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.
+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
 
-**Evaluation**: A named collection of run configurations defined in a `config.ts` file. Each evaluation lives in `evaluations/<name>/`.
+**Experiment**: A named collection of run configurations defined in a `config.ts` file. Each experiment lives in `experiments/<name>/`.
 
-**Iteration**: A snapshot of an evaluation execution. When you run an evaluation, it creates an iteration containing:
+**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
 
-Iterations are stored in `evaluations/<name>/iterations/001/`, `002/`, etc. This allows you to:
-- Resume an interrupted evaluation from where it left off
-- Re-run the same evaluation with `--new` to create a fresh iteration
-- Compare results across different iterations
+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 Evaluation
+### Create Experiment
 
-Create a new evaluation with a template config file:
+Create a new experiment with a template config file:
 
 ```bash
-kradle evaluation create <name>
+kradle experiment create <name>
 ```
 
-This creates `evaluations/<name>/config.ts` with a template that you can customize. The config exports a `main()` function that returns a manifest with:
+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 Evaluation
+### Run Experiment
 
-Execute or resume an evaluation:
+Execute or resume an experiment:
 
 ```bash
-kradle evaluation run <name>                  # Resume current iteration or create first one
-kradle evaluation run <name> --new            # Start a new iteration
-kradle evaluation run <name> --max-concurrent 10  # Control parallelism (default: 5)
+kradle experiment run <name>                  # Resume current version or create first one
+kradle experiment run <name> --new            # Start a new version
+kradle experiment run <name> --max-concurrent 10  # Control parallelism (default: 5)
 ```
 
 The run command:
-1. Creates a new iteration (or resumes the current one)
+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
 
-### List Evaluations
+### List Experiments
+
+List all local experiments:
+
+```bash
+kradle experiment list
+```
+
+## Agent Commands
+
+### List Agents
 
-List all local evaluations:
+List all agents registered in the system:
 
 ```bash
-kradle evaluation list
+kradle agent list
 ```
 
 ## Publishing a New Version
@@ -203,25 +228,10 @@ npm run build
 npm link
 ```
 
-### `kradle` vs `kradle-dev`
-
-The repository provides two CLI commands:
-
-- **`kradle`**: Production CLI that runs compiled JavaScript from `dist/`
-  - Requires `npm run build` after every code change
-  - This is what end users will use
+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
 
-- **`kradle-dev`**: Development CLI that runs TypeScript directly
-  - No build step required
-  - Changes are reflected immediately
-  - **Always use this during development**
-
-Example usage:
-```bash
-kradle-dev challenge list
-kradle-dev challenge build <challenge-name>
-kradle-dev challenge run <challenge-name>
-```
 
 ### Build & Lint
 
@@ -246,10 +256,6 @@ Each challenge is a folder in `challenges/<slug>/` containing:
 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
 
-### Configuration Note
-
-The CLI relies on a `.env` file in the **parent directory (kradle-sandstone root)**, not in the kradle-cli directory itself. The `.env` file should be at the same level as both `kradle-cli/` and `challenges/` folders.
-
 ## Architecture
 
 The CLI is built with:
@@ -257,6 +263,8 @@ 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
@@ -268,22 +276,11 @@ The CLI is built with:
 kradle-cli/
 ├── src/
 │   ├── commands/             # CLI commands
-│   │   └── challenge/        # Challenge management commands
-│   │       ├── build.ts      # Build & upload datapack + config
-│   │       ├── create.ts     # Create new challenge
-│   │       ├── list.ts       # List local & cloud challenges
-│   │       ├── multi-upload.ts  # Interactive multi-select upload
-│   │       ├── run.ts        # Run challenge (prod or studio)
-│   │       ├── watch.ts      # Watch for changes & auto-rebuild
+│   │   ├── agent/            # Agent commands
+│   │   ├── challenge/        # Challenge management commands
+│   │   └── experiment/       # Experiment commands
 │   └── lib/                  # Core libraries
-│       ├── api-client.ts     # Typed API client with Zod validation
-│       ├── arguments.ts      # Shared CLI arguments with autocomplete
-│       ├── challenge.ts      # Challenge class (build, upload, hash, config)
-│       ├── config.ts         # Environment config with Zod schemas
-│       ├── schemas.ts        # Zod schemas for type-safe API interactions
-│       └── utils.ts          # Utility functions
-├── static/                   # Template files (challenge.ts)
-├── biome.json               # Biome linter & formatter config
-├── package.json
-└── tsconfig.json            # TypeScript ESM configuration
+│       └── experiment/       # Experiment system
+└── static/                   # Template files
+    └── project_template/     # Files for kradle init
 ```

package/dist/commands/agent/list.d.ts

@@ -2,5 +2,9 @@ import { Command } from "@oclif/core";
 export default class List extends Command {
     static description: string;
     static examples: string[];
+    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>;
+    };
     run(): Promise<void>;
 }

package/dist/commands/agent/list.js

@@ -1,14 +1,16 @@
 import { Command } from "@oclif/core";
 import pc from "picocolors";
 import { ApiClient } from "../../lib/api-client.js";
-import { loadConfig } from "../../lib/config.js";
+import { getConfigFlags } from "../../lib/flags.js";
 export default class List extends Command {
     static description = "List all agents";
     static examples = ["<%= config.bin %> <%= command.id %>"];
+    static flags = {
+        ...getConfigFlags("api-key", "api-url"),
+    };
     async run() {
-        const config = loadConfig();
-        await this.parse(List);
-        const api = new ApiClient(config);
+        const { flags } = await this.parse(List);
+        const api = new ApiClient(flags["api-url"], flags["api-key"]);
         this.log(pc.blue(">> Loading agents..."));
         const agents = await api.listKradleAgents();
         agents.sort((a, b) => a.username?.localeCompare(b.username || "") || 0);

package/dist/commands/challenge/build.d.ts

@@ -3,7 +3,15 @@ export default class Build extends Command {
     static description: string;
     static examples: string[];
     static args: {
-        challenge: import("@oclif/core/interfaces").Arg<string>;
+        challengeSlug: import("@oclif/core/interfaces").Arg<string | undefined>;
     };
+    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>;
+        "challenges-path": import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        all: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        public: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    static strict: boolean;
     run(): Promise<void>;
 }

package/dist/commands/challenge/build.js

@@ -1,25 +1,53 @@
-import { Command } from "@oclif/core";
+import { Command, Flags, loadHelpClass } from "@oclif/core";
 import pc from "picocolors";
 import { ApiClient } from "../../lib/api-client.js";
 import { getChallengeSlugArgument } from "../../lib/arguments.js";
 import { Challenge } from "../../lib/challenge.js";
-import { loadConfig } from "../../lib/config.js";
+import { getConfigFlags } from "../../lib/flags.js";
 export default class Build extends Command {
     static description = "Build and upload challenge datapack and config";
-    static examples = ["<%= config.bin %> <%= command.id %> my-challenge"];
+    static examples = [
+        "<%= config.bin %> <%= command.id %> my-challenge",
+        "<%= config.bin %> <%= command.id %> my-challenge my-other-challenge",
+        "<%= config.bin %> <%= command.id %> --all",
+    ];
     static args = {
-        challenge: getChallengeSlugArgument({ description: "Challenge slug to build" }),
+        challengeSlug: getChallengeSlugArgument({
+            description: "Challenge slug to build and upload. Can be used multiple times to build and upload multiple challenges at once. Incompatible with --all flag.",
+            required: false,
+        }),
     };
+    static flags = {
+        all: Flags.boolean({ char: "a", description: "Build all challenges in the challenges directory", default: false }),
+        public: Flags.boolean({ char: "p", description: "Upload challenges as public.", default: false }),
+        ...getConfigFlags("api-key", "api-url", "challenges-path"),
+    };
+    static strict = false;
     async run() {
-        const { args } = await this.parse(Build);
-        const config = loadConfig();
-        const api = new ApiClient(config);
-        const challenge = new Challenge(args.challenge, config);
-        try {
-            await challenge.buildAndUpload(api);
+        const { argv, flags } = await this.parse(Build);
+        if (flags.all && argv.length > 0) {
+            this.error(pc.red("Cannot use --all flag with challenge slugs"));
+        }
+        if (!flags.all && argv.length === 0) {
+            // Show help if no challenge slugs are provided - https://github.com/oclif/oclif/issues/183#issuecomment-1933104981
+            await new (await loadHelpClass(this.config))(this.config).showHelp([Build.id]);
+            return;
+        }
+        if (flags.all) {
+            this.log(pc.blue("Building all challenges"));
         }
-        catch (error) {
-            this.error(pc.red(`Build failed: ${error instanceof Error ? error.message : String(error)}`));
+        const challengeSlugs = flags.all ? await Challenge.getLocalChallenges() : argv;
+        const api = new ApiClient(flags["api-url"], flags["api-key"]);
+        for (const challengeSlug of challengeSlugs) {
+            const challenge = new Challenge(challengeSlug, flags["challenges-path"]);
+            this.log(pc.blue(`==== Building challenge: ${challenge.shortSlug} ====`));
+            try {
+                await challenge.buildAndUpload(api, flags.public);
+            }
+            catch (error) {
+                this.error(pc.red(`Build failed: ${error instanceof Error ? error.message : String(error)}`));
+            }
+            this.log();
         }
     }
 }

package/dist/commands/challenge/create.d.ts

@@ -3,9 +3,13 @@ export default class Create extends Command {
     static description: string;
     static examples: string[];
     static args: {
-        challenge: import("@oclif/core/interfaces").Arg<string>;
+        challengeSlug: import("@oclif/core/interfaces").Arg<string>;
     };
     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>;
+        "web-url": import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        "challenges-path": import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         verbose: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     run(): Promise<void>;

package/dist/commands/challenge/create.js

@@ -5,28 +5,29 @@ import pc from "picocolors";
 import { ApiClient } from "../../lib/api-client.js";
 import { getChallengeSlugArgument } from "../../lib/arguments.js";
 import { Challenge } from "../../lib/challenge.js";
-import { loadConfig } from "../../lib/config.js";
+import { getConfigFlags } from "../../lib/flags.js";
+import { ChallengeConfigSchema } from "../../lib/schemas.js";
 export default class Create extends Command {
     static description = "Create a new challenge locally and in the cloud";
     static examples = ["<%= config.bin %> <%= command.id %> my-challenge"];
     static args = {
-        challenge: getChallengeSlugArgument({ description: "Challenge slug to create" }),
+        challengeSlug: getChallengeSlugArgument({ description: "Challenge slug to create" }),
     };
     static flags = {
         verbose: Flags.boolean({ char: "v", description: "Verbose output", default: false }),
+        ...getConfigFlags("api-key", "api-url", "challenges-path", "web-url"),
     };
     async run() {
         const { args, flags } = await this.parse(Create);
-        const config = loadConfig();
-        const api = new ApiClient(config);
-        const challenge = new Challenge(args.challenge, config);
+        const api = new ApiClient(flags["api-url"], flags["api-key"]);
+        const challenge = new Challenge(args.challengeSlug, flags["challenges-path"]);
         const tasks = new Listr([
             {
                 title: "Checking if challenge exists",
                 task: async (_, task) => {
-                    const exists = await api.challengeExists(args.challenge);
+                    const exists = await api.challengeExists(args.challengeSlug);
                     if (exists) {
-                        this.error(pc.red(`Challenge already exists: ${args.challenge}`));
+                        this.error(pc.red(`Challenge already exists: ${args.challengeSlug}`));
                     }
                     task.title = `Challenge does not exist.`;
                 },
@@ -34,27 +35,25 @@ export default class Create extends Command {
             {
                 title: "Creating local challenge folder",
                 task: async (_, task) => {
-                    await Challenge.createLocal(args.challenge, config);
+                    await Challenge.createLocal(args.challengeSlug, flags["challenges-path"]);
                     task.title = `Created local challenge folder: ${challenge.challengeDir}`;
                 },
             },
             {
                 title: "Creating cloud challenge",
                 task: async (_, task) => {
-                    await api.createChallenge(args.challenge);
+                    await api.createChallenge(args.challengeSlug);
                     task.title = `Created cloud challenge`;
                 },
             },
             {
                 title: "Downloading challenge config",
                 task: async (_, task) => {
-                    const challengeData = await api.getChallenge(args.challenge);
+                    const challengeData = await api.getChallenge(args.challengeSlug);
                     // Remove fields that shouldn't be in the config file
-                    const { id, creationTime, updateTime, creator, ...cleanChallenge } = challengeData;
-                    // We remove the username prefix from the slug, to make the challenge easy to share with others
-                    cleanChallenge.slug = cleanChallenge.slug.split(":")[1];
+                    const config = ChallengeConfigSchema.parse(challengeData);
                     // Remove quotes from keys
-                    const configStr = JSON.stringify(cleanChallenge, null, 2).replace(/"([a-zA-Z0-9_]+)":/g, "$1:");
+                    const configStr = JSON.stringify(config, null, 2).replace(/"([a-zA-Z0-9_]+)":/g, "$1:");
                     await fs.writeFile(challenge.configPath, `
 export const config = ${configStr};
 `.trim());
@@ -71,16 +70,16 @@ export const config = ${configStr};
             {
                 title: "Uploading initial datapack",
                 task: async (_, task) => {
-                    await challenge.upload(api);
+                    api.uploadChallengeDatapack(args.challengeSlug, challenge.tarballPath);
                     task.title = `Uploaded initial datapack`;
                 },
             },
         ]);
         try {
             await tasks.run();
-            this.log(pc.green(`\n✓ Challenge created: ${args.challenge}`));
-            this.log(pc.green(`↳ Run "kradle challenge watch ${args.challenge}" to watch your challenge and start testing!`));
-            this.log(pc.dim(`\nSee your challenge at: ${config.WEB_URL}/studio/challenges/${args.challenge}?tab=challenge-definition`));
+            this.log(pc.green(`\n✓ Challenge created: ${args.challengeSlug}`));
+            this.log(pc.green(`↳ Run "kradle challenge watch ${args.challengeSlug}" to watch your challenge and start testing!`));
+            this.log(pc.dim(`\nSee your challenge at: ${flags["web-url"]}/studio/challenges/${args.challengeSlug}?tab=challenge-definition`));
         }
         catch (error) {
             this.error(pc.red(`Create failed: ${error instanceof Error ? error.message : String(error)}`));

package/dist/commands/challenge/delete.d.ts

@@ -3,9 +3,12 @@ export default class Delete extends Command {
     static description: string;
     static examples: string[];
     static args: {
-        challenge: import("@oclif/core/interfaces").Arg<string>;
+        challengeSlug: import("@oclif/core/interfaces").Arg<string>;
     };
     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>;
+        "challenges-path": import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         yes: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     run(): Promise<void>;

package/dist/commands/challenge/delete.js

@@ -5,7 +5,7 @@ import pc from "picocolors";
 import { ApiClient } from "../../lib/api-client.js";
 import { getChallengeSlugArgument } from "../../lib/arguments.js";
 import { Challenge } from "../../lib/challenge.js";
-import { loadConfig } from "../../lib/config.js";
+import { getConfigFlags } from "../../lib/flags.js";
 export default class Delete extends Command {
     static description = "Delete a challenge locally and from the cloud";
     static examples = [
@@ -13,16 +13,16 @@ export default class Delete extends Command {
         "<%= config.bin %> <%= command.id %> my-challenge --yes",
     ];
     static args = {
-        challenge: getChallengeSlugArgument({ description: "Challenge slug to delete" }),
+        challengeSlug: getChallengeSlugArgument({ description: "Challenge slug to delete" }),
     };
     static flags = {
         yes: Flags.boolean({ char: "y", description: "Skip confirmation prompts", default: false }),
+        ...getConfigFlags("api-key", "api-url", "challenges-path"),
     };
     async run() {
         const { args, flags } = await this.parse(Delete);
-        const config = loadConfig();
-        const api = new ApiClient(config);
-        const challenge = new Challenge(args.challenge, config);
+        const api = new ApiClient(flags["api-url"], flags["api-key"]);
+        const challenge = new Challenge(args.challengeSlug, flags["challenges-path"]);
         // Check if challenge exists locally
         const existsLocally = challenge.exists();
         // Check if challenge exists in cloud

package/dist/commands/challenge/list.d.ts

@@ -2,5 +2,10 @@ import { Command } from "@oclif/core";
 export default class List extends Command {
     static description: string;
     static examples: string[];
+    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>;
+        "challenges-path": import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+    };
     run(): Promise<void>;
 }

package/dist/commands/challenge/list.js

@@ -2,14 +2,16 @@ import { Command } from "@oclif/core";
 import pc from "picocolors";
 import { ApiClient } from "../../lib/api-client.js";
 import { Challenge } from "../../lib/challenge.js";
-import { loadConfig } from "../../lib/config.js";
+import { getConfigFlags } from "../../lib/flags.js";
 export default class List extends Command {
     static description = "List all challenges (local and cloud)";
     static examples = ["<%= config.bin %> <%= command.id %>"];
+    static flags = {
+        ...getConfigFlags("api-key", "api-url", "challenges-path"),
+    };
     async run() {
-        const config = loadConfig();
-        await this.parse(List);
-        const api = new ApiClient(config);
+        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([
             api.listChallenges(),
@@ -18,17 +20,14 @@ export default class List extends Command {
         ]);
         // Create a map for easy lookup
         const cloudMap = new Map(cloudChallenges.map((c) => [c.slug, c]));
-        const allSlugs = new Set([
-            ...cloudMap.keys(),
-            ...Object.keys(localChallenges).map((id) => `${human.username}:${id}`),
-        ]);
+        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)}`);
         this.log("-".repeat(90));
         for (const slug of Array.from(allSlugs).sort()) {
-            const challenge = new Challenge(slug, config);
+            const challenge = new Challenge(slug, flags["challenges-path"]);
             const inCloud = cloudMap.has(slug);
-            const inLocal = localChallenges[challenge.shortSlug];
+            const inLocal = localChallenges.includes(slug);
             let status;
             if (inCloud && inLocal) {
                 status = pc.green("✓ synced");

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

@@ -3,10 +3,17 @@ export default class Run extends Command {
     static description: string;
     static examples: string[];
     static args: {
-        challenge: import("@oclif/core/interfaces").Arg<string>;
+        challengeSlug: import("@oclif/core/interfaces").Arg<string>;
     };
     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>;
+        "web-url": import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        "studio-api-url": import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        "studio-url": import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        "challenges-path": import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         studio: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        open: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     run(): Promise<void>;
 }

package/dist/commands/challenge/run.js

@@ -3,8 +3,8 @@ import pc from "picocolors";
 import { ApiClient } from "../../lib/api-client.js";
 import { getChallengeSlugArgument } from "../../lib/arguments.js";
 import { Challenge } from "../../lib/challenge.js";
-import { loadConfig } from "../../lib/config.js";
-import { loadTemplateRun } from "../../lib/utils.js";
+import { getConfigFlags } from "../../lib/flags.js";
+import { loadTemplateRun, openInBrowser } from "../../lib/utils.js";
 export default class Run extends Command {
     static description = "Run a challenge";
     static examples = [
@@ -12,16 +12,18 @@ export default class Run extends Command {
         "<%= config.bin %> <%= command.id %> my-challenge --studio",
     ];
     static args = {
-        challenge: getChallengeSlugArgument({ description: "Challenge slug to run" }),
+        challengeSlug: getChallengeSlugArgument({ description: "Challenge slug to run" }),
     };
     static flags = {
         studio: Flags.boolean({ char: "s", description: "Run in studio environment", default: false }),
+        open: Flags.boolean({ char: "o", description: "Open the run URL in the browser", default: false }),
+        ...getConfigFlags("api-key", "api-url", "challenges-path", "web-url", "studio-url", "studio-api-url"),
     };
     async run() {
         const { args, flags } = await this.parse(Run);
-        const config = loadConfig();
-        const api = new ApiClient(config);
-        const challenge = new Challenge(args.challenge, config);
+        const apiUrl = flags.studio ? flags["studio-api-url"] : flags["api-url"];
+        const studioApi = new ApiClient(apiUrl, flags["api-key"]);
+        const challenge = new Challenge(args.challengeSlug, flags["challenges-path"]);
         try {
             const { participants } = (await loadTemplateRun());
             const template = {
@@ -29,12 +31,15 @@ export default class Run extends Command {
                 participants,
             };
             this.log(pc.blue(`>> Running challenge: ${challenge.shortSlug}${flags.studio ? " (studio)" : ""}...`));
-            const response = await api.runChallenge(template, flags.studio);
+            const response = await studioApi.runChallenge(template);
             if (response.runIds && response.runIds.length > 0) {
-                const baseUrl = flags.studio ? config.STUDIO_URL : config.WEB_URL;
+                const baseUrl = flags.studio ? flags["studio-url"] : flags["web-url"];
                 const runUrl = `${baseUrl}/runs/${response.runIds[0]}`;
                 this.log(pc.green("\n✓ Challenge started!"));
                 this.log(pc.dim(`Run URL: ${runUrl}`));
+                if (flags.open) {
+                    await openInBrowser(runUrl);
+                }
             }
             else {
                 this.log(pc.yellow("⚠ Challenge started but no run ID returned"));

package/dist/commands/challenge/watch.d.ts

@@ -3,10 +3,13 @@ export default class Watch extends Command {
     static description: string;
     static examples: string[];
     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>;
+        "challenges-path": import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         verbose: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     static args: {
-        challenge: import("@oclif/core/interfaces").Arg<string>;
+        challengeSlug: import("@oclif/core/interfaces").Arg<string>;
     };
     run(): Promise<void>;
 }