checkbox-cli 1.1.1 → 2.0.1

package/dist/checkbox.d.ts

@@ -1,25 +1,15 @@
 #!/usr/bin/env node
 /**
- * Checkbox CLI
+ * Checkbox CLI — Beautiful, interactive compliance management from your terminal.
  *
- * Command-line interface for the Checkbox capability API.
+ * First-time users: just run `checkbox` and follow the guided setup.
+ * Returning users: `checkbox` opens the interactive menu.
  *
- * Usage:
- *   checkbox capabilities                          — list all capabilities
- *   checkbox command <type> <payload-json> [--org <id>]  — execute a command
- *   checkbox query <type> <payload-json> --org <id>      — execute a query
- *   checkbox workspace --org <id>                  — get workspace graph
- *   checkbox entities --org <id> [--type <t>] [--search <s>]  — find entities
- *   checkbox schema --org <id> [--type <t>]        — get entity schemas
- *   checkbox permissions --org <id>                — check permissions
- *
- * Environment variables:
- *   CHECKBOX_API_URL    — Base URL (default: https://checkbox.my)
- *   CHECKBOX_API_TOKEN  — API key (ck_live_...) or Supabase JWT
- *
- * Get your API key:
- *   1. Log in to checkbox.my
- *   2. Go to Developer Hub (sidebar)
- *   3. Create an API key — it never expires unless you set an expiry
+ * Direct commands (for scripts & automation):
+ *   checkbox plans             — List your compliance plans
+ *   checkbox tasks             — Browse tasks
+ *   checkbox complete <id>     — Complete a task
+ *   checkbox status            — Workspace overview
+ *   checkbox setup             — Re-run the setup wizard
  */
 export {};

package/dist/checkbox.js

@@ -1,207 +1,826 @@
 #!/usr/bin/env node
 /**
- * Checkbox CLI
+ * Checkbox CLI — Beautiful, interactive compliance management from your terminal.
  *
- * Command-line interface for the Checkbox capability API.
+ * First-time users: just run `checkbox` and follow the guided setup.
+ * Returning users: `checkbox` opens the interactive menu.
  *
- * Usage:
- *   checkbox capabilities                          — list all capabilities
- *   checkbox command <type> <payload-json> [--org <id>]  — execute a command
- *   checkbox query <type> <payload-json> --org <id>      — execute a query
- *   checkbox workspace --org <id>                  — get workspace graph
- *   checkbox entities --org <id> [--type <t>] [--search <s>]  — find entities
- *   checkbox schema --org <id> [--type <t>]        — get entity schemas
- *   checkbox permissions --org <id>                — check permissions
- *
- * Environment variables:
- *   CHECKBOX_API_URL    — Base URL (default: https://checkbox.my)
- *   CHECKBOX_API_TOKEN  — API key (ck_live_...) or Supabase JWT
- *
- * Get your API key:
- *   1. Log in to checkbox.my
- *   2. Go to Developer Hub (sidebar)
- *   3. Create an API key — it never expires unless you set an expiry
+ * Direct commands (for scripts & automation):
+ *   checkbox plans             — List your compliance plans
+ *   checkbox tasks             — Browse tasks
+ *   checkbox complete <id>     — Complete a task
+ *   checkbox status            — Workspace overview
+ *   checkbox setup             — Re-run the setup wizard
  */
