@overscore/cli 0.13.21 → 0.13.22

package/dist/homes.js

@@ -0,0 +1,134 @@
+import fs from "fs";
+import path from "path";
+import os from "os";
+const SCHEMA_VERSION = 1;
+const CONFIG_DIR = path.join(os.homedir(), ".overscore");
+const HOMES_PATH = path.join(CONFIG_DIR, "homes.json");
+const LOCK_PATH = HOMES_PATH + ".lock";
+const LOCK_STALE_MS = 10000;
+// Managed workspace root. Project-nested from day one so that graduating a project to a
+// dbt workspace is purely additive: the workspace wrapper drops in at the project root
+// and `overscore/<slug>/` never has to move.
+export function managedRoot() {
+    return path.join(os.homedir(), "Overscore");
+}
+export function managedProjectDir(projectSlug) {
+    return path.join(managedRoot(), projectSlug);
+}
+export function managedOverscoreDir(projectSlug) {
+    return path.join(managedProjectDir(projectSlug), "overscore");
+}
+export function managedDashboardDir(projectSlug, dashboardSlug) {
+    return path.join(managedOverscoreDir(projectSlug), dashboardSlug);
+}
+function readHomesFile() {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(HOMES_PATH, "utf-8"));
+        if (parsed && typeof parsed === "object" && parsed.homes) {
+            return { schema_version: parsed.schema_version ?? SCHEMA_VERSION, homes: parsed.homes };
+        }
+    }
+    catch {
+        // Missing or corrupt. Atomic rename means a reader never sees a torn write, so a parse
+        // failure means no file yet (or a truly hand-mangled one) — start fresh.
+    }
+    return { schema_version: SCHEMA_VERSION, homes: {} };
+}
+// Reads are lock-free: writes rename atomically, so a reader sees either the old or the new
+// complete file, never a partial one. Returns null if the project has no home recorded yet.
+export function getHome(projectSlug) {
+    return readHomesFile().homes[projectSlug] ?? null;
+}
+// A cross-process advisory lock so a read-modify-write from `overscore open` can't lose an
+// update raced against a concurrent `workspace` write. Exclusive-create the lockfile; if
+// it's held, wait, and reclaim it only if it's gone stale.
+function withLock(fn) {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true });
+    const start = Date.now();
+    // Small synchronous sleep without pulling in a dependency.
+    const sleep = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+    for (;;) {
+        try {
+            const fd = fs.openSync(LOCK_PATH, "wx");
+            fs.writeSync(fd, String(process.pid));
+            fs.closeSync(fd);
+            break;
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                throw err;
+            let age = Infinity;
+            try {
+                age = Date.now() - fs.statSync(LOCK_PATH).mtimeMs;
+            }
+            catch {
+                continue; // lock vanished between openSync and statSync — retry immediately
+            }
+            if (age > LOCK_STALE_MS) {
+                try {
+                    fs.rmSync(LOCK_PATH, { force: true });
+                }
+                catch {
+                    /* someone else reclaimed it */
+                }
+                continue;
+            }
+            if (Date.now() - start > LOCK_STALE_MS) {
+                throw new Error("Timed out waiting for the homes.json lock");
+            }
+            sleep(50);
+        }
+    }
+    try {
+        return fn();
+    }
+    finally {
+        try {
+            fs.rmSync(LOCK_PATH, { force: true });
+        }
+        catch {
+            /* best effort */
+        }
+    }
+}
+function writeAtomic(data) {
+    const tmp = `${HOMES_PATH}.tmp-${process.pid}`;
+    fs.writeFileSync(tmp, JSON.stringify(data, null, 2));
+    // On Windows a rename can transiently fail with EPERM/EBUSY if a lock-free reader has the
+    // file open; retry briefly rather than crash after side effects.
+    for (let attempt = 0;; attempt++) {
+        try {
+            fs.renameSync(tmp, HOMES_PATH);
+            return;
+        }
+        catch (err) {
+            const code = err.code;
+            if (process.platform === "win32" && (code === "EPERM" || code === "EBUSY") && attempt < 5) {
+                Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 20);
+                continue;
+            }
+            try {
+                fs.rmSync(tmp, { force: true });
+            }
+            catch {
+                /* best effort */
+            }
+            throw err;
+        }
+    }
+}
+// Record (or update) where a project lives: locked read-modify-write + atomic replace. Refuses
+// to write over a homes.json written by a newer CLI, so an old binary can't downgrade/corrupt it.
+export function setHome(projectSlug, entry) {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true });
+    withLock(() => {
+        const file = readHomesFile();
+        if (file.schema_version > SCHEMA_VERSION) {
+            throw new Error(`~/.overscore/homes.json is version ${file.schema_version}, but this Overscore CLI only ` +
+                `understands version ${SCHEMA_VERSION}. Update the CLI (npm i -g @overscore/cli).`);
+        }
+        file.schema_version = SCHEMA_VERSION;
+        file.homes[projectSlug] = entry;
+        writeAtomic(file);
+    });
+}

