@outkit-dev/cli
v0.5.0
Published
The Outkit command-line tool. Wires Outkit into existing apps with a single command.
Readme
@outkit-dev/cli
The Outkit command-line tool. Wire your app to Outkit, sync design tokens, debug the wire format, manage profiles + API keys, and (optionally) hand off complex grafts to your installed coding agent — all without leaving your terminal.
Status: 0.4.0 — full v0.1 surface complete. Network commands talk to https://api.outkit.dev by default.
Install
npm install -g @outkit-dev/cli
# or
pnpm add -g @outkit-dev/cliCommands
Auth & identity
| Command | What it does |
| --- | --- |
| outkit login | Device-code flow. Opens the dashboard, approves the device, saves a token to ~/.outkit/credentials.json (mode 0600). |
| outkit whoami | Print the signed-in user, team, and device (network round-trip). |
| outkit logout | Revoke the device on the server and wipe local credentials. |
| outkit switch | Switch the active team or profile for this CLI session. |
| outkit status | Local-only "what does the CLI know about my setup". |
| outkit doctor [--backend <url>] [--full] [--json] | End-to-end health check: auth, network, project mode, SDK packages, wire format, design-token meta event. |
| outkit telemetry on\|off\|status\|log | Toggle and inspect anonymous usage analytics. Local NDJSON log at ~/.outkit/telemetry.log even when off. |
Project setup
| Command | What it does |
| --- | --- |
| outkit init [--no-install] [--profile <id>] | Mode-aware project wiring. Detects framework, picks a profile, writes outkit.json, prints the swap snippet for your stack (React, Vue, Svelte, Astro, vanilla JS), and offers to install the right SDK. |
| outkit config | View or edit the local outkit.json. |
| outkit upgrade | Bump @outkit-dev/* packages and run any required codemods. |
| outkit migrate [from] [to] | Run codemods between two SDK versions. |
| outkit undo [-y, --yes] | Reverse the last code-mutating command (journaled at ~/.outkit/undo.json). Refuses to clobber files you have edited; prints uninstall commands rather than auto-removing dependencies. |
Theme sync
The theme cascade detects design tokens in this order: shadcn/ui CSS vars
→ Tailwind v4 @theme blocks → Tailwind v3 config → CSS-in-JS configs
(Chakra, Mantine, Stitches, Panda, Tamagui) → inline <ThemeProvider> JSX
literals → generic :root { --… } blocks → SVG logo extraction → repo-wide
hex frequency.
| Command | What it does |
| --- | --- |
| outkit theme | Interactive: detect, preview swatches, confirm, apply. |
| outkit theme detect [--json] | Detect-only. Print the cascade result without writing. |
| outkit theme apply [--from <file>] [--map <map.json>] [--preset <id>] [-y] | Detect (or load preset) → contrast guard → push to active profile. |
| outkit theme presets [--json] | List curated palettes (modern-neutral, vibrant-violet, warm-editorial, dark-first) with terminal swatches. |
| outkit theme sync [--on-build] | One-shot detect+apply for CI. --on-build adds a prebuild hook to your package.json. |
| outkit theme watch | Re-sync whenever a known source file changes. |
| outkit theme map | Inspect or override the canonical name mapping. outkit theme map --explain prints the full table. |
| outkit theme regen-surfaces | Recompute surfaceLowest…surfaceHighest from the current background. |
| outkit theme pull | Fetch the active profile back into outkit.theme.json. |
| outkit theme push | Validate outkit.theme.json, show diff, PATCH the active profile. |
| outkit theme diff | Print local-vs-remote diff. Exits non-zero when they differ — useful for CI. |
Profiles & deploy
| Command | What it does |
| --- | --- |
| outkit profiles list | List profiles available to your team. |
| outkit profiles create --name <name> | Create a new profile. |
| outkit profiles use <profileId> | Set the active profile for this repo. |
| outkit profiles pull | Write the active profile to a local JSON file. |
| outkit profiles push | Push a local profile JSON file as a new version. |
| outkit profiles diff [a] [b] | Diff two version IDs (defaults to the latest two). |
| outkit profiles deploy [--version <id>] [-y] | Mark a version live. |
| outkit profiles rollback <versionId> | Re-deploy an older version. |
| outkit deploy [--version <id>] [-y] | Alias of profiles deploy for the active profile. |
API keys
| Command | What it does |
| --- | --- |
| outkit keys list [--all] [--profile <id>] | List API keys. Hides revoked unless --all. |
| outkit keys create [-n <name>] [--profile <id>] | Create a new API key bound to the active profile. Plaintext shown once. |
| outkit keys rotate <keyId> | Rotate with a 24-hour grace window on the old key. |
| outkit keys revoke <keyId> [-y] | Immediately revoke a key everywhere. |
| outkit keys stats <keyId> | Show usage, errors, and last-used time. |
Local development
| Command | What it does |
| --- | --- |
| outkit dev | Tail render logs in real time alongside your dev server. Resolves ${VAR} placeholders in backendUrl against process.env and .env.local. |
| outkit logs list | Show recent render logs (newest first). |
| outkit logs tail | Stream new logs as they arrive (polls every 2s). |
| outkit logs replay <logId> | Replay a single log entry. |
| outkit logs export [--since <date>] | Bulk-export to JSON or CSV. |
MCP & coding agents
| Command | What it does |
| --- | --- |
| outkit mcp install --client claude-desktop\|cursor\|windsurf | Write the MCP server entry into your AI client config — no manual JSON editing. |
| outkit mcp uninstall --client <name> | Remove the entry. |
| outkit mcp test | Smoke-test the MCP connection. |
| outkit agent --task "<text>" [--agent claude\|cursor\|copilot] [--no-verify] | Hand a complex Outkit graft to your installed coding agent. The agent returns a structured plan; the CLI validates it (path-escape, secret-leak, denied-scope, size limits), shows the diff, and applies it via the same backup+undo pipeline as init. Verifies with tsc + Biome + your test command. |
Auth model
- Device-code (RFC 8628 inspired) flow against
POST /cli/authorize/{start,poll}. - Tokens are opaque (
okcli_…) and are only valid for CLI endpoints. - Tokens are SHA-256-hashed before storage server-side. Plaintext is shown to the CLI exactly once at the end of the flow.
- 90-day sliding TTL. Revoke any device from the dashboard or via
outkit logout.
Project files the CLI manages
| Path | Owner | Notes |
| --- | --- | --- |
| outkit.json | committed to your repo | { version, mode, teamId, profileId, backendUrl?, sdkVersion?, themeMap? }. The CLI's repo-local config. |
| outkit.theme.json | committed to your repo | Local copy of the profile's design tokens. Edit, then outkit theme push. |
| ~/.outkit/credentials.json (mode 0600) | per-user, never commit | Auth token + cached config. |
| ~/.outkit/undo.json (mode 0600) | per-user, never commit | Append-only journal feeding outkit undo. Bounded to the last 50 entries. |
| ~/.outkit/telemetry.log (NDJSON) | per-user, never commit | Glass-jar log of every event the CLI would send when telemetry is on. Auto-truncates at 1MB. |
Environment overrides
| Variable | Default | Use case |
| --- | --- | --- |
| OUTKIT_API_BASE_URL | https://api.outkit.dev | Point at staging / self-host. |
| OUTKIT_DASHBOARD_BASE_URL | https://app.outkit.dev | Match the API override. |
| OUTKIT_DEBUG=1 | off | Print stack traces on uncaught errors. |
Development
pnpm install
pnpm --filter @outkit-dev/cli build
pnpm --filter @outkit-dev/cli test
node packages/cli/dist/index.js --help@outkit-dev/cli
The Outkit command-line tool. Sign in, wire Outkit into your project, sync design tokens, deploy profile versions, and undo it all when you change your mind.
Status: 0.3.0 — auth, project setup, theme sync, deploy, and API key management are live. Network commands talk to https://api.outkit.dev by default.
Install
npm install -g @outkit-dev/cli
# or
pnpm add -g @outkit-dev/cliCommands
Auth
| Command | What it does |
| --- | --- |
| outkit login | Device-code flow. Opens the dashboard, approves the device, saves a token to ~/.outkit/credentials.json (mode 0600). |
| outkit whoami | Print the signed-in user, team, and device (network round-trip). |
| outkit logout | Revoke the device on the server and wipe local credentials. |
| outkit status | Local-only "what does the CLI know about my setup". |
| outkit doctor | End-to-end health check (network + auth). |
| outkit telemetry on\|off\|status | Toggle anonymous usage analytics. |
Project
| Command | What it does |
| --- | --- |
| outkit init [--no-install] [--profile <id>] | Pick (or auto-pick) a profile, write outkit.config.json, and offer to install @outkit-dev/react. |
| outkit theme pull [-f, --force] | Fetch the active profile's tokens into outkit.theme.json. |
| outkit theme push [-y, --yes] | Validate outkit.theme.json, show a diff, and PATCH the active profile. |
| outkit theme diff | Print the diff between local and remote theme. Exits non-zero when they differ — useful for CI. |
| outkit deploy [--version <id>] [-y, --yes] | Mark a profile version live. Defaults to the most recent version. |
| outkit keys list [--all] [--profile <id>] | List API keys. Hides revoked unless --all. |
| outkit keys create [-n, --name <name>] [--profile <id>] | Create a new API key bound to the active profile. Plaintext shown once. |
| outkit keys revoke <keyId> [-y, --yes] | Immediately revoke a key everywhere. |
| outkit undo [-y, --yes] | Reverse the last code-mutating command (journaled at ~/.outkit/undo.json). Refuses to clobber files you have edited; prints uninstall commands rather than auto-removing dependencies. |
Auth model
- Device-code (RFC 8628 inspired) flow against
POST /cli/authorize/{start,poll}. - Tokens are opaque (
okcli_…) and are only valid for CLI endpoints. - Tokens are SHA-256-hashed before storage server-side. Plaintext is shown to the CLI exactly once at the end of the flow.
- 90-day sliding TTL. Revoke any device from the dashboard or via
outkit logout.
Project files the CLI manages
| Path | Owner | Notes |
| --- | --- | --- |
| outkit.config.json | committed to your repo | { version, teamId, profileId }. Tells theme and deploy which profile to target. |
| outkit.theme.json | committed to your repo | Local copy of the profile's design tokens. Edit, then outkit theme push. |
| ~/.outkit/credentials.json (mode 0600) | per-user, never commit | Auth token + cached config. |
| ~/.outkit/undo.json (mode 0600) | per-user, never commit | Append-only journal feeding outkit undo. Bounded to the last 50 entries. |
Environment overrides
| Variable | Default | Use case |
| --- | --- | --- |
| OUTKIT_API_BASE_URL | https://api.outkit.dev | Point at staging / self-host. |
| OUTKIT_DASHBOARD_BASE_URL | https://app.outkit.dev | Match the API override. |
| OUTKIT_DEBUG=1 | off | Print stack traces on uncaught errors. |
Development
pnpm install
pnpm --filter @outkit-dev/cli build
node packages/cli/dist/index.js --help