-const API_URL = process.env.CHECKBOX_API_URL ?? 'https://checkbox.my';
-const API_TOKEN = process.env.CHECKBOX_API_TOKEN ?? '';
-function getHeaders() {
-    return {
+import * as p from '@clack/prompts';
+import pc from 'picocolors';
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+// ── Config ──────────────────────────────────────────────────────────
+const CONFIG_DIR = join(homedir(), '.checkbox');
+const CONFIG_FILE = join(CONFIG_DIR, 'config.json');
+const VERSION = '2.0.1';
+function loadConfig() {
+    try {
+        if (!existsSync(CONFIG_FILE))
+            return null;
+        const raw = readFileSync(CONFIG_FILE, 'utf-8');
+        const cfg = JSON.parse(raw);
+        if (!cfg.apiKey)
+            return null;
+        return {
+            apiKey: cfg.apiKey,
+            apiUrl: cfg.apiUrl || 'https://checkbox.my',
+            orgId: cfg.orgId || '',
+            orgName: cfg.orgName || '',
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function saveConfig(cfg) {
+    mkdirSync(CONFIG_DIR, { recursive: true });
+    writeFileSync(CONFIG_FILE, JSON.stringify(cfg, null, 2));
+}
+function resolveConfig() {
+    const envKey = process.env.CHECKBOX_API_KEY || process.env.CHECKBOX_API_TOKEN;
+    const fileCfg = loadConfig();
+    if (envKey) {
+        return {
+            apiKey: envKey,
+            apiUrl: process.env.CHECKBOX_API_URL || fileCfg?.apiUrl || 'https://checkbox.my',
+            orgId: fileCfg?.orgId || '',
+            orgName: fileCfg?.orgName || '',
+        };
+    }
+    return fileCfg;
+}
+// ── API ─────────────────────────────────────────────────────────────
+/** Extract a human-readable error message from any API error shape */
+function extractError(obj) {
+    if (!obj)
+        return 'Unknown error';
+    if (typeof obj === 'string')
+        return obj;
+    if (typeof obj.error === 'string')
+        return obj.error;
+    if (obj.error?.message)
+        return obj.error.message;
+    if (obj.message)
+        return obj.message;
+    return JSON.stringify(obj);
+}
+function api(cfg) {
+    const headers = {
         'Content-Type': 'application/json',
-        ...(API_TOKEN ? { 'X-API-Key': API_TOKEN } : {}),
+        'X-API-Key': cfg.apiKey,
     };
+    async function post(path, body) {
+        const res = await fetch(`${cfg.apiUrl}${path}`, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(body),
+        });
+        const json = await res.json().catch(() => null);
+        if (!res.ok) {
+            throw new Error(extractError(json) || `Request failed (${res.status})`);
+        }
+        if (json && json.success === false) {
+            throw new Error(extractError(json) || 'Request failed');
+        }
+        return json;
+    }
+    async function get(path) {
+        const res = await fetch(`${cfg.apiUrl}${path}`, { headers });
+        const json = await res.json().catch(() => null);
+        if (!res.ok) {
+            throw new Error(extractError(json) || `Request failed (${res.status})`);
+        }
+        if (json && json.success === false) {
+            throw new Error(extractError(json) || 'Request failed');
+        }
+        return json;
+    }
+    return { post, get };
 }
-async function apiGet(path) {
-    const res = await fetch(`${API_URL}${path}`, { method: 'GET', headers: getHeaders() });
-    return res.json();
+// ── Query helpers ───────────────────────────────────────────────────
+// The actual query types are: list_entities, get_entity, list_my_organizations,
+// get_task_states, workspace_graph, entity_discovery, schema_discovery,
+// permission_discovery, list_approvals.
+// There is NO list_plans or list_tasks — use list_entities with entity_type.
+async function listEntities(post, orgId, entityType) {
+    const res = await post('/api/v2/query', {
+        type: 'list_entities',
+        organization_id: orgId,
+        payload: { entity_type: entityType, organization_id: orgId },
+    });
+    // list_entities returns { success, data: [...], meta }
+    return Array.isArray(res.data) ? res.data : [];
 }
-async function apiPost(path, body) {
-    const res = await fetch(`${API_URL}${path}`, {
-        method: 'POST',
-        headers: getHeaders(),
-        body: JSON.stringify(body),
+async function searchEntities(post, orgId, search, limit = 20) {
+    // entity_discovery returns { success, data: { organization_id, entities: [...] } }
+    const res = await post('/api/v2/introspection/entities', {
+        organization_id: orgId,
+        search,
+        limit,
     });
-    return res.json();
+    return res.data?.entities || [];
 }
-function print(data) {
-    console.log(JSON.stringify(data, null, 2));
+async function getWorkspaceNodes(post, orgId) {
+    // workspace returns { success, data: { organization_id, nodes: [...], edges: [...] } }
+    const res = await post('/api/v2/introspection/workspace', {
+        organization_id: orgId,
+    });
+    return res.data?.nodes || [];
 }
-function fail(message) {
-    console.error(`Error: ${message}`);
-    process.exit(1);
+// ── Formatters ──────────────────────────────────────────────────────
+function truncate(s, max) {
+    return s.length > max ? s.slice(0, max - 1) + '\u2026' : s;
 }
-function getFlag(args, flag) {
-    const idx = args.indexOf(flag);
-    if (idx === -1 || idx + 1 >= args.length)
-        return undefined;
-    return args[idx + 1];
+function formatDate(iso) {
+    return new Date(iso).toLocaleDateString('en-US', { month: 'short', day: 'numeric', year: 'numeric' });
+}
+function pad(s, n) {
+    return s.padEnd(n);
+}
+// ── Setup Wizard ────────────────────────────────────────────────────
+async function runSetup(existingConfig) {
+    p.intro(pc.bgCyan(pc.black(' Checkbox Setup ')));
+    if (existingConfig?.apiKey) {
+        p.log.info(`Current API key: ${pc.dim(existingConfig.apiKey.slice(0, 16) + '...')}`);
+        p.log.info(`Current workspace: ${pc.cyan(existingConfig.orgName || 'not set')}`);
+    }
+    const result = await p.group({
+        apiKey: () => p.password({
+            message: 'Paste your API key',
+            validate: (v) => {
+                if (!v)
+                    return 'API key is required';
+                if (!v.startsWith('ck_live_'))
+                    return 'API key must start with ck_live_';
+                if (v.length < 30)
+                    return 'That looks too short for an API key';
+            },
+        }),
+        confirm: ({ results }) => p.confirm({
+            message: `Connect with key ${pc.dim(String(results.apiKey).slice(0, 16) + '...')}?`,
+            initialValue: true,
+        }),
+    }, {
+        onCancel: () => {
+            p.cancel('Setup cancelled.');
+            process.exit(0);
+        },
+    });
+    if (!result.confirm) {
+        p.cancel('Setup cancelled.');
+        process.exit(0);
+    }
+    const cfg = {
+        apiKey: result.apiKey,
+        apiUrl: existingConfig?.apiUrl || 'https://checkbox.my',
+        orgId: '',
+        orgName: '',
+    };
+    const s = p.spinner();
+    s.start('Connecting to Checkbox...');
+    let orgs = [];
+    try {
+        const { post } = api(cfg);
+        const res = await post('/api/v2/query', { type: 'list_my_organizations', payload: {} });
+        orgs = Array.isArray(res.data) ? res.data : [];
+        s.stop(`Connected! Found ${orgs.length} workspace${orgs.length === 1 ? '' : 's'}`);
+    }
+    catch (err) {
+        s.stop(pc.red('Connection failed'));
+        p.log.error(err.message || 'Could not connect with that API key');
+        p.log.info(`Make sure your key is active at ${pc.underline('checkbox.my/developers')}`);
+        p.outro(pc.dim('Try again with a valid key.'));
+        process.exit(1);
+    }
+    if (orgs.length === 0) {
+        p.log.warn('No workspaces found. Create one at checkbox.my first.');
+        saveConfig(cfg);
+        p.outro(pc.green('API key saved. Run checkbox again after creating a workspace.'));
+        return cfg;
+    }
+    if (orgs.length === 1) {
+        cfg.orgId = orgs[0].id;
+        cfg.orgName = orgs[0].name;
+        p.log.success(`Workspace: ${pc.cyan(cfg.orgName)}`);
+    }
+    else {
+        const choice = await p.select({
+            message: 'Choose your default workspace',
+            options: orgs.map((o) => ({
+                value: o.id,
+                label: o.name,
+                hint: o.role,
+            })),
+        });
+        if (p.isCancel(choice)) {
+            p.cancel('Setup cancelled.');
+            process.exit(0);
+        }
+        cfg.orgId = choice;
+        cfg.orgName = orgs.find((o) => o.id === choice)?.name || '';
+    }
+    saveConfig(cfg);
+    p.note([
+        `${pad('Workspace', 14)} ${pc.cyan(cfg.orgName)}`,
+        `${pad('API Key', 14)} ${pc.dim(cfg.apiKey.slice(0, 16) + '...')}`,
+        `${pad('Config saved', 14)} ${pc.dim(CONFIG_FILE)}`,
+    ].join('\n'), 'Ready to go');
+    p.outro(pc.green('Setup complete! Run `checkbox` to get started.'));
+    return cfg;
+}
+// ── Interactive Menu ────────────────────────────────────────────────
+async function interactiveMenu(cfg) {
+    const { post } = api(cfg);
+    console.log();
+    p.intro(pc.bgCyan(pc.black(' Checkbox ')) +
+        pc.dim(` v${VERSION}`) +
+        pc.dim(' \u2022 ') +
+        pc.cyan(cfg.orgName || 'no workspace'));
+    const action = await p.select({
+        message: 'What would you like to do?',
+        options: [
+            { value: 'plans', label: 'View plans', hint: 'see your compliance plans' },
+            { value: 'tasks', label: 'Browse tasks', hint: 'view and complete tasks' },
+            { value: 'status', label: 'Workspace overview', hint: 'summary of your workspace' },
+            { value: 'search', label: 'Search', hint: 'find anything in your workspace' },
+            { value: 'complete', label: 'Complete a task', hint: 'mark a task as done' },
+            { value: 'create-task', label: 'Create a task', hint: 'add a new task' },
+            { value: 'switch', label: 'Switch workspace', hint: 'change organization' },
+            { value: 'setup', label: 'Settings', hint: 'API key, workspace config' },
+        ],
+    });
+    if (p.isCancel(action)) {
+        p.cancel('Goodbye!');
+        return;
+    }
+    switch (action) {
+        case 'plans': return menuPlans(cfg, post);
+        case 'tasks': return menuTasks(cfg, post);
+        case 'status': return menuStatus(cfg, post);
+        case 'search': return menuSearch(cfg, post);
+        case 'complete': return menuComplete(cfg, post);
+        case 'create-task': return menuCreateTask(cfg, post);
+        case 'switch': return menuSwitch(cfg, post);
+        case 'setup':
+            await runSetup(cfg);
+            return;
+    }
+}
+// ── Plans ───────────────────────────────────────────────────────────
+async function menuPlans(cfg, post) {
+    const s = p.spinner();
+    s.start('Loading plans...');
+    try {
+        const plans = await listEntities(post, cfg.orgId, 'plan');
+        s.stop(`Found ${plans.length} plan${plans.length === 1 ? '' : 's'}`);
+        if (plans.length === 0) {
+            p.log.info('No plans yet. Create one at checkbox.my');
+            return interactiveMenu(cfg);
+        }
+        const lines = plans.map((plan) => {
+            const name = truncate(plan.name || 'Untitled', 40);
+            const meta = plan.metadata || {};
+            const created = meta.created_at ? formatDate(meta.created_at) : '';
+            return `${pc.cyan(pad(name, 42))} ${pc.dim(created)}`;
+        });
+        p.note(lines.join('\n'), `Plans in ${cfg.orgName}`);
+        const selected = await p.select({
+            message: 'Select a plan to view its tasks',
+            options: [
+                ...plans.map((plan) => ({
+                    value: plan.id,
+                    label: plan.name || 'Untitled',
+                })),
+                { value: '__back', label: pc.dim('Back to menu') },
+            ],
+        });
+        if (p.isCancel(selected) || selected === '__back') {
+            return interactiveMenu(cfg);
+        }
+        return menuPlanTasks(cfg, post, selected, plans.find((pl) => pl.id === selected)?.name || '');
+    }
+    catch (err) {
+        s.stop(pc.red('Failed'));
+        p.log.error(err.message || 'Could not load plans');
+        return interactiveMenu(cfg);
+    }
+}
+async function menuPlanTasks(cfg, post, planId, planName) {
+    const s = p.spinner();
+    s.start('Loading tasks...');
+    try {
+        // Search entities by plan — use entity_discovery with search for plan-specific tasks
+        // Or query list_entities for tasks and filter by parent_id
+        const res = await post('/api/v2/query', {
+            type: 'list_entities',
+            organization_id: cfg.orgId,
+            payload: { entity_type: 'task', organization_id: cfg.orgId },
+        });
+        const allTasks = Array.isArray(res.data) ? res.data : [];
+        // Filter tasks that belong to this plan via parent_id chain
+        const tasks = allTasks.filter((t) => t.parent_id === planId || t.metadata?.plan_id === planId);
+        s.stop(`${tasks.length} task${tasks.length === 1 ? '' : 's'} in ${pc.cyan(planName)}`);
+        if (tasks.length === 0) {
+            p.log.info('No tasks found for this plan.');
+            return interactiveMenu(cfg);
+        }
+        const lines = tasks.map((t) => {
+            const name = truncate(t.name || 'Untitled', 50);
+            const freq = t.metadata?.frequency || '';
+            return `  ${pc.cyan(pad(name, 52))} ${pc.dim(freq)}`;
+        });
+        p.note(lines.join('\n'), planName);
+        return interactiveMenu(cfg);
+    }
+    catch (err) {
+        s.stop(pc.red('Failed'));
+        p.log.error(err.message || 'Could not load tasks');
+        return interactiveMenu(cfg);
+    }
+}
+// ── Tasks ───────────────────────────────────────────────────────────
+async function menuTasks(cfg, post) {
+    const s = p.spinner();
+    s.start('Loading tasks...');
+    try {
+        const tasks = await listEntities(post, cfg.orgId, 'task');
+        s.stop(`Found ${tasks.length} task${tasks.length === 1 ? '' : 's'}`);
+        if (tasks.length === 0) {
+            p.log.info('No tasks yet.');
+            return interactiveMenu(cfg);
+        }
+        const selected = await p.select({
+            message: 'Select a task',
+            options: [
+                ...tasks.slice(0, 25).map((t) => ({
+                    value: t.id,
+                    label: truncate(t.name || 'Untitled', 60),
+                    hint: t.metadata?.frequency || '',
+                })),
+                ...(tasks.length > 25 ? [{ value: '__more', label: pc.dim(`...and ${tasks.length - 25} more`) }] : []),
+                { value: '__back', label: pc.dim('Back to menu') },
+            ],
+        });
+        if (p.isCancel(selected) || selected === '__back' || selected === '__more') {
+            return interactiveMenu(cfg);
+        }
+        const task = tasks.find((t) => t.id === selected);
+        if (task) {
+            const meta = task.metadata || {};
+            const lines = [
+                `${pad('Name', 14)} ${pc.cyan(task.name || 'Untitled')}`,
+                `${pad('Frequency', 14)} ${meta.frequency || pc.dim('none')}`,
+                `${pad('Assigned to', 14)} ${meta.assigned_to || pc.dim('unassigned')}`,
+                `${pad('ID', 14)} ${pc.dim(task.id)}`,
+            ];
+            p.note(lines.join('\n'), task.name || 'Task');
+            const action = await p.select({
+                message: 'What would you like to do?',
+                options: [
+                    { value: 'complete', label: 'Complete this task' },
+                    { value: 'back', label: pc.dim('Back to menu') },
+                ],
+            });
+            if (action === 'complete' && !p.isCancel(action)) {
+                await doComplete(cfg, post, task.id, task.name);
+            }
+        }
+        return interactiveMenu(cfg);
+    }
+    catch (err) {
+        s.stop(pc.red('Failed'));
+        p.log.error(err.message || 'Could not load tasks');
+        return interactiveMenu(cfg);
+    }
+}
+// ── Status ──────────────────────────────────────────────────────────
+async function menuStatus(cfg, post) {
+    const s = p.spinner();
+    s.start('Loading workspace...');
+    try {
+        const nodes = await getWorkspaceNodes(post, cfg.orgId);
+        s.stop('Workspace loaded');
+        // Count nodes by type
+        const counts = {};
+        for (const node of nodes) {
+            const t = node.type || 'unknown';
+            counts[t] = (counts[t] || 0) + 1;
+        }
+        const lines = [
+            `${pad('Workspace', 16)} ${pc.cyan(cfg.orgName)}`,
+            '',
+            `${pad('Plans', 16)} ${pc.bold(String(counts.plan || 0))}`,
+            `${pad('Tasks', 16)} ${pc.bold(String(counts.task || 0))}`,
+            `${pad('Requirements', 16)} ${pc.bold(String(counts.requirement || 0))}`,
+            `${pad('Goals', 16)} ${pc.bold(String(counts.goal || 0))}`,
+            `${pad('Rules', 16)} ${pc.bold(String(counts.rule || 0))}`,
+            `${pad('Documents', 16)} ${pc.bold(String(counts.document || 0))}`,
+            `${pad('Tables', 16)} ${pc.bold(String(counts.table || 0))}`,
+        ];
+        p.note(lines.join('\n'), 'Workspace Overview');
+    }
+    catch (err) {
+        s.stop(pc.red('Failed'));
+        p.log.error(err.message || 'Could not load workspace');
+    }
+    return interactiveMenu(cfg);
 }
-// ── Subcommands ─────────────────────────────────────────────────────
-async function cmdCapabilities() {
-    print(await apiGet('/api/v2/introspection/capabilities'));
-}
-async function cmdCommand(args) {
-    const type = args[0];
-    const payloadRaw = args[1];
-    if (!type)
-        fail('Usage: checkbox command <type> <payload-json> [--org <id>]');
-    const payload = payloadRaw ? JSON.parse(payloadRaw) : {};
-    const orgId = getFlag(args, '--org');
+// ── Search ──────────────────────────────────────────────────────────
+async function menuSearch(cfg, post) {
+    const query = await p.text({
+        message: 'Search for...',
+        placeholder: 'task name, plan, document...',
+        validate: (v) => {
+            if (!v)
+                return 'Enter a search term';
+        },
+    });
+    if (p.isCancel(query))
+        return interactiveMenu(cfg);
+    const s = p.spinner();
+    s.start('Searching...');
+    try {
+        const entities = await searchEntities(post, cfg.orgId, query);
+        s.stop(`Found ${entities.length} result${entities.length === 1 ? '' : 's'}`);
+        if (entities.length === 0) {
+            p.log.info('No results found.');
+        }
+        else {
+            const lines = entities.map((e) => {
+                const type = pad(e.entity_type || 'unknown', 14);
+                const name = truncate(e.name || 'Untitled', 50);
+                return `  ${pc.dim(type)} ${pc.cyan(name)}`;
+            });
+            p.note(lines.join('\n'), `Results for "${query}"`);
+        }
+    }
+    catch (err) {
+        s.stop(pc.red('Failed'));
+        p.log.error(err.message || 'Search failed');
+    }
+    return interactiveMenu(cfg);
+}
+// ── Complete Task ───────────────────────────────────────────────────
+async function menuComplete(cfg, post) {
+    const s = p.spinner();
+    s.start('Loading tasks...');
+    try {
+        const tasks = await listEntities(post, cfg.orgId, 'task');
+        s.stop(`${tasks.length} task${tasks.length === 1 ? '' : 's'} available`);
+        if (tasks.length === 0) {
+            p.log.info('No tasks to complete.');
+            return interactiveMenu(cfg);
+        }
+        const selected = await p.select({
+            message: 'Which task did you complete?',
+            options: [
+                ...tasks.slice(0, 30).map((t) => ({
+                    value: t.id,
+                    label: truncate(t.name || 'Untitled', 60),
+                    hint: t.metadata?.frequency || '',
+                })),
+                { value: '__back', label: pc.dim('Back to menu') },
+            ],
+        });
+        if (p.isCancel(selected) || selected === '__back') {
+            return interactiveMenu(cfg);
+        }
+        const task = tasks.find((t) => t.id === selected);
+        await doComplete(cfg, post, selected, task?.name || '');
+    }
+    catch (err) {
+        s.stop(pc.red('Failed'));
+        p.log.error(err.message || 'Could not load tasks');
+    }
+    return interactiveMenu(cfg);
+}
+async function doComplete(cfg, post, taskId, taskName) {
+    const s = p.spinner();
+    s.start('Completing task...');
+    try {
+        await post('/api/v2/commands', {
+            type: 'complete_task',
+            organization_id: cfg.orgId,
+            payload: { task_id: taskId },
+        });
+        s.stop(pc.green(`Done! "${taskName}" completed`));
+    }
+    catch (err) {
+        s.stop(pc.red('Failed'));
+        p.log.error(err.message || 'Could not complete task');
+    }
+}
+// ── Create Task ─────────────────────────────────────────────────────
+async function menuCreateTask(cfg, post) {
+    const s = p.spinner();
+    s.start('Loading plans...');
+    let plans = [];
+    try {
+        plans = await listEntities(post, cfg.orgId, 'plan');
+        s.stop('');
+    }
+    catch {
+        s.stop('');
+    }
+    const result = await p.group({
+        name: () => p.text({
+            message: 'Task name',
+            placeholder: 'e.g. Daily safety walkthrough',
+            validate: (v) => {
+                if (!v)
+                    return 'Task name is required';
+            },
+        }),
+        planId: () => {
+            if (plans.length === 0)
+                return Promise.resolve(undefined);
+            return p.select({
+                message: 'Add to which plan?',
+                options: [
+                    { value: undefined, label: pc.dim('No plan (standalone task)') },
+                    ...plans.map((plan) => ({
+                        value: plan.id,
+                        label: plan.name || 'Untitled',
+                    })),
+                ],
+            });
+        },
+        frequency: () => p.select({
+            message: 'How often?',
+            options: [
+                { value: 'daily', label: 'Daily' },
+                { value: 'weekly', label: 'Weekly' },
+                { value: 'monthly', label: 'Monthly' },
+                { value: 'one-time', label: 'One-time' },
+            ],
+        }),
+    }, {
+        onCancel: () => {
+            p.cancel('Cancelled.');
+            return;
+        },
+    });
+    if (!result.name)
+        return interactiveMenu(cfg);
+    const spinner = p.spinner();
+    spinner.start('Creating task...');
+    try {
+        const payload = {
+            name: result.name,
+            organization_id: cfg.orgId,
+            frequency: result.frequency || 'daily',
+        };
+        if (result.planId)
+            payload.plan_id = result.planId;
+        await post('/api/v2/commands', {
+            type: 'create_task',
+            organization_id: cfg.orgId,
+            payload,
+        });
+        spinner.stop(pc.green(`Task "${result.name}" created!`));
+    }
+    catch (err) {
+        spinner.stop(pc.red('Failed'));
+        p.log.error(err.message || 'Could not create task');
+    }
+    return interactiveMenu(cfg);
+}
+// ── Switch Workspace ────────────────────────────────────────────────
+async function menuSwitch(cfg, post) {
+    const s = p.spinner();
+    s.start('Loading workspaces...');
+    try {
+        const res = await post('/api/v2/query', {
+            type: 'list_my_organizations',
+            payload: {},
+        });
+        const orgs = Array.isArray(res.data) ? res.data : [];
+        s.stop(`${orgs.length} workspace${orgs.length === 1 ? '' : 's'}`);
+        const selected = await p.select({
+            message: 'Switch to workspace',
+            options: orgs.map((o) => ({
+                value: o.id,
+                label: o.name,
+                hint: o.id === cfg.orgId ? pc.green('current') : o.role,
+            })),
+        });
+        if (p.isCancel(selected))
+            return interactiveMenu(cfg);
+        const org = orgs.find((o) => o.id === selected);
+        cfg.orgId = selected;
+        cfg.orgName = org?.name || '';
+        saveConfig(cfg);
+        p.log.success(`Switched to ${pc.cyan(cfg.orgName)}`);
+    }
+    catch (err) {
+        s.stop(pc.red('Failed'));
+        p.log.error(err.message || 'Could not load workspaces');
+    }
+    return interactiveMenu(cfg);
+}
+// ── Direct Commands (non-interactive) ───────────────────────────────
+async function directPlans(cfg) {
+    const { post } = api(cfg);
+    const s = p.spinner();
+    s.start('Loading plans...');
+    const plans = await listEntities(post, cfg.orgId, 'plan');
+    s.stop('');
+    if (plans.length === 0) {
+        p.log.info('No plans found.');
+        return;
+    }
+    const lines = plans.map((plan) => {
+        const name = truncate(plan.name || 'Untitled', 40);
+        return `  ${pc.cyan(pad(name, 42))} ${pc.dim(plan.id)}`;
+    });
+    p.note(lines.join('\n'), `${plans.length} plan${plans.length === 1 ? '' : 's'}`);
+}
+async function directTasks(cfg) {
+    const { post } = api(cfg);
+    const s = p.spinner();
+    s.start('Loading tasks...');
+    const tasks = await listEntities(post, cfg.orgId, 'task');
+    s.stop('');
+    if (tasks.length === 0) {
+        p.log.info('No tasks found.');
+        return;
+    }
+    const lines = tasks.map((t) => {
+        const name = truncate(t.name || 'Untitled', 50);
+        const freq = t.metadata?.frequency || '';
+        return `  ${pc.cyan(pad(name, 52))} ${pc.dim(freq)}  ${pc.dim(t.id)}`;
+    });
+    p.note(lines.join('\n'), `${tasks.length} task${tasks.length === 1 ? '' : 's'}`);
+}
+async function directComplete(cfg, taskId) {
+    const { post } = api(cfg);
+    const s = p.spinner();
+    s.start('Completing task...');
+    await post('/api/v2/commands', {
+        type: 'complete_task',
+        organization_id: cfg.orgId,
+        payload: { task_id: taskId },
+    });
+    s.stop(pc.green('Task completed!'));
+}
+async function directStatus(cfg) {
+    const { post } = api(cfg);
+    const s = p.spinner();
+    s.start('Loading workspace...');
+    const nodes = await getWorkspaceNodes(post, cfg.orgId);
+    s.stop('');
+    const counts = {};
+    for (const node of nodes) {
+        const t = node.type || 'unknown';
+        counts[t] = (counts[t] || 0) + 1;
+    }
+    const lines = [
+        `${pad('Workspace', 16)} ${pc.cyan(cfg.orgName)}`,
+        '',
+        `${pad('Plans', 16)} ${pc.bold(String(counts.plan || 0))}`,
+        `${pad('Tasks', 16)} ${pc.bold(String(counts.task || 0))}`,
+        `${pad('Requirements', 16)} ${pc.bold(String(counts.requirement || 0))}`,
+        `${pad('Goals', 16)} ${pc.bold(String(counts.goal || 0))}`,
+        `${pad('Rules', 16)} ${pc.bold(String(counts.rule || 0))}`,
+        `${pad('Documents', 16)} ${pc.bold(String(counts.document || 0))}`,
+        `${pad('Tables', 16)} ${pc.bold(String(counts.table || 0))}`,
+    ];
+    p.note(lines.join('\n'), 'Workspace Overview');
+}
+async function directSearch(cfg, term) {
+    const { post } = api(cfg);
+    const s = p.spinner();
+    s.start('Searching...');
+    const entities = await searchEntities(post, cfg.orgId, term);
+    s.stop('');
+    if (entities.length === 0) {
+        p.log.info('No results found.');
+    }
+    else {
+        const lines = entities.map((e) => `  ${pc.dim(pad(e.entity_type || '', 14))} ${pc.cyan(truncate(e.name || '', 50))}  ${pc.dim(e.id)}`);
+        p.note(lines.join('\n'), `${entities.length} result${entities.length === 1 ? '' : 's'} for "${term}"`);
+    }
+}
+// Raw passthrough for power users
+async function directRaw(cfg, type, args) {
+    const { post } = api(cfg);
+    const payloadRaw = args[0];
+    const orgId = getFlag(args, '--org') || cfg.orgId;
+    const payload = payloadRaw && !payloadRaw.startsWith('--') ? JSON.parse(payloadRaw) : {};
     const body = { type, payload };
     if (orgId)
         body.organization_id = orgId;
-    print(await apiPost('/api/v2/commands', body));
-}
-async function cmdQuery(args) {
-    const type = args[0];
-    const payloadRaw = args[1];
-    const orgId = getFlag(args, '--org');
-    if (!type || !orgId)
-        fail('Usage: checkbox query <type> <payload-json> --org <id>');
-    const payload = payloadRaw ? JSON.parse(payloadRaw) : {};
-    print(await apiPost('/api/v2/query', {
+    const res = await post('/api/v2/commands', body);
+    console.log(JSON.stringify(res, null, 2));
+}
+async function directQuery(cfg, type, args) {
+    const { post } = api(cfg);
+    const payloadRaw = args[0];
+    const orgId = getFlag(args, '--org') || cfg.orgId;
+    const payload = payloadRaw && !payloadRaw.startsWith('--') ? JSON.parse(payloadRaw) : {};
+    const res = await post('/api/v2/query', {
         type,
         organization_id: orgId,
         payload: { ...payload, organization_id: orgId },
-    }));
-}
-async function cmdWorkspace(args) {
-    const orgId = getFlag(args, '--org');
-    if (!orgId)
-        fail('Usage: checkbox workspace --org <id>');
-    print(await apiPost('/api/v2/introspection/workspace', { organization_id: orgId }));
-}
-async function cmdEntities(args) {
-    const orgId = getFlag(args, '--org');
-    if (!orgId)
-        fail('Usage: checkbox entities --org <id> [--type <t>] [--search <s>]');
-    const entityType = getFlag(args, '--type');
-    const search = getFlag(args, '--search');
-    const limit = getFlag(args, '--limit');
-    print(await apiPost('/api/v2/introspection/entities', {
-        organization_id: orgId,
-        entity_type: entityType,
-        search,
-        limit: limit ? parseInt(limit, 10) : undefined,
-    }));
-}
-async function cmdSchema(args) {
-    const orgId = getFlag(args, '--org');
-    if (!orgId)
-        fail('Usage: checkbox schema --org <id> [--type <t>] [--entity-id <id>]');
-    const entityType = getFlag(args, '--type');
-    const entityId = getFlag(args, '--entity-id');
-    print(await apiPost('/api/v2/introspection/schema', {
-        organization_id: orgId,
-        entity_type: entityType,
-        entity_id: entityId,
-    }));
-}
-async function cmdPermissions(args) {
-    const orgId = getFlag(args, '--org');
-    if (!orgId)
-        fail('Usage: checkbox permissions --org <id>');
-    print(await apiPost('/api/v2/introspection/permissions', { organization_id: orgId }));
-}
-async function cmdOrganizations() {
-    print(await apiPost('/api/v2/query', {
-        type: 'list_my_organizations',
-        payload: {},
-    }));
-}
-function printUsage() {
-    console.log(`Checkbox CLI — interact with the Checkbox capability API
-
-Usage:
-  checkbox orgs                                          List your organizations
-  checkbox capabilities                                  List all capabilities
-  checkbox command <type> [payload-json] [--org <id>]    Execute a command
-  checkbox query <type> [payload-json] --org <id>        Execute a query
-  checkbox workspace --org <id>                          Get workspace graph
-  checkbox entities --org <id> [--type <t>] [--search <s>]  Find entities
-  checkbox schema --org <id> [--type <t>]                Get entity schemas
-  checkbox permissions --org <id>                        Check permissions
-
-Environment:
-  CHECKBOX_API_URL    Base URL (default: https://checkbox.my)
-  CHECKBOX_API_TOKEN  API key (ck_live_...) or Supabase JWT
-
-Get your API key:
-  1. Log in to checkbox.my
-  2. Go to Developer Hub (sidebar)
-  3. Create an API key — it never expires unless you configure an expiry
-
-Examples:
-  export CHECKBOX_API_TOKEN="ck_live_your_key_here"
-
-  checkbox orgs
-  checkbox capabilities
-  checkbox command create_plan '{"name":"Q2 Safety"}' --org <org-id>
-  checkbox command complete_task '{"task_id":"abc-123"}' --org <org-id>
-  checkbox query get_task_states '{"date":"2026-03-12"}' --org <org-id>
-  checkbox entities --org <org-id> --type task --search "Daily check"
-`);
+    });
+    console.log(JSON.stringify(res, null, 2));
+}
+function getFlag(args, flag) {
+    const idx = args.indexOf(flag);
+    if (idx === -1 || idx + 1 >= args.length)
+        return undefined;
+    return args[idx + 1];
 }
 // ── Main ────────────────────────────────────────────────────────────
 async function main() {
     const args = process.argv.slice(2);
     const sub = args[0];
     const rest = args.slice(1);
-    if (!API_TOKEN && sub !== undefined && sub !== 'help' && sub !== '--help') {
-        console.error('Warning: CHECKBOX_API_TOKEN is not set. Authenticated requests will fail.');
-        console.error('Get an API key: log in to checkbox.my → Developer Hub → Create Key\n');
-    }
-    switch (sub) {
-        case 'orgs':
-        case 'organizations':
-            return cmdOrganizations();
-        case 'capabilities':
-            return cmdCapabilities();
-        case 'command':
-        case 'cmd':
-            return cmdCommand(rest);
-        case 'query':
-            return cmdQuery(rest);
-        case 'workspace':
-            return cmdWorkspace(rest);
-        case 'entities':
-            return cmdEntities(rest);
-        case 'schema':
-            return cmdSchema(rest);
-        case 'permissions':
-            return cmdPermissions(rest);
-        case 'help':
-        case '--help':
-        case '-h':
-        case undefined:
-            return printUsage();
-        default:
-            console.error(`Unknown subcommand: ${sub}\n`);
-            printUsage();
-            process.exit(1);
+    if (sub === 'setup' || sub === 'init' || sub === 'login') {
+        await runSetup(resolveConfig());
+        return;
+    }
+    if (sub === '--version' || sub === '-v') {
+        console.log(`checkbox v${VERSION}`);
+        return;
+    }
+    if (sub === '--help' || sub === '-h' || sub === 'help') {
+        console.log();
+        p.intro(pc.bgCyan(pc.black(' Checkbox CLI ')) + pc.dim(` v${VERSION}`));
+        p.note([
+            `${pc.cyan('checkbox')}               Interactive menu`,
+            `${pc.cyan('checkbox setup')}          Setup wizard (API key & workspace)`,
+            `${pc.cyan('checkbox plans')}          List your plans`,
+            `${pc.cyan('checkbox tasks')}          List your tasks`,
+            `${pc.cyan('checkbox complete <id>')}  Complete a task`,
+            `${pc.cyan('checkbox status')}         Workspace overview`,
+            `${pc.cyan('checkbox search <term>')}  Search your workspace`,
+            '',
+            pc.dim('Advanced (for automation):'),
+            `${pc.dim('checkbox cmd <type> [json] [--org <id>]')}`,
+            `${pc.dim('checkbox query <type> [json] [--org <id>]')}`,
+        ].join('\n'), 'Commands');
+        p.outro(pc.dim('Run `checkbox setup` to get started'));
+        return;
+    }
+    const cfg = resolveConfig();
+    if (!cfg) {
+        await runSetup(null);
+        return;
+    }
+    try {
+        switch (sub) {
+            case 'plans':
+                return await directPlans(cfg);
+            case 'tasks':
+                return await directTasks(cfg);
+            case 'complete':
+                if (!rest[0]) {
+                    const { post } = api(cfg);
+                    return await menuComplete(cfg, post);
+                }
+                return await directComplete(cfg, rest[0]);
+            case 'status':
+            case 'overview':
+                return await directStatus(cfg);
+            case 'search':
+                if (!rest[0]) {
+                    const { post } = api(cfg);
+                    return await menuSearch(cfg, post);
+                }
+                return await directSearch(cfg, rest.join(' '));
+            case 'switch':
+                return await menuSwitch(cfg, api(cfg).post);
+            case 'cmd':
+            case 'command':
+                return await directRaw(cfg, rest[0], rest.slice(1));
+            case 'query':
+                return await directQuery(cfg, rest[0], rest.slice(1));
+            case 'orgs':
+            case 'organizations':
+                return await directQuery(cfg, 'list_my_organizations', []);
+            case undefined:
+                return await interactiveMenu(cfg);
+            default:
+                p.log.error(`Unknown command: ${sub}`);
+                p.log.info(`Run ${pc.cyan('checkbox --help')} to see available commands`);
+                process.exit(1);
+        }
+    }
+    catch (err) {
+        p.log.error(err.message || 'Something went wrong');
+        process.exit(1);
     }
 }
 main().catch((err) => {
-    console.error('Fatal:', err);
+    p.log.error(err.message || 'Fatal error');
     process.exit(1);
 });
-export {};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "checkbox-cli",
-  "version": "1.1.1",
-  "description": "CLI for the Checkbox capability API — create compliance plans, manage tasks, query workspaces, and automate from the terminal.",
+  "version": "2.0.1",
+  "description": "Beautiful, interactive CLI for Checkbox compliance management. Setup wizard, guided workflows, and full workspace control from your terminal.",
   "type": "module",
   "main": "dist/checkbox.js",
   "bin": {
@@ -36,8 +36,12 @@
     "node": ">=18.0.0"
   },
   "devDependencies": {
-    "typescript": "^5.7.0",
+    "@types/node": "^22.0.0",
     "tsx": "^4.19.0",
-    "@types/node": "^22.0.0"
+    "typescript": "^5.7.0"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.1.0",
+    "picocolors": "^1.1.1"
   }
 }