@skhema/cli

The Skhema command-line interface (skhema). Authenticate as a human or an agent, then drive the Skhema Public API from your terminal, CI, or an autonomous agent — workspaces, elements, components, strategies, exports, resources, and webhooks, plus one-command agent onboarding.

Install

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:

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.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:

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.

Strategy document imports

Import a local strategy document or public URL through the same reviewable proposal used by the web and MCP surfaces:

skhema import start --file ./strategy.pdf --wait
skhema import get imp_...                       # inspect the mapped proposal
skhema import decide imp_... --file decisions.json
skhema import apply imp_... --workspace-name "Imported strategy" --yes

Use --json for a stable machine envelope. Applying or discarding requires an interactive confirmation, or an explicit --yes in scripts and CI.

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:

skhema auth status
# Credential:   SKHEMA_API_KEY environment variable
# Key:          sk_live_...a1b2
# Verified:     Yes
# Permission:   read-write
# Organization: org_…

Managing API keys

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

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:

// 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

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.

Contributor commands

Approved contributors get a contribute command group for generating embeds and shareable links, and for inspecting their account, analytics, and payouts. Every command is gated on approved-contributor status and honours --json.

skhema contribute generate embed --element-type key_challenge \
  --content "..." --contributor-id contrib_…      # HTML <skhema-element> snippet
skhema contribute generate link  --element-type key_challenge \
  --content "..." --contributor-id contrib_…      # save + share links

skhema contribute status                          # approval status, ID, display name
skhema contribute profile                         # public profile (edit at contribute.skhema.com/account)
skhema contribute analytics --time-range 30d      # embeds, loads, clicks, CTR + top content
skhema contribute analytics --content-hash <hash> # per-content detail with top pages
skhema contribute payouts                         # payout history (20% commission, 60-day hold)

Generated embed snippets pin the CDN to a specific @skhema/embed version (https://unpkg.com/@skhema/embed@<version>/dist/embed.min.js), so a published snippet renders identically forever rather than tracking latest.

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 — use it directly when you want Skhema in your own code rather than your terminal.

License

MIT