package/dist/index.js

@@ -9,6 +9,7 @@ import { createInterface } from "readline";
 import { createHash, randomBytes } from "crypto";
 import yauzl from "yauzl";
 import { templatePush } from "./template-push.js";
+import { getHome, setHome, managedProjectDir, managedOverscoreDir, managedDashboardDir, } from "./homes.js";
 // ── Shared helpers ──────────────────────────────────────────────────
 // Name CLI-minted API keys after the machine + date so stale keys are
 // recognizable and revocable in the Hub UI (mitigates key sprawl). Keys are
@@ -75,7 +76,7 @@ async function loadEnv() {
         }
         // .env has project context but no API key — generate one via device token
         if (projectSlug) {
-            const globalCfgPath = path.join(process.env.HOME || "", ".overscore", "config");
+            const globalCfgPath = path.join(os.homedir(), ".overscore", "config");
             const globalCfg = fs.existsSync(globalCfgPath)
                 ? parseEnv(fs.readFileSync(globalCfgPath, "utf-8"))
                 : {};
@@ -98,7 +99,7 @@ async function loadEnv() {
         }
     }
     // (2) Global config (works from analysis folders or anywhere)
-    const configPath = path.join(process.env.HOME || "", ".overscore", "config");
+    const configPath = path.join(os.homedir(), ".overscore", "config");
     if (fs.existsSync(configPath)) {
         const cfg = parseEnv(fs.readFileSync(configPath, "utf-8"));
         if (cfg.OVERSCORE_API_KEY) {
@@ -125,7 +126,7 @@ async function loadEnv() {
     // No creds — trigger browser auth inline, then re-check
     console.log("\n  No Overscore credentials found. Launching browser login...\n");
     await authLogin();
-    const configPath2 = path.join(process.env.HOME || "", ".overscore", "config");
+    const configPath2 = path.join(os.homedir(), ".overscore", "config");
     if (fs.existsSync(configPath2)) {
         const cfg2 = parseEnv(fs.readFileSync(configPath2, "utf-8"));
         if (cfg2.OVERSCORE_API_KEY) {
@@ -229,7 +230,7 @@ function prompt(message) {
     });
 }
 async function refreshApiKey(projectSlug) {
-    const configDir = path.join(process.env.HOME || "", ".overscore");
+    const configDir = path.join(os.homedir(), ".overscore");
     const configPath = path.join(configDir, "config");
     let cfg = fs.existsSync(configPath)
         ? parseEnv(fs.readFileSync(configPath, "utf-8"))
@@ -1053,7 +1054,7 @@ async function pull(slug) {
         : null;
     // Resolve API key: device token → auto-create os_ key, else the saved project key, else prompt.
     let apiKey = "";
-    const configPath = path.join(process.env.HOME || "", ".overscore", "config");
+    const configPath = path.join(os.homedir(), ".overscore", "config");
     const cfg = fs.existsSync(configPath)
         ? parseEnv(fs.readFileSync(configPath, "utf-8"))
         : {};
@@ -1337,7 +1338,7 @@ async function listDashboards() {
 // project-scoped API key, so it can enumerate EVERY project on the account —
 // including empty ones a project key could never see.
 async function listProjects() {
-    const configPath = path.join(process.env.HOME || "", ".overscore", "config");
+    const configPath = path.join(os.homedir(), ".overscore", "config");
     const readToken = () => {
         const cfg = fs.existsSync(configPath)
             ? parseEnv(fs.readFileSync(configPath, "utf-8"))
@@ -1493,7 +1494,7 @@ async function loadAnalysisConfig() {
         }
     }
     // (2) ~/.overscore/config
-    const configDir = path.join(process.env.HOME || "", ".overscore");
+    const configDir = path.join(os.homedir(), ".overscore");
     const configPath = path.join(configDir, "config");
     if (fs.existsSync(configPath)) {
         const cfg = parseEnv(fs.readFileSync(configPath, "utf-8"));
@@ -2881,7 +2882,7 @@ async function dev() {
     // "Invalid API key".
     assertHubMatchesEnv();
     // Get device token from global config
-    const configPath = path.join(process.env.HOME || "", ".overscore", "config");
+    const configPath = path.join(os.homedir(), ".overscore", "config");
     if (!fs.existsSync(configPath)) {
         console.error("\n  Error: Not authenticated. Run 'npx @overscore/cli auth login' first.\n");
         process.exit(1);
@@ -2978,7 +2979,7 @@ async function dev() {
 }
 // ── auth ────────────────────────────────────────────────────────────
 async function authStatus() {
-    const configPath = path.join(process.env.HOME || "", ".overscore", "config");
+    const configPath = path.join(os.homedir(), ".overscore", "config");
     if (fs.existsSync(configPath)) {
         const cfg = parseEnv(fs.readFileSync(configPath, "utf-8"));
         const deviceToken = cfg.OVERSCORE_DEVICE_TOKEN;
@@ -3004,7 +3005,7 @@ async function authStatus() {
 `);
 }
 async function authLogin() {
-    const configDir = path.join(process.env.HOME || "", ".overscore");
+    const configDir = path.join(os.homedir(), ".overscore");
     const configPath = path.join(configDir, "config");
     const state = randomBytes(16).toString("hex");
     // Find a free port in range 9876–9886
@@ -3083,11 +3084,13 @@ async function authLogin() {
     const { token: deviceToken, project: projectSlug } = await callbackPromise;
     clearTimeout(timeout);
     server.close();
-    // Preserve any existing os_ API key so dashboard .env fallback still works
+    // Preserve any existing os_ API key + saved tool preference so re-login doesn't drop them
     let existingApiKey = "";
+    let existingTool = "";
     if (fs.existsSync(configPath)) {
         const existing = parseEnv(fs.readFileSync(configPath, "utf-8"));
         existingApiKey = existing.OVERSCORE_API_KEY || "";
+        existingTool = existing.OVERSCORE_TOOL || "";
     }
     fs.mkdirSync(configDir, { recursive: true });
     const lines = [
@@ -3098,6 +3101,8 @@ async function authLogin() {
         lines.push(`OVERSCORE_PROJECT_SLUG=${projectSlug}`);
     if (existingApiKey)
         lines.push(`OVERSCORE_API_KEY=${existingApiKey}`);
+    if (existingTool)
+        lines.push(`OVERSCORE_TOOL=${existingTool}`);
     fs.writeFileSync(configPath, lines.join("\n") + "\n", { mode: 0o600 });
     console.log(`
   Authenticated!
@@ -3108,7 +3113,7 @@ async function authLogin() {
 `);
 }
 async function authLogout() {
-    const configPath = path.join(process.env.HOME || "", ".overscore", "config");
+    const configPath = path.join(os.homedir(), ".overscore", "config");
     if (fs.existsSync(configPath)) {
         // Attempt server-side revocation of the device token (non-fatal)
         try {
@@ -3142,7 +3147,7 @@ async function installSkills() {
         console.error(`\n  Error: Bundled skills directory not found at ${skillsSrc}\n`);
         process.exit(1);
     }
-    const homeSkills = path.join(process.env.HOME || "", ".claude", "skills");
+    const homeSkills = path.join(os.homedir(), ".claude", "skills");
     fs.mkdirSync(homeSkills, { recursive: true });
     const installed = [];
     for (const entry of fs.readdirSync(skillsSrc, { withFileTypes: true })) {
@@ -3189,7 +3194,7 @@ async function templatePull(slug) {
         res = await fetch(url, {
             // Optional: attach device token if available, for attribution in install counting
             headers: (() => {
-                const configPath = path.join(process.env.HOME || "", ".overscore", "config");
+                const configPath = path.join(os.homedir(), ".overscore", "config");
                 if (fs.existsSync(configPath)) {
                     const cfg = parseEnv(fs.readFileSync(configPath, "utf-8"));
                     if (cfg.OVERSCORE_DEVICE_TOKEN) {
@@ -3260,6 +3265,263 @@ async function templatePull(slug) {
 // ── Routing ─────────────────────────────────────────────────────────
 const command = process.argv[2];
 const subcommand = process.argv[3];
+const OPEN_TOOL_LABELS = {
+    code: "VS Code",
+    cursor: "Cursor",
+    claude: "Claude Code (terminal)",
+    codex: "Codex",
+};
+const OPEN_TOOLS = ["code", "cursor", "claude", "codex"];
+const DASHBOARD_STARTER = "Build me a professional dashboard for this data.";
+const WORKSPACE_STARTER = "Read the catalog first, then help me build or update a dashboard for this client.";
+function openCmdOnPath(cmd) {
+    try {
+        execSync(process.platform === "win32" ? `where ${cmd}` : `command -v ${cmd}`, {
+            stdio: "ignore",
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function detectOpenTools() {
+    return OPEN_TOOLS.filter((t) => openCmdOnPath(t));
+}
+function saveConfigValue(key, value) {
+    const dir = path.join(os.homedir(), ".overscore");
+    const configPath = path.join(dir, "config");
+    const cfg = fs.existsSync(configPath)
+        ? parseEnv(fs.readFileSync(configPath, "utf-8"))
+        : {};
+    cfg[key] = value;
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(configPath, Object.entries(cfg)
+        .map(([k, v]) => `${k}=${v}`)
+        .join("\n") + "\n", { mode: 0o600 });
+}
+// Which tool to open in: an explicit --tool wins, then a remembered choice, then detection
+// (one installed → use it; several → ask once and remember). Null if nothing is installed.
+async function chooseOpenTool(explicit) {
+    if (explicit && OPEN_TOOLS.includes(explicit))
+        return explicit;
+    const configPath = path.join(os.homedir(), ".overscore", "config");
+    const cfg = fs.existsSync(configPath)
+        ? parseEnv(fs.readFileSync(configPath, "utf-8"))
+        : {};
+    const saved = cfg.OVERSCORE_TOOL;
+    if (saved && OPEN_TOOLS.includes(saved))
+        return saved;
+    const available = detectOpenTools();
+    if (available.length === 0)
+        return null;
+    let chosen;
+    if (available.length === 1) {
+        chosen = available[0];
+    }
+    else {
+        console.log("\n  Which tool do you build with?");
+        available.forEach((t, i) => console.log(`    ${i + 1}) ${OPEN_TOOL_LABELS[t]}`));
+        const ans = await prompt(`Choose 1-${available.length}:`);
+        chosen = available[parseInt(ans, 10) - 1] ?? available[0];
+    }
+    saveConfigValue("OVERSCORE_TOOL", chosen);
+    return chosen;
+}
+function launchUrl(url) {
+    try {
+        if (process.platform === "darwin")
+            execSync(`open '${url}'`);
+        else if (process.platform === "win32")
+            execSync(`start "" "${url}"`);
+        else
+            execSync(`xdg-open '${url}'`);
+    }
+    catch {
+        /* best effort */
+    }
+}
+// Open a folder in the chosen tool. GUI editors open cleanly by spawning their launcher;
+// terminal agents can't be launched cleanly everywhere, so we hand back a copy-paste hint.
+function openFolderInTool(tool, dir, starter) {
+    try {
+        if (tool === "code") {
+            execSync(`code -r "${dir}"`, { stdio: "ignore" });
+            return { opened: true, hint: "" };
+        }
+        if (tool === "cursor") {
+            execSync(`cursor "${dir}"`, { stdio: "ignore" });
+            return { opened: true, hint: "" };
+        }
+        if (tool === "claude") {
+            // Opens a terminal running claude in the folder (pre-fills, does not send, the prompt).
+            // The handler only registers after the first interactive claude session, so also give
+            // the manual fallback.
+            launchUrl(`claude-cli://open?cwd=${encodeURIComponent(dir)}&q=${encodeURIComponent(starter)}`);
+            return { opened: true, hint: `If Claude didn't open, run:  cd "${dir}" && claude` };
+        }
+        // codex: no folder deep link — hand over the exact command.
+        return { opened: false, hint: `cd "${dir}" && codex` };
+    }
+    catch {
+        return { opened: false, hint: `Open "${dir}" in ${OPEN_TOOL_LABELS[tool]} to start building.` };
+    }
+}
+function runOpenChild(cmd, cwd) {
+    try {
+        execSync(cmd, { cwd, stdio: "inherit" });
+    }
+    catch {
+        console.error(`\n  Error: setup step failed:\n    ${cmd}\n`);
+        process.exit(1);
+    }
+}
+async function probeDashboard(deviceToken, projectSlug, dashboardSlug) {
+    let apiKey = "";
+    try {
+        const keyRes = await fetch(`${HUB_URL}/api/projects/${projectSlug}/api-keys`, {
+            method: "POST",
+            headers: { Authorization: `Bearer ${deviceToken}`, "Content-Type": "application/json" },
+            body: JSON.stringify({ name: `${projectSlug} open key` }),
+        });
+        if (keyRes.status === 401 || keyRes.status === 403)
+            return { state: "unauthorized", apiKey };
+        if (!keyRes.ok)
+            return { state: "error", apiKey };
+        apiKey = (await keyRes.json()).raw_key || "";
+    }
+    catch {
+        return { state: "error", apiKey };
+    }
+    if (!apiKey)
+        return { state: "error", apiKey };
+    try {
+        const vRes = await fetch(`${HUB_URL}/api/dashboards/${dashboardSlug}/versions`, {
+            headers: { Authorization: `Bearer ${apiKey}` },
+        });
+        if (vRes.status === 401 || vRes.status === 403)
+            return { state: "unauthorized", apiKey };
+        if (vRes.status === 404)
+            return { state: "new", apiKey };
+        if (!vRes.ok)
+            return { state: "error", apiKey };
+        const data = (await vRes.json());
+        const deployed = Array.isArray(data.versions) && data.versions.length > 0;
+        return { state: deployed ? "deployed" : "new", apiKey };
+    }
+    catch {
+        return { state: "error", apiKey };
+    }
+}
+function finishOpen(res, dir) {
+    console.log(res.opened ? `\n  Opened in your tool:\n    ${dir}` : `\n  Ready at:\n    ${dir}`);
+    if (res.hint)
+        console.log(`\n  ${res.hint}`);
+    console.log(`\n  Tell your AI tool what to build. When it looks right, say "deploy it".\n`);
+}
+async function open(dashboardSlug) {
+    if (!dashboardSlug || dashboardSlug.startsWith("--")) {
+        console.error("\n  Usage: npx @overscore/cli open <dashboard-slug> --project <slug> [--tool code|cursor|claude|codex]\n");
+        process.exit(1);
+    }
+    const projIdx = process.argv.indexOf("--project");
+    const projectSlug = projIdx !== -1 && process.argv[projIdx + 1] && !process.argv[projIdx + 1].startsWith("--")
+        ? process.argv[projIdx + 1]
+        : null;
+    if (!projectSlug) {
+        console.error(`\n  Error: --project <slug> is required.`);
+        console.error(`    npx @overscore/cli open ${dashboardSlug} --project <project-slug>\n`);
+        process.exit(1);
+    }
+    // Slugs get interpolated into shell commands and filesystem paths below, so validate them
+    // strictly (lowercase alphanumeric + hyphens) — this also blocks command injection.
+    const SLUG_RE = /^[a-z0-9][a-z0-9-]*$/;
+    if (!SLUG_RE.test(dashboardSlug) || !SLUG_RE.test(projectSlug)) {
+        console.error("\n  Error: project and dashboard slugs must be lowercase letters, numbers, and hyphens.\n");
+        process.exit(1);
+    }
+    const toolIdx = process.argv.indexOf("--tool");
+    const toolFlag = toolIdx !== -1 ? process.argv[toolIdx + 1] : undefined;
+    // 1. Ensure a device token (browser login if needed) — the same file every tool reads.
+    const configPath = path.join(os.homedir(), ".overscore", "config");
+    const readToken = () => (fs.existsSync(configPath) ? parseEnv(fs.readFileSync(configPath, "utf-8")) : {})
+        .OVERSCORE_DEVICE_TOKEN;
+    let deviceToken = readToken();
+    if (!deviceToken) {
+        console.log("\n  No session found. Signing you in...\n");
+        await authLogin();
+        deviceToken = readToken();
+        if (!deviceToken) {
+            console.error("\n  Could not authenticate.\n");
+            process.exit(1);
+        }
+    }
+    // 2. Coexistence: if a dbt workspace already owns this project, open it there instead of
+    //    making a second, divergent copy.
+    const existing = getHome(projectSlug);
+    if (existing?.mode === "workspace") {
+        console.log(`\n  Project "${projectSlug}" is managed by a workspace at:\n    ${existing.path}`);
+        const tool = await chooseOpenTool(toolFlag);
+        if (!tool) {
+            console.log(`\n  Install an AI coding tool, then open that folder to build.\n`);
+            return;
+        }
+        finishOpen(openFolderInTool(tool, existing.path, WORKSPACE_STARTER), existing.path);
+        return;
+    }
+    const dashDir = managedDashboardDir(projectSlug, dashboardSlug);
+    const parentDir = managedOverscoreDir(projectSlug);
+    // A folder counts as "ready" only if a complete scaffold/pull left a package.json — a dir
+    // that exists without one is a half-finished setup (Ctrl-C, crash, lost network) we redo.
+    const isReady = (d) => fs.existsSync(path.join(d, "package.json"));
+    // 3. Make sure the source is present locally.
+    if (isReady(dashDir)) {
+        console.log(`\n  Opening your local copy of "${dashboardSlug}"...`);
+    }
+    else {
+        // Clear away any half-written folder left by a previous interrupted run.
+        if (fs.existsSync(dashDir))
+            fs.rmSync(dashDir, { recursive: true, force: true });
+        fs.mkdirSync(parentDir, { recursive: true });
+        let probe = await probeDashboard(deviceToken, projectSlug, dashboardSlug);
+        if (probe.state === "unauthorized") {
+            console.log("\n  Your session expired. Signing you in again...\n");
+            await authLogin();
+            deviceToken = readToken() || deviceToken;
+            probe = await probeDashboard(deviceToken, projectSlug, dashboardSlug);
+        }
+        if (probe.state === "error" || probe.state === "unauthorized") {
+            console.error(`\n  Error: couldn't reach the Hub for project "${projectSlug}".`);
+            console.error(`  Check the project slug and your access, then try again.\n`);
+            process.exit(1);
+        }
+        const selfCli = process.argv[1];
+        if (probe.state === "deployed") {
+            console.log(`\n  Fetching "${dashboardSlug}" from the Hub...`);
+            runOpenChild(`node "${selfCli}" pull ${dashboardSlug} --project ${projectSlug} --force`, parentDir);
+        }
+        else {
+            console.log(`\n  Setting up a new dashboard "${dashboardSlug}"...`);
+            // Reuse the key we already minted so the scaffold doesn't mint a second one.
+            const keyArg = probe.apiKey ? ` --key ${probe.apiKey}` : "";
+            runOpenChild(`npx --yes create-overscore --dashboard ${dashboardSlug} --project ${projectSlug}${keyArg}`, parentDir);
+        }
+        if (!isReady(dashDir)) {
+            console.error(`\n  Error: setup did not complete for:\n    ${dashDir}\n`);
+            process.exit(1);
+        }
+    }
+    // 4. Record the project's home so re-opens and workspace graduation stay coherent.
+    setHome(projectSlug, { path: managedProjectDir(projectSlug), mode: "flat" });
+    // 5. Open it in the user's tool.
+    const tool = await chooseOpenTool(toolFlag);
+    if (!tool) {
+        console.log(`\n  Your dashboard is ready at:\n    ${dashDir}`);
+        console.log(`\n  Install Claude Code, Codex, VS Code, or Cursor, then open that folder to build.\n`);
+        return;
+    }
+    finishOpen(openFolderInTool(tool, dashDir, DASHBOARD_STARTER), dashDir);
+}
 if (command === "dev") {
     dev();
 }
@@ -3269,6 +3531,9 @@ else if (command === "deploy") {
 else if (command === "pull") {
     pull(process.argv[3]);
 }
+else if (command === "open") {
+    open(process.argv[3]);
+}
 else if (command === "versions") {
     versions();
 }
@@ -3440,6 +3705,7 @@ else {
     auth                   Check authentication status
     auth login             Authenticate via browser (one time per machine)
     auth logout            Remove saved credentials
+    open <slug>            Set up or fetch a dashboard and open it in your AI tool
     dev                    Start the dev server (injects auth automatically)
     list                   List all dashboards in the project
     projects               List every project on your account
@@ -3453,6 +3719,7 @@ else {
 
   Usage:
     npx @overscore/cli auth login
+    npx @overscore/cli open <slug> --project <project-slug>
     npx @overscore/cli dev
     npx @overscore/cli list
     npx @overscore/cli projects

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@overscore/cli",
-  "version": "0.13.21",
+  "version": "0.13.22",
   "description": "CLI for deploying Overscore dashboards and publishing analyses",
   "bin": {
     "overscore": "dist/index.js"