@root-signals/scorable-cli 0.3.0 → 0.4.1

package/README.md

@@ -24,6 +24,10 @@
   </a>
 </p>
 
+<p align="center">
+  <video src="https://github.com/user-attachments/assets/3475573e-b20c-405b-acc6-ee48709998fa" width="800" autoplay loop muted></video>
+</p>
+
 The `scorable` CLI is a command-line tool for interacting with the Scorable API. It lets you manage and execute Judges and Evaluators, view execution logs, and run prompt testing experiments directly from the terminal.
 
 Requires **Node.js 20 or higher**.
@@ -48,7 +52,15 @@ npx @root-signals/scorable-cli judge list
 
 ## Authentication
 
-Get a free API key at [scorable.ai/register](https://scorable.ai/register), then save it using one of:
+**Option 1 — Free demo key** (no registration required):
+
+```bash
+scorable auth demo-key
+```
+
+Creates a temporary key and saves it to `~/.scorable/settings.json`.
+
+**Option 2 — Permanent key** from [scorable.ai/register](https://scorable.ai/register):
 
 ```bash
 # Interactively
@@ -58,17 +70,25 @@ scorable auth set-key
 scorable auth set-key sk-your-api-key
 ```
 
-The key is written to `~/.scorable/settings.json`
-
-Alternatively, set it as an environment variable — this takes precedence over the saved key:
+**Option 3 — Environment variable** (takes precedence over saved key):
 
 ```bash
 export SCORABLE_API_KEY="sk-your-api-key"
 ```
 
-### Temporary API keys
+The key lookup order is: `SCORABLE_API_KEY` env var → `api_key` in `~/.scorable/settings.json` → `temporary_api_key` in `~/.scorable/settings.json`.
+
+## Scorable Skills for AI Coding Agents
+
+Install Scorable skills into your project so your AI coding agent (Claude Code, Cursor, etc.) can integrate evaluators automatically:
+
+```bash
+scorable skills-add
+```
+
+Once installed, open your coding agent in your AI powered project and use the prompt:
 
-If no API key is set, the CLI will offer to create a temporary key interactively (in TTY sessions) and save it to `~/.scorable/settings.json`.
+> "Integrate scorable evaluators"
 
 ## Judge Management
 

package/dist/auth.d.ts

@@ -5,4 +5,5 @@ export declare function getApiKey(): string | undefined;
 export declare function getBaseUrl(): string;
 export declare function getSdkClient(apiKey: string): Scorable;
 export declare function requireApiKey(): Promise<string>;
+export declare function createDemoKey(): Promise<string>;
 //# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAYlD,wBAAgB,YAAY,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAStD;AAED,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CASvE;AAED,wBAAgB,SAAS,IAAI,MAAM,GAAG,SAAS,CAM9C;AAED,wBAAgB,UAAU,IAAI,MAAM,CAEnC;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,CAErD;AAED,wBAAsB,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC,CA+DrD"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAYlD,wBAAgB,YAAY,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAStD;AAED,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CASvE;AAED,wBAAgB,SAAS,IAAI,MAAM,GAAG,SAAS,CAM9C;AAED,wBAAgB,UAAU,IAAI,MAAM,CAEnC;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,CAErD;AAED,wBAAsB,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC,CAQrD;AAED,wBAAsB,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC,CAarD"}

package/dist/auth.js

@@ -3,7 +3,7 @@ import { join } from "node:path";
 import { homedir } from "node:os";
 import { Scorable } from "@root-signals/scorable";
 import { CliError } from "./types.js";
-import { printError, printInfo, printSuccess } from "./output.js";
+import { printError, printInfo } from "./output.js";
 function configDir() {
     return join(homedir(), ".scorable");
 }
@@ -52,60 +52,26 @@ export async function requireApiKey() {
     const key = getApiKey();
     if (key)
         return key;
-    printError("SCORABLE_API_KEY environment variable not set.");
-    const shell = process.env["SHELL"] ?? "";
-    if (shell.includes("fish")) {
-        printInfo("Run: set -x SCORABLE_API_KEY <your_key>");
-    }
-    else {
-        printInfo("Run: export SCORABLE_API_KEY='<your_key>'");
-    }
-    printInfo("Or run: scorable auth set-key <your-key>");
-    if (process.stdin.isTTY && process.stdout.isTTY) {
-        const { confirm } = await import("@inquirer/prompts");
-        const answer = await confirm({
-            message: "No API key found. Create a temporary key now?",
-            default: true,
-        });
-        if (!answer) {
-            printInfo("Aborted. Please set SCORABLE_API_KEY and try again.");
-            throw new CliError(1, "Aborted");
-        }
-        try {
-            const resp = await fetch(`${getBaseUrl()}/create-demo-user/`, { method: "POST" });
-            if (!resp.ok)
-                throw new Error(`HTTP ${resp.status}`);
-            const data = (await resp.json());
-            const tempKey = data["api_key"];
-            if (!tempKey) {
-                printError("Temporary key response did not include 'api_key'.");
-                throw new CliError(1, "Missing api_key in demo response");
-            }
-            process.env["SCORABLE_API_KEY"] = tempKey;
-            const settings = loadSettings();
-            settings["temporary_api_key"] = tempKey;
-            if (!saveSettings(settings)) {
-                printError("Failed to save temporary API key to ~/.scorable/settings.json");
-                throw new CliError(1, "Failed to save temporary API key");
-            }
-            printSuccess("Temporary API key saved to ~/.scorable/settings.json");
-            if (shell.includes("fish")) {
-                printInfo("To persist in your shell: set -x SCORABLE_API_KEY <paste_key_here>");
-            }
-            else {
-                printInfo("To persist in your shell: export SCORABLE_API_KEY='<paste_key_here>'");
-            }
-            return tempKey;
-        }
-        catch (e) {
-            if (e instanceof CliError)
-                throw e;
-            printError(`Failed to create temporary API key: ${e instanceof Error ? e.message : String(e)}`);
-            throw new CliError(1, "Failed to create temporary API key");
-        }
+    printError("No API key found.");
+    printInfo("Get a free demo key:   scorable auth demo-key");
+    printInfo("Set a permanent key:   scorable auth set-key <your-api-key>");
+    throw new CliError(1, "Missing API key");
+}
+export async function createDemoKey() {
+    try {
+        const resp = await fetch(`${getBaseUrl()}/create-demo-user/`, { method: "POST" });
+        if (!resp.ok)
+            throw new Error(`HTTP ${resp.status}`);
+        const data = (await resp.json());
+        const tempKey = data["api_key"];
+        if (!tempKey)
+            throw new Error("Response did not include 'api_key'");
+        return tempKey;
     }
-    else {
-        printInfo("Set SCORABLE_API_KEY and retry. Non-interactive session cannot prompt.");
-        throw new CliError(1, "Missing API key");
+    catch (e) {
+        if (e instanceof CliError)
+            throw e;
+        printError(`Failed to create demo key: ${e instanceof Error ? e.message : String(e)}`);
+        throw new CliError(1, "Failed to create demo key");
     }
 }

package/dist/commands/auth/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/auth/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAKpC,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAuC3D"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/auth/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAMpC,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAgE3D"}

package/dist/commands/auth/index.js

@@ -1,4 +1,5 @@
-import { loadSettings, saveSettings } from "../../auth.js";
+import ora from "ora";
+import { loadSettings, saveSettings, createDemoKey } from "../../auth.js";
 import { printSuccess, printError } from "../../output.js";
 import { CliError } from "../../types.js";
 export function registerAuthCommands(program) {
@@ -38,4 +39,28 @@ export function registerAuthCommands(program) {
         }
         printSuccess("API key saved to ~/.scorable/settings.json");
     });
+    auth
+        .command("demo-key")
+        .description("Create a free demo API key and save it to ~/.scorable/settings.json")
+        .action(async () => {
+        const spinner = ora("Creating demo key...").start();
+        try {
+            const key = await createDemoKey();
+            spinner.stop();
+            const settings = loadSettings();
+            settings["temporary_api_key"] = key;
+            if (!saveSettings(settings)) {
+                printError("Failed to save demo key to ~/.scorable/settings.json");
+                throw new CliError(1, "Failed to save demo key");
+            }
+            printSuccess(`Demo key saved to ~/.scorable/settings.json`);
+        }
+        catch (e) {
+            spinner.stop();
+            if (e instanceof CliError)
+                throw e;
+            printError(`Failed to create demo key: ${e instanceof Error ? e.message : String(e)}`);
+            throw new CliError(1, "Failed to create demo key");
+        }
+    });
 }

package/dist/commands/evaluator/generate.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+export declare function registerGenerateCommand(evaluator: Command): void;
+//# sourceMappingURL=generate.d.ts.map

package/dist/commands/evaluator/generate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../../src/commands/evaluator/generate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAcpC,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,OAAO,GAAG,IAAI,CAwDhE"}

package/dist/commands/evaluator/generate.js

@@ -0,0 +1,49 @@
+import ora from "ora";
+import { requireApiKey } from "../../auth.js";
+import { apiRequest } from "../../client.js";
+import { printSuccess, printError, printJson } from "../../output.js";
+import { CliError } from "../../types.js";
+export function registerGenerateCommand(evaluator) {
+    evaluator
+        .command("generate")
+        .description("Generate an evaluator from scored examples using AI")
+        .requiredOption("--examples <json>", 'JSON array of scored examples, e.g. \'[{"response":"Paris","score":1.0}]\'')
+        .option("--evaluation-approach <value>", "Evaluation approach (default: pointwise_score)", "pointwise_score")
+        .action(async (opts) => {
+        const apiKey = await requireApiKey();
+        let examples;
+        try {
+            examples = JSON.parse(opts.examples);
+            if (!Array.isArray(examples) || examples.length === 0) {
+                throw new Error("Must be a non-empty array");
+            }
+        }
+        catch (e) {
+            printError(`Invalid --examples JSON: ${e instanceof Error ? e.message : String(e)}`);
+            throw new CliError(1, "Invalid examples JSON");
+        }
+        const spinner = ora("Generating evaluator (this may take a moment)...").start();
+        try {
+            const result = (await apiRequest("POST", "v1/beta/evaluation-agents/generate", {
+                payload: {
+                    examples,
+                    evaluation_approach: opts.evaluationApproach,
+                },
+                apiKey,
+            }));
+            spinner.stop();
+            if (!result) {
+                throw new CliError(1, "Generate request failed");
+            }
+            printSuccess("Evaluator generated successfully!");
+            printJson(result);
+        }
+        catch (e) {
+            spinner.stop();
+            if (e instanceof CliError)
+                throw e;
+            printError(`Failed to generate evaluator: ${e instanceof Error ? e.message : String(e)}`);
+            throw new CliError(1, "Failed to generate evaluator");
+        }
+    });
+}

package/dist/commands/judge/generate.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+export declare function registerGenerateCommand(judge: Command): void;
+//# sourceMappingURL=generate.d.ts.map

package/dist/commands/judge/generate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../../src/commands/judge/generate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAcpC,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CA4H5D"}

package/dist/commands/judge/generate.js

@@ -0,0 +1,98 @@
+import ora from "ora";
+import chalk from "chalk";
+import { requireApiKey, getSdkClient } from "../../auth.js";
+import { printSuccess, printError, printWarning, printInfo, printJson, handleSdkError, } from "../../output.js";
+import { CliError } from "../../types.js";
+export function registerGenerateCommand(judge) {
+    judge
+        .command("generate")
+        .description("Generate a judge from an intent description using AI")
+        .addHelpText("after", `
+Example:
+  $ scorable judge generate \\
+      --intent "I am building a customer support chatbot for a hotel chain. \\
+I want to evaluate that responses are helpful, accurate, and reflect our brand tone. \\
+The chatbot must never make promises about pricing or availability, and should always \\
+offer to connect the guest with a human agent when uncertain."`)
+        .requiredOption("--intent <text>", "Detailed description of what the judge should evaluate")
+        .option("--visibility <value>", "Visibility of the generated judge: private, public", "private")
+        .option("--name <name>", "Optional name for the generated judge")
+        .option("--stage <stage>", "Stage name for the judge")
+        .option("--reasoning-effort <value>", "Reasoning effort for generation: off, low, medium, high")
+        .option("--judge-id <id>", "ID of an existing judge to regenerate")
+        .option("--overwrite", "Overwrite existing judge with the same name", false)
+        .option("--extra-contexts <json>", 'JSON object of additional context key-value pairs, e.g. \'{"Tone Of Voice":"formal","Domain":"hotel chatbot"}\'')
+        .option("--context-aware", "Enable context-aware evaluators for RAG applications (hallucination detection, context drift, etc.)", false)
+        .action(async (opts) => {
+        const acceptedVisibilities = ["private", "public"];
+        const visibility = opts.visibility;
+        if (!acceptedVisibilities.includes(visibility)) {
+            printError(`Invalid --visibility value: "${visibility}". Accepted values: private, public.`);
+            throw new CliError(1, "invalid_visibility");
+        }
+        const apiVisibility = visibility === "private" ? "unlisted" : "public";
+        const apiKey = await requireApiKey();
+        let extra_contexts;
+        if (opts.extraContexts) {
+            try {
+                extra_contexts = JSON.parse(opts.extraContexts);
+            }
+            catch {
+                printError("Invalid --extra-contexts JSON: must be a key-value object.");
+                throw new CliError(1, "Invalid extra-contexts JSON");
+            }
+        }
+        const spinner = ora("Generating judge (this may take a moment)...").start();
+        try {
+            const client = getSdkClient(apiKey);
+            const result = await client.judges.generate({
+                intent: opts.intent,
+                visibility: apiVisibility,
+                overwrite: opts.overwrite,
+                name: opts.name,
+                stage: opts.stage,
+                judge_id: opts.judgeId,
+                extra_contexts: extra_contexts ?? null,
+                enable_context_aware_evaluators: opts.contextAware || undefined,
+                ...(opts.reasoningEffort && {
+                    generating_model_params: {
+                        reasoning_effort: opts.reasoningEffort,
+                    },
+                }),
+            });
+            spinner.stop();
+            if (result.error_code === "multiple_stages") {
+                printWarning("Multiple evaluation stages detected. Each judge covers one stage.");
+                printInfo("Detected stages:");
+                for (const s of result.stages ?? []) {
+                    console.log(`    ${chalk.cyan("·")} ${s}`);
+                }
+                printInfo('Re-run with --stage "<stage name>" to target a specific stage.');
+                throw new CliError(1, "multiple_stages");
+            }
+            if (result.error_code) {
+                printError(`Generation failed with error code: ${result.error_code}`);
+                throw new CliError(1, result.error_code ?? "generation_failed");
+            }
+            const missingContext = result.missing_context_from_system_goal;
+            if (missingContext?.length) {
+                printSuccess("Judge created — but additional context would improve it:");
+                console.log();
+                for (const field of missingContext) {
+                    console.log(`    ${chalk.bold(field.form_field_name)}`);
+                    console.log(`    ${chalk.dim(field.form_field_description)}`);
+                    console.log();
+                }
+                printInfo(`Re-run with --judge-id "${result.judge_id}" and --extra-contexts to refine.`);
+            }
+            else {
+                printSuccess("Judge generated successfully!");
+            }
+            printJson(result);
+        }
+        catch (e) {
+            spinner.stop();
+            handleSdkError(e);
+        }
+    });
+}

package/dist/commands/judge/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/judge/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAYpC,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAe5D"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/judge/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAapC,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAgB5D"}

