@skhema/cli 0.3.1

package/README.md

@@ -0,0 +1,163 @@
+# @skhema/cli
+
+The Skhema command-line interface (`skhema`). Authenticate as a human or an
+agent, then drive the [Skhema Public API](https://skhema.com/docs/api) from your
+terminal, CI, or an autonomous agent — workspaces, elements, components,
+strategies, exports, resources, and webhooks, plus one-command agent onboarding.
+
+## Install
+
+```sh
+npm i -g @skhema/cli
+skhema --help
+```
+
+Requires Node ≥ 18.
+
+## Agent quickstart
+
+Point an agent (OpenClaw / Hermes / any CI job) at Skhema in one line — install
+skills, register the MCP server, and verify an API connection:
+
+```sh
+SKHEMA_API_KEY=sk_live_… npx @skhema/cli init --yes --json
+```
+
+`skhema init`:
+
+- **Verifies a credential** — resolves `--api-key` / `SKHEMA_API_KEY` / a stored
+  key / an OAuth session (same precedence as every command), exchanges + probes
+  it, and reports the org and permission. An explicit `--api-key` is stored for
+  future commands (never overwriting a different stored key without `--force`).
+- **Installs skills** into every detected agent platform (idempotent — reruns
+  report `unchanged`).
+- **Registers the MCP server** (`https://mcp-server.skhema.com/mcp`, Streamable
+  HTTP) in detected clients by safely merging a dedicated config file and writing
+  a `.bak` backup — **or printing copy-paste instructions** when a client's config
+  isn't cleanly writable. `--yes` registers non-interactively; without it, `init`
+  reports what it _would_ do and prompts only on a TTY. MCP auth is per-client
+  browser OAuth on first use — the CLI only wires the URL, never a credential.
+
+`--yes` never prompts and does everything resolvable, reporting what it skipped.
+Re-running is safe: every step reports already-done work as such.
+
+### Raw API passthrough
+
+Reach any current or future gateway route without waiting for a dedicated verb —
+with the CLI's credential resolution, error mapping, and exit codes:
+
+```sh
+skhema api GET /workspaces                       # leading /v1 is optional
+skhema api POST /workspaces/ws_1/elements --data @element.json
+skhema api GET /workspaces --query limit=10 --query type=strategy
+echo '{"name":"Q3"}' | skhema api POST /workspaces --data -
+skhema api routes                                # every live route from the OpenAPI spec
+```
+
+`--data` takes a JSON literal, `@file`, or `-` (stdin). `--query k=v` repeats. The
+passthrough refuses any host other than the Skhema gateway.
+
+## Credential lanes
+
+The CLI accepts **two kinds** of credential and resolves them in a fixed
+precedence order (highest first):
+
+1. `--api-key <sk_live_…>` global flag (this invocation only)
+2. `SKHEMA_API_KEY` environment variable
+3. A stored API key (`skhema auth key use <key>`)
+4. A stored OAuth session (`skhema auth login`)
+
+API keys (lanes 1–3) are for **CI and agents** — no browser, no device flow. The
+OAuth session (lane 4) is for **interactive human** use. The organization is
+baked into an API key, so you never pass an org id when using one.
+
+`skhema auth status` reports exactly which lane is active and for which org:
+
+```sh
+skhema auth status
+# Credential:   SKHEMA_API_KEY environment variable
+# Key:          sk_live_...a1b2
+# Verified:     Yes
+# Permission:   read-write
+# Organization: org_…
+```
+
+### Managing API keys
+
+```sh
+skhema auth login                       # interactive OAuth (needed to manage keys)
+skhema auth key create --name ci --permission read   # prints the key ONCE
+skhema auth key create --name ci --use  # …and store it as the CLI credential
+skhema auth key list                    # masked, with usage + status
+skhema auth key revoke <key-id>
+skhema auth key use  <sk_live_…>        # store a key you already have
+skhema auth key remove                  # forget the stored key
+```
+
+`create` / `list` / `revoke` call the same server-side `api-key-manage` function
+the web dashboard uses, authenticated with your OAuth session — issuance
+authorization (org owner/admin, plan limits, one-time key display, security
+emails) is enforced there, unchanged. Raw keys are printed only at creation and
+are otherwise always masked.
+
+### Headless / CI
+
+```sh
+export SKHEMA_API_KEY=sk_live_…
+skhema --json workspace use <workspace-id>   # every command now just works
+```
+
+## Command conventions
+
+Every command supports the global flags `--json`, `--quiet`, `--verbose`, and
+`--api-key <key>`.
+
+### `--json` envelope
+
+Under `--json`, commands emit one stable envelope on stdout:
+
+```jsonc
+// success
+{ "ok": true,  "command": "workspace use", "data": { "defaultWorkspaceId": "ws_1" } }
+// failure
+{ "ok": false, "command": "auth key create", "error": { "code": "forbidden", "message": "…", "requestId": "req_…" } }
+```
+
+### Exit codes
+
+Deterministic, so agents can branch on them:
+
+| Code | Meaning                                    |
+| ---- | ------------------------------------------ |
+| `0`  | Success                                    |
+| `1`  | Generic / API error                        |
+| `2`  | Usage error (bad or missing arguments)     |
+| `3`  | Auth required (no usable credential)       |
+| `4`  | Permission or plan denied (HTTP 403 / 402) |
+| `5`  | Rate limited (HTTP 429)                    |
+
+### Default workspace
+
+```sh
+skhema workspace use <workspace-id>   # stored in ~/.skhema/config.json (0600)
+skhema workspace use --clear
+```
+
+Later workspace-scoped commands read this default when `--workspace` is omitted.
+
+## Configuration & storage
+
+| What                            | Where                                                                |
+| ------------------------------- | -------------------------------------------------------------------- |
+| OAuth session                   | macOS Keychain (`com.skhema.cli`) → `~/.skhema/credentials.json`     |
+| Stored API key                  | macOS Keychain (`com.skhema.cli/api-key`) → `~/.skhema/api-key.json` |
+| Preferences (default workspace) | `~/.skhema/config.json`                                              |
+
+Environment overrides for non-production environments: `SKHEMA_API_URL`,
+`SKHEMA_AUTH_URL`. The underlying API client is
+[`@skhema/sdk`](https://www.npmjs.com/package/@skhema/sdk) — use it directly
+when you want Skhema in your own code rather than your terminal.
+
+## License
+
+MIT

package/bin/skhema.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../dist/cli.js'

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,92 @@
+import { Command } from 'commander';
+import { createRequire } from 'module';
+import { registerAgentCommands } from './commands/agent.js';
+import { registerApiCommands } from './commands/api.js';
+import { registerAuthCommands } from './commands/auth.js';
+import { registerComponentCommands } from './commands/component.js';
+import { registerContributeCommands } from './commands/contribute.js';
+import { registerElementCommands } from './commands/element.js';
+import { registerWorkspaceExportCommand } from './commands/export.js';
+import { registerInitCommand } from './commands/init.js';
+import { registerLinkCommands } from './commands/link.js';
+import { registerResourceCommands } from './commands/resource.js';
+import { registerSkillsCommands } from './commands/skills.js';
+import { registerStrategyCommands } from './commands/strategy.js';
+import { registerWebhookCommands } from './commands/webhook.js';
+import { registerWorkspaceCommands } from './commands/workspace.js';
+import { setApiKeyFlag } from './lib/api/credential-context.js';
+import { isApprovedContributor } from './lib/auth/entitlements.js';
+import { getStoredCredentials } from './lib/auth/token-store.js';
+import { showBanner } from './lib/banner.js';
+import { outputError, setGlobalOptions } from './lib/output.js';
+const require = createRequire(import.meta.url);
+const pkg = require('../package.json');
+const program = new Command();
+program
+    .name('skhema')
+    .description('Skhema CLI — authentication and AI skills management')
+    .version(pkg.version)
+    .option('--json', 'Output structured JSON')
+    .option('--verbose', 'Verbose output')
+    .option('--quiet', 'Suppress non-essential output')
+    .option('--api-key <key>', 'Use this API key for this invocation (highest credential precedence)')
+    .hook('preAction', (thisCommand) => {
+    const opts = thisCommand.opts();
+    setGlobalOptions({
+        json: opts.json ?? false,
+        verbose: opts.verbose ?? false,
+        quiet: opts.quiet ?? false,
+    });
+    setApiKeyFlag(opts.apiKey);
+})
+    .action(() => {
+    // Show banner when run with no subcommand
+    showBanner(pkg.version);
+    program.help();
+});
+registerInitCommand(program);
+registerAuthCommands(program);
+registerWorkspaceCommands(program);
+registerElementCommands(program);
+registerLinkCommands(program);
+registerWorkspaceExportCommand(program);
+registerComponentCommands(program);
+registerStrategyCommands(program);
+registerResourceCommands(program);
+registerWebhookCommands(program);
+registerAgentCommands(program);
+registerApiCommands(program);
+registerSkillsCommands(program);
+registerContributeCommands(program);
+async function main() {
+    // Gate all contribute invocations (including --help) before Commander parses.
+    // Commander handles --help internally before preAction fires, so we check early.
+    const args = process.argv.slice(2);
+    const isContributeInvocation = args[0] === 'contribute';
+    if (isContributeInvocation) {
+        const approved = await isApprovedContributor().catch(() => false);
+        if (!approved) {
+            const credentials = await getStoredCredentials();
+            if (!credentials?.access_token) {
+                outputError('Authentication required. Run "skhema auth login" first.', 'contribute');
+            }
+            else {
+                outputError('Contributor access required. Apply at https://skhema.com/contribute', 'contribute');
+            }
+            process.exit(1);
+        }
+    }
+    else {
+        // Hide contribute from top-level --help for non-contributors
+        const contributeCmd = program.commands.find((c) => c.name() === 'contribute');
+        if (contributeCmd) {
+            const approved = await isApprovedContributor().catch(() => false);
+            if (!approved) {
+                ;
+                contributeCmd._hidden = true;
+            }
+        }
+    }
+    await program.parseAsync();
+}
+main();

package/dist/commands/agent.d.ts

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/commands/agent.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAyBnC,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAuK5D"}

package/dist/commands/agent.js

@@ -0,0 +1,154 @@
+import { AgentAuthError, createAgentClient } from '@skhema/agent-sdk';
+import { FileCredentialStore } from '@skhema/agent-sdk/node';
+import chalk from 'chalk';
+import ora from 'ora';
+import { AUTH_BASE_URL } from '../lib/config.js';
+import { getGlobalOptions, log, logHeader, outputError, outputSuccess, } from '../lib/output.js';
+/** Resolve the auth API base (the SDK expects the `/api/auth` root). */
+function authApiBase(override) {
+    const base = override ?? AUTH_BASE_URL;
+    return base.endsWith('/api/auth')
+        ? base
+        : `${base.replace(/\/$/, '')}/api/auth`;
+}
+function errorMessage(error) {
+    if (error instanceof AgentAuthError)
+        return `${error.message} (${error.code})`;
+    if (error instanceof Error)
+        return error.message;
+    return 'Unknown error';
+}
+export function registerAgentCommands(program) {
+    const agent = program
+        .command('agent')
+        .description('Enroll this runtime as a registered agent and sign requests');
+    agent
+        .command('enroll')
+        .argument('<token>', 'One-time enrollment token from the Skhema dashboard')
+        .description('Enroll this runtime as a registered agent (keys are generated locally)')
+        .option('--name <name>', 'A label for this agent runtime')
+        .option('--mode <mode>', 'Agent mode: delegated | autonomous', 'autonomous')
+        .option('--auth-url <url>', 'Override the Skhema auth server base URL')
+        .action(async (token, options) => {
+        const store = new FileCredentialStore();
+        const existing = await store.load();
+        if (existing) {
+            log(chalk.yellow(`Already enrolled as agent ${existing.agentId}. Run 'skhema agent logout' first.`));
+            return;
+        }
+        const mode = options.mode === 'delegated' ? 'delegated' : 'autonomous';
+        const client = createAgentClient({
+            baseUrl: authApiBase(options.authUrl),
+            store,
+        });
+        const spinner = ora('Generating keys and enrolling...').start();
+        try {
+            const cred = await client.enroll(token, { name: options.name, mode });
+            spinner.succeed(`Enrolled as agent ${chalk.cyan(cred.agentId)}`);
+            if (getGlobalOptions().json) {
+                outputSuccess({ agentId: cred.agentId, hostId: cred.hostId, mode: cred.mode }, 'agent enroll');
+            }
+            else {
+                log(`  Host: ${chalk.cyan(cred.hostId)}`);
+                log(`  Mode: ${cred.mode}`);
+                log(chalk.dim('  Credential stored at ~/.skhema/agent.json — keep it secret.'));
+            }
+        }
+        catch (error) {
+            spinner.fail('Enrollment failed');
+            outputError(errorMessage(error), 'agent enroll');
+            process.exit(1);
+        }
+    });
+    agent
+        .command('status')
+        .description("Show this runtime's agent identity")
+        .option('--verify', 'Verify the credential against the server')
+        .action(async (options) => {
+        const store = new FileCredentialStore();
+        const cred = await store.load();
+        if (!cred) {
+            log(chalk.yellow('Not enrolled. Run `skhema agent enroll <token>`.'));
+            if (getGlobalOptions().json) {
+                outputSuccess({ enrolled: false }, 'agent status');
+            }
+            return;
+        }
+        let capabilities;
+        if (options.verify) {
+            const client = createAgentClient({ baseUrl: cred.baseUrl, store });
+            const spinner = ora('Verifying with server...').start();
+            try {
+                const session = await client.session();
+                spinner.succeed('Verified');
+                capabilities = (session.agent.capabilityGrants ?? []).map((g) => g.capability);
+            }
+            catch (error) {
+                spinner.fail('Verification failed');
+                outputError(errorMessage(error), 'agent status');
+                process.exit(1);
+            }
+        }
+        if (getGlobalOptions().json) {
+            outputSuccess({
+                enrolled: true,
+                agentId: cred.agentId,
+                hostId: cred.hostId,
+                mode: cred.mode,
+                baseUrl: cred.baseUrl,
+                createdAt: cred.createdAt,
+                verified: options.verify ? true : undefined,
+                capabilities,
+            }, 'agent status');
+            return;
+        }
+        logHeader('Agent Status');
+        log(`  Agent:    ${chalk.cyan(cred.agentId)}`);
+        log(`  Host:     ${chalk.cyan(cred.hostId)}`);
+        log(`  Mode:     ${cred.mode}`);
+        log(`  Server:   ${cred.baseUrl}`);
+        log(`  Enrolled: ${new Date(cred.createdAt).toLocaleString()}`);
+        if (options.verify) {
+            log(`  Verified: ${chalk.green('yes')}`);
+            if (capabilities && capabilities.length > 0) {
+                log(`  Capabilities: ${capabilities.join(', ')}`);
+            }
+        }
+    });
+    agent
+        .command('rotate')
+        .description("Rotate this agent's signing key (identity and grants unchanged)")
+        .action(async () => {
+        const store = new FileCredentialStore();
+        const cred = await store.load();
+        if (!cred) {
+            log(chalk.yellow('Not enrolled. Run `skhema agent enroll <token>`.'));
+            return;
+        }
+        const client = createAgentClient({ baseUrl: cred.baseUrl, store });
+        const spinner = ora('Rotating agent key...').start();
+        try {
+            await client.rotate();
+            spinner.succeed('Agent key rotated. The previous key no longer works.');
+            if (getGlobalOptions().json) {
+                outputSuccess({ rotated: true, agentId: cred.agentId }, 'agent rotate');
+            }
+        }
+        catch (error) {
+            spinner.fail('Rotation failed');
+            outputError(errorMessage(error), 'agent rotate');
+            process.exit(1);
+        }
+    });
+    agent
+        .command('logout')
+        .description("Remove this runtime's stored agent credential")
+        .action(async () => {
+        const store = new FileCredentialStore();
+        await store.clear();
+        log(chalk.green('Agent credential removed.'));
+        if (getGlobalOptions().json) {
+            outputSuccess({ loggedOut: true }, 'agent logout');
+        }
+    });
+}

package/dist/commands/api.d.ts

@@ -0,0 +1,19 @@
+import { Command } from 'commander';
+interface OpenApiOperation {
+    summary?: string;
+}
+interface OpenApiSpec {
+    paths?: Record<string, Record<string, OpenApiOperation>>;
+}
+/**
+ * Flatten an OpenAPI document to a sorted `{ method, path, summary }` list.
+ * Exported for unit testing against a spec fixture.
+ */
+export declare function renderRouteRows(spec: OpenApiSpec): Array<{
+    method: string;
+    path: string;
+    summary: string;
+}>;
+export declare function registerApiCommands(program: Command): void;
+export {};
+//# sourceMappingURL=api.d.ts.map

package/dist/commands/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../src/commands/api.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAuBnC,UAAU,gBAAgB;IACxB,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AACD,UAAU,WAAW;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAA;CACzD;AASD;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,WAAW,GAChB,KAAK,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAkB1D;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAkF1D"}

package/dist/commands/api.js

@@ -0,0 +1,97 @@
+import { readFile } from 'fs/promises';
+import { resolveClient } from '../lib/api/client.js';
+import { setApiKeyFlag } from '../lib/api/credential-context.js';
+import { normalizeMethod, normalizePath, parseQueryPairs, resolveDataBody, } from '../lib/api/passthrough.js';
+import { runCommand, UsageError } from '../lib/api/run-command.js';
+import { API_BASE_URL } from '../lib/config.js';
+import { getGlobalOptions, log, logTable } from '../lib/output.js';
+/** Read all of stdin as UTF-8 (used by `--data -`). */
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks).toString('utf-8');
+}
+const HTTP_METHODS = new Set(['get', 'post', 'put', 'delete', 'patch']);
+/** Gateway OpenAPI path keys use the regex fragment `([^/]+)` for a param. */
+function prettifyPath(pathKey) {
+    return pathKey.replace(/\(\[\^\/\]\+\)/g, '{param}');
+}
+/**
+ * Flatten an OpenAPI document to a sorted `{ method, path, summary }` list.
+ * Exported for unit testing against a spec fixture.
+ */
+export function renderRouteRows(spec) {
+    const rows = [];
+    for (const [pathKey, operations] of Object.entries(spec.paths ?? {})) {
+        for (const [method, op] of Object.entries(operations)) {
+            if (!HTTP_METHODS.has(method.toLowerCase()))
+                continue;
+            rows.push({
+                method: method.toUpperCase(),
+                path: prettifyPath(pathKey),
+                summary: op?.summary ?? '',
+            });
+        }
+    }
+    rows.sort((a, b) => a.path === b.path
+        ? a.method.localeCompare(b.method)
+        : a.path.localeCompare(b.path));
+    return rows;
+}
+export function registerApiCommands(program) {
+    const api = program
+        .command('api')
+        .description('Raw authenticated access to the Skhema Public API')
+        .argument('[method]', 'HTTP method (GET, POST, PUT, DELETE), or `routes` to list the surface')
+        .argument('[path]', 'Gateway path, e.g. /workspaces (leading /v1 optional)')
+        .option('--data <json|@file|->', 'JSON body: literal, @file, or - for stdin')
+        .option('--query <key=value>', 'Query parameter (repeatable)', (value, prev) => [...prev, value], [])
+        .option('--api-key <key>', 'API key for this invocation')
+        .action(async (method, rawPath, options) => {
+        await runCommand(`api ${method ?? ''}`.trim(), async () => {
+            if (options.apiKey)
+                setApiKeyFlag(options.apiKey);
+            if (!method || !rawPath) {
+                throw new UsageError('Usage: skhema api <method> <path>  (or `skhema api routes`).');
+            }
+            const httpMethod = normalizeMethod(method);
+            const path = normalizePath(rawPath, API_BASE_URL);
+            const query = parseQueryPairs(options.query);
+            const body = await resolveDataBody(options.data, {
+                readFile: (p) => readFile(p, 'utf-8'),
+                readStdin,
+            });
+            const { client } = await resolveClient();
+            const data = await client.request(httpMethod, path, {
+                body,
+                query,
+            });
+            // Human mode: pretty-print the response body. --json mode: the response
+            // is the envelope's `data` (emitted by runCommand).
+            if (!getGlobalOptions().json) {
+                log(JSON.stringify(data ?? null, null, 2));
+            }
+            return data;
+        });
+    });
+    api
+        .command('routes')
+        .description('List every live gateway route from /v1/openapi.json')
+        .action(async () => {
+        await runCommand('api routes', async () => {
+            const { client } = await resolveClient();
+            const spec = await client.meta.openapi();
+            if (getGlobalOptions().json) {
+                // Under --json the raw spec is the payload (the envelope wraps it).
+                return spec;
+            }
+            const rows = renderRouteRows(spec);
+            logTable(['Method', 'Path', 'Summary'], rows.map((r) => [r.method, r.path, r.summary]));
+            log('');
+            log(`${rows.length} routes.`);
+            return { count: rows.length };
+        });
+    });
+}

package/dist/commands/auth.d.ts

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/commands/auth.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAqEnC,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAyT3D"}