CLI Tools

The @guidekit/cli package provides command-line tools for project setup and diagnostics.

Installation

The CLI is available via npx (no installation needed):

npx guidekit <command>

Or install globally:

npm install -g @guidekit/cli

Commands

guidekit init

Interactive setup wizard that scaffolds GuideKit configuration for your project.

npx guidekit init
npx guidekit init --platform

What it does:

1. Detects your framework (Next.js App Router, Pages Router, React)
2. Checks for missing packages
3. Creates .env.local with GuideKit variables
4. For Next.js App Router + token auth: creates lib/guidekit-routes.ts and /api/guidekit/{token,llm,health} routes
5. With --platform: also scaffolds STT/TTS routes and Platform Mode provider props
6. Creates a provider wrapper component (Next.js App Router)
7. Optionally patches layout.tsx to import Providers

Options:

• --yes — Skip prompts and use defaults
• --platform — Enable Platform Mode (RAG, plugins, intelligence)
• --auth-mode token|direct — Proxy auth mode (default: token)
• --json — Output the scaffold result as JSON (implies --yes)

npx guidekit init --yes --platform
npx guidekit init --yes --auth-mode direct --json

guidekit doctor

Validates your setup — checks environment variables, packages, proxy route files, provider wiring, local endpoints (when the dev server is running), external provider connectivity, and, when run inside the GuideKit monorepo, CI/local parity for the example app and release-confidence workflows.

npx guidekit doctor
npx guidekit doctor --fix
npx guidekit doctor --json

When run interactively, doctor will offer to apply safe fixes (create .env.local, generate a GUIDEKIT_SECRET, add .env to .gitignore, scaffold missing proxy routes, and wire the provider into layout.tsx). Use --fix to apply them without prompting, or --json to get machine-readable output.

Checks performed:

• .env / .env.local file exists
• .gitignore includes .env files
• GUIDEKIT_SECRET is set and valid length
• LLM_API_KEY is present
• STT_API_KEY and TTS_API_KEY (optional, for voice)
• @guidekit/core, @guidekit/react, @guidekit/server are installed
• Proxy route files and layout.tsx provider wiring (Next.js App Router)
• Local /api/guidekit/token and /api/guidekit/health (warns if dev server is not running)
• Connectivity to Google AI, Deepgram, and ElevenLabs APIs
• In the GuideKit monorepo, example-app token-route parity, hosted PR E2E coverage, and the Nightly dependency-audit gate

Example output:

GuideKit Doctor — Checking your setup

ℹ Project root: /Users/you/myapp

Environment
✓ .env file: Found .env.local
✓ .gitignore: .env files are ignored
✓ GUIDEKIT_SECRET: Set and valid length
✓ LLM API Key: Found
○ STT API Key: Not set (optional)
○ TTS API Key: Not set (optional)

Packages
✓ @guidekit/core: Installed (^0.1.0)
✓ @guidekit/react: Installed (^0.1.0)
✓ @guidekit/server: Installed (^0.1.0)

Connectivity
✓ LLM provider connectivity: Reachable
✓ STT provider connectivity: Reachable
✓ TTS provider connectivity: Reachable

✓ All checks passed! Your GuideKit setup looks good.

guidekit generate-secret

Generates a cryptographically random 256-bit signing secret for JWT token authentication.

npx guidekit generate-secret
npx guidekit generate-secret --write-env
npx guidekit generate-secret --write-env --copy
npx guidekit generate-secret --json

When run interactively, the command can write GUIDEKIT_SECRET directly to .env.local and copy it to the clipboard. Use --write-env and --copy to do this without prompting, or --json to get machine-readable output.

Output:

GuideKit — Generate Signing Secret

✓ Generated a cryptographically random 256-bit signing secret:

  SIIwq8fzeBsh1s5WTTMBZEiXcxU5BH51A0ScD5ORVvQ

✓ Saved GUIDEKIT_SECRET to /Users/you/myapp/.env.local

Warning: Keep this secret safe. Never commit it to version control.

Interactive menu

Running npx guidekit without a command in an interactive terminal opens a menu so you can pick a command instead of typing it:

npx guidekit

In CI or non-TTY environments, the same command prints the help text below.

Help

npx guidekit --help
npx guidekit --version