package/dist/commands/judge/index.js

@@ -7,6 +7,7 @@ import { registerDeleteCommand } from "./delete.js";
 import { registerExecuteCommand } from "./execute.js";
 import { registerExecuteByNameCommand } from "./execute-by-name.js";
 import { registerDuplicateCommand } from "./duplicate.js";
+import { registerGenerateCommand } from "./generate.js";
 import { registerExecOpenaiCommand } from "./exec-openai.js";
 import { registerExecOpenaiGenericCommand } from "./exec-openai-generic.js";
 export function registerJudgeCommands(program) {
@@ -19,6 +20,7 @@ export function registerJudgeCommands(program) {
     registerExecuteCommand(judge);
     registerExecuteByNameCommand(judge);
     registerDuplicateCommand(judge);
+    registerGenerateCommand(judge);
     registerExecOpenaiCommand(judge);
     registerExecOpenaiGenericCommand(judge);
     program.addCommand(judge);

package/dist/commands/prompt-test/index.js

@@ -8,6 +8,6 @@ function buildPtGroup(name) {
     return pt;
 }
 export function registerPromptTestCommands(program) {
-    program.addCommand(buildPtGroup("pt"));
+    program.addCommand(buildPtGroup("pt"), { hidden: true });
     program.addCommand(buildPtGroup("prompt-test"));
 }

package/dist/commands/prompt-test/run.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../../src/commands/prompt-test/run.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA0FpC,wBAAsB,cAAc,CAClC,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,UAAU,EAAE,MAAM,EAClB,KAAK,GAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAiD,GACnF,OAAO,CAAC,IAAI,CAAC,CAiHf;AAED,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI,CAYpD"}
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../../src/commands/prompt-test/run.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA6GpC,wBAAsB,cAAc,CAClC,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,UAAU,EAAE,MAAM,EAClB,KAAK,GAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAiD,GACnF,OAAO,CAAC,IAAI,CAAC,CAiHf;AAED,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI,CAYpD"}

package/dist/commands/prompt-test/run.js

@@ -1,9 +1,27 @@
 import { readFileSync, writeFileSync } from "node:fs";
 import yaml from "js-yaml";
+import chalk from "chalk";
 import Table from "cli-table3";
 import { requireApiKey } from "../../auth.js";
 import { apiRequest } from "../../client.js";
 import { printInfo, printSuccess, printWarning, printError, handleSdkError } from "../../output.js";
+const UNICODE_CHARS = {
+    top: "─",
+    "top-mid": "┬",
+    "top-left": "┌",
+    "top-right": "┐",
+    bottom: "─",
+    "bottom-mid": "┴",
+    "bottom-left": "└",
+    "bottom-right": "┘",
+    left: "│",
+    "left-mid": "├",
+    mid: "─",
+    "mid-mid": "┼",
+    right: "│",
+    "right-mid": "┤",
+    middle: "│",
+};
 import { CliError } from "../../types.js";
 function isPromptTestComplete(exp) {
     if (!exp.tasks.length)
@@ -12,8 +30,8 @@ function isPromptTestComplete(exp) {
 }
 function displayProgressTable(experiments) {
     const table = new Table({
-        head: ["Prompt Test ID", "Status", "Tasks Completed"],
-        style: { head: ["cyan"] },
+        head: ["Prompt Test ID", "Status", "Tasks Completed"].map((h) => chalk.bold.cyan(h)),
+        chars: UNICODE_CHARS,
     });
     for (const exp of experiments) {
         const done = exp.tasks.filter((t) => t.status === "completed" || t.status === "failed").length;
@@ -48,8 +66,8 @@ function displayAggregatedResults(experiments) {
             "Latency (s)",
             "Output",
             ...sortedEvalIds.map((id) => allEvaluators.get(id)),
-        ],
-        style: { head: ["cyan"] },
+        ].map((h) => chalk.bold.cyan(h)),
+        chars: UNICODE_CHARS,
         wordWrap: true,
     });
     for (const exp of experiments) {

package/dist/commands/skills-add.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+export declare function registerSkillsAddCommand(program: Command): void;
+//# sourceMappingURL=skills-add.d.ts.map

package/dist/commands/skills-add.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills-add.d.ts","sourceRoot":"","sources":["../../src/commands/skills-add.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA0B/D"}

package/dist/commands/skills-add.js

@@ -0,0 +1,29 @@
+import { spawn } from "node:child_process";
+import { CliError } from "../types.js";
+import { printSuccess, printInfo } from "../output.js";
+export function registerSkillsAddCommand(program) {
+    program
+        .command("skills-add")
+        .description("Install Scorable Skills for coding agents")
+        .action(async () => {
+        await new Promise((resolve, reject) => {
+            const child = spawn("npx", ["skills", "add", "root-signals/scorable-skills"], {
+                stdio: "inherit",
+            });
+            child.on("close", (code) => {
+                if (code !== 0) {
+                    reject(new CliError(code ?? 1, `skills add exited with code ${code}`));
+                }
+                else {
+                    resolve();
+                }
+            });
+            child.on("error", (err) => {
+                reject(new CliError(1, `Failed to run npx skills: ${err.message}`));
+            });
+        });
+        console.log();
+        printSuccess("Scorable skills installed.");
+        printInfo('Open your coding agent in your AI powered project and use the prompt: "Integrate scorable evaluators"');
+    });
+}

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAIA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AASpC,wBAAgB,SAAS,IAAI,OAAO,CAwBnC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAIA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAgDpC,wBAAgB,SAAS,IAAI,OAAO,CAoBnC"}

package/dist/index.js

@@ -3,30 +3,64 @@ import { realpathSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { createRequire } from "node:module";
 import { Command } from "commander";
+import chalk from "chalk";
 import { registerJudgeCommands } from "./commands/judge/index.js";
 import { registerPromptTestCommands } from "./commands/prompt-test/index.js";
 import { registerEvaluatorCommands } from "./commands/evaluator/index.js";
 import { registerExecutionLogCommands } from "./commands/execution-log/index.js";
 import { registerAuthCommands } from "./commands/auth/index.js";
+import { registerSkillsAddCommand } from "./commands/skills-add.js";
 const { version } = createRequire(import.meta.url)("../package.json");
+function buildBanner(ver) {
+    const logo = chalk.hex("#4D9FFF");
+    const name = chalk.bold.hex("#4D9FFF")("scorable");
+    const tag = chalk.dim(`v${ver}`);
+    const tagline = chalk.dim("Measurement & Control for LLM Automations");
+    const line = chalk.dim("─".repeat(52));
+    return [
+        "",
+        `  ${logo("┌─┐")}  ${name}  ${tag}`,
+        `  ${logo("╰◈╯")}  ${tagline}`,
+        `     ${line}`,
+    ].join("\n");
+}
+function buildGettingStarted() {
+    const header = chalk.bold("Getting started");
+    const line = chalk.dim("─".repeat(52));
+    const num = (n) => chalk.dim(n + ".");
+    const cmd = (s) => chalk.cyan(s);
+    return [
+        "",
+        `  ${header}`,
+        `  ${line}`,
+        `  ${num("1")} Authenticate ${chalk.dim("(pick one)")}:`,
+        `       ${cmd("$ scorable auth demo-key")}           ${chalk.dim("# for quick testing")}`,
+        `       ${cmd("$ scorable auth set-key <api-key>")}  ${chalk.dim("# permanent key")}`,
+        `  ${num("2")} Install skills for your AI coding agent:`,
+        `       ${cmd("$ scorable skills-add")}`,
+        `  ${num("3")} Explore resources:`,
+        `       ${cmd("$ scorable judge list")}`,
+        `       ${cmd("$ scorable evaluator list")}`,
+        "",
+    ].join("\n");
+}
 export function createCli() {
     const program = new Command()
         .name("scorable")
         .description("A CLI tool to interact with the Scorable API")
         .version(version, "-V, --version", "Print version number")
-        .addHelpText("after", `
-Getting started:
-  Set your API key first (required before any command):
-  $ scorable auth set-key <your-api-key>
-
-  Then use any command, e.g.:
-  $ scorable judge list`)
-        .exitOverride();
+        .addHelpText("before", buildBanner(version))
+        .addHelpText("after", buildGettingStarted())
+        .exitOverride()
+        .action(() => {
+        program.outputHelp();
+    });
     registerJudgeCommands(program);
     registerPromptTestCommands(program);
     registerEvaluatorCommands(program);
     registerExecutionLogCommands(program);
     registerAuthCommands(program);
+    registerSkillsAddCommand(program);
     return program;
 }
 if (realpathSync(fileURLToPath(import.meta.url)) === realpathSync(process.argv[1])) {

package/dist/output.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../src/output.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAEzF,wBAAgB,SAAS,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAE7C;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAE5C;AAED,wBAAgB,cAAc,CAAC,CAAC,EAAE,OAAO,GAAG,KAAK,CAKhD;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAE9C;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAE3C;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAE9C;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAE9C;AAMD,wBAAgB,eAAe,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAmB1E;AAED,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,iBAAiB,EAAE,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAmB9F;AAED,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,gBAAgB,EAAE,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAoB1F"}
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../src/output.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAoBzF,wBAAgB,SAAS,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAE7C;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAE5C;AAED,wBAAgB,cAAc,CAAC,CAAC,EAAE,OAAO,GAAG,KAAK,CAKhD;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAE9C;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAE3C;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAE9C;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAE9C;AAMD,wBAAgB,eAAe,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAmB1E;AAED,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,iBAAiB,EAAE,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAmB9F;AAED,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,gBAAgB,EAAE,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAoB1F"}

package/dist/output.js

@@ -1,11 +1,28 @@
 import chalk from "chalk";
 import Table from "cli-table3";
 import { CliError } from "./types.js";
+const UNICODE_CHARS = {
+    top: "─",
+    "top-mid": "┬",
+    "top-left": "┌",
+    "top-right": "┐",
+    bottom: "─",
+    "bottom-mid": "┴",
+    "bottom-left": "└",
+    "bottom-right": "┘",
+    left: "│",
+    "left-mid": "├",
+    mid: "─",
+    "mid-mid": "┼",
+    right: "│",
+    "right-mid": "┤",
+    middle: "│",
+};
 export function printJson(data) {
     console.log(JSON.stringify(data, null, 2));
 }
 export function printError(msg) {
-    console.error(chalk.bold.red("Error:") + " " + msg);
+    console.error(chalk.red("✖") + " " + msg);
 }
 export function handleSdkError(e) {
     if (e instanceof CliError)
@@ -15,13 +32,13 @@ export function handleSdkError(e) {
     throw new CliError(1, message);
 }
 export function printSuccess(msg) {
-    console.log(chalk.bold.green("Success:") + " " + msg);
+    console.log(chalk.green("✔") + " " + msg);
 }
 export function printInfo(msg) {
-    console.log(chalk.bold.blue("Info:") + " " + msg);
+    console.log(chalk.cyan("›") + " " + msg);
 }
 export function printWarning(msg) {
-    console.log(chalk.bold.yellow("Warning:") + " " + msg);
+    console.log(chalk.yellow("⚠") + " " + msg);
 }
 export function printMessage(msg) {
     console.log(msg);
@@ -31,8 +48,8 @@ function truncate(s, max) {
 }
 export function printJudgeTable(judges, nextCursor) {
     const table = new Table({
-        head: ["ID", "Name", "Intent", "Created At"],
-        style: { head: ["cyan"] },
+        head: ["ID", "Name", "Intent", "Created At"].map((h) => chalk.bold.cyan(h)),
+        chars: UNICODE_CHARS,
         colWidths: [38, 30, 52, 12],
         wordWrap: true,
     });
@@ -48,8 +65,8 @@ export function printJudgeTable(judges, nextCursor) {
 }
 export function printEvaluatorTable(evaluators, nextCursor) {
     const table = new Table({
-        head: ["ID", "Name", "Created At"],
-        style: { head: ["cyan"] },
+        head: ["ID", "Name", "Created At"].map((h) => chalk.bold.cyan(h)),
+        chars: UNICODE_CHARS,
         colWidths: [38, 30, 12],
         wordWrap: true,
     });
@@ -65,8 +82,8 @@ export function printEvaluatorTable(evaluators, nextCursor) {
 }
 export function printExecutionLogTable(logs, nextCursor) {
     const table = new Table({
-        head: ["ID", "Item Name", "Type", "Score", "Created At"],
-        style: { head: ["cyan"] },
+        head: ["ID", "Item Name", "Type", "Score", "Created At"].map((h) => chalk.bold.cyan(h)),
+        chars: UNICODE_CHARS,
         colWidths: [38, 30, 15, 8, 12],
         wordWrap: true,
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@root-signals/scorable-cli",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "CLI for Scorable",
   "license": "Apache-2.0",
   "author": "Scorable",
@@ -31,7 +31,7 @@
   },
   "dependencies": {
     "@inquirer/prompts": "^8.3.2",
-    "@root-signals/scorable": "^0.3.0",
+    "@root-signals/scorable": "^0.3.1",
     "chalk": "^5.6.2",
     "cli-table3": "^0.6.5",
     "commander": "^14.0.3",