kiroku-ai CLI

Interactive CLI to bootstrap Kiroku AI Standards (AI Context as Code) into any project.

# Run without installing
pnpm dlx @kiroku-solutions/kiroku-ai

# Or install globally
npm i -g @kiroku-solutions/kiroku-ai
kiroku --help

Commands

Setup & sync

kiroku init

Guided setup wizard. Picks a stack, downloads the matching skills from the SSOT, scaffolds the engine folders, injects the sync workflow, and writes the native permission config.

kiroku init
kiroku init --force          # Re-init even if a lockfile already exists
kiroku init --dry-run        # Resolve and print files without writing
kiroku init --ref v1.2.0     # Pin to a specific SSOT ref

Setup modes:

• Quickstart — pick a predefined stack preset and go.
• Auto-Detect — scans the project (package.json, config files) and proposes the stack.
• Guided — answer the stack questionnaire step by step.
• Modular — Guided + architecture, methodology, development practices, and per-agent selection.

kiroku update

Re-syncs skills for the stack recorded in the lockfile. Downloads the latest versions, prunes stale files that left the resolved set, and re-applies governance folders + permission config.

kiroku update
kiroku update --ref v1.3.0   # Pull from a specific ref instead of the recorded one

kiroku env [tool]

Switches the active AI tool. Migrates installed folders to the new tool's convention, swaps the pointer file, and re-asks permission preferences (pre-filled from the saved values).

kiroku env                   # Interactive picker
kiroku env opencode          # Non-interactive

Supported tools:

| Key | Tool | Pointer file | Skills dir | Agents dir | |---|---|---|---|---| | claude-code | Claude Code | CLAUDE.md | .claude/skills/ | .claude/agents/ | | cursor | Cursor | .cursor/rules/kiroku-ai.mdc | skills/ | .agents/ | | copilot | GitHub Copilot | .github/copilot-instructions.md | skills/ | .agents/ | | opencode | OpenCode | AGENTS.md | .opencode/skills/ | .opencode/agents/ | | antigravity | Antigravity (Gemini) | GEMINI.md | .agent/skills/ | .agent/agents/ | | windsurf | Windsurf | .windsurf/rules/kiroku-ai.md | skills/ | .agents/ |

kiroku scaffold

Generates a runnable starter project for the recorded stack (e.g. Next.js app, FastAPI service). Also offered at the end of kiroku init.

kiroku stackinfo

Analyzes the project at --dir and prints the detected stack (frontend, backend, databases, deploy, devops) and total dependency count.

Inspect & diagnose

kiroku status

Quick health snapshot of the current install.

✓ Lockfile          ref: main  (2024-06-04)
✓ AI tool           Claude Code
✗ Skills            12 files  (10/12 on disk — 2 missing)
✓ Pointer file      CLAUDE.md
✓ Sync workflow     .github/workflows/kiroku-ai-sync.yml
✓ Policy file       .claude/settings.json

kiroku doctor

Full diagnostics with 7 checks and actionable fix suggestions for every issue found.

Checks: lockfile presence + version, required fields, GitHub connectivity (token validity), files on disk, pointer file, sync workflow, policy file.

[ERROR]  Pointer file CLAUDE.md not found
         Fix: Run `kiroku init --force` or `kiroku env` to regenerate it.

[WARN]   2 skill file(s) missing from disk
         Fix: Run `kiroku update` to restore.

Returns exit code 1 if any errors are found.

kiroku diff

Dry-run preview of what kiroku update would change — without writing anything.

  + skills/frontend/nextjs/app-router.md
  - skills/backend/old-patterns.md
  ~ skills/global/01-coding-standards.md  (content changed)

  1 added, 1 removed, 1 changed

kiroku diff
kiroku diff --ref v1.4.0     # Diff against a specific ref

kiroku changelog

Shows SSOT commits that touched skills/ since the last update.

kiroku changelog
kiroku changelog --since 2024-01-01
kiroku changelog --limit 50

  a1b2c3d  2024-06-01  feat(skills): add nextjs app router rules
  e4f5g6h  2024-05-28  fix(global): tighten security practices

Skill management

kiroku add <selector>

Adds specific skills by path without re-running init. Accepts a directory prefix or a single file path (relative to skills/).

kiroku add frontend/nextjs
kiroku add global/security-review.md
kiroku add agents/security-auditor.md

kiroku remove <selector>

Removes installed skills from disk and from the lockfile. Safe to run — kiroku update will restore them if needed.

kiroku remove frontend/astro
kiroku remove global/old-rules.md

kiroku search <term>

Searches the SSOT catalog for skills matching the term. Groups results by category and marks already-installed files with ✓.

kiroku search testing
kiroku search supabase

kiroku validate

Lints all skill files in the current install (skips proposals/ and local/). Checks:

• Non-empty content
• Top-level # Heading present
• File size under 10 KB (warns if larger)

Returns exit code 1 if any files fail.

kiroku propose

Interactive wizard that creates a new skill proposal in skills/proposals/. Prompts for name, category, and a one-line description, then generates a structured Markdown template.

kiroku propose

Commit and push to main to trigger the sync workflow and open a PR in the SSOT repo.

Workspace (multi-project / monorepo)

Manage kiroku across multiple projects from a single kiroku.workspace.json.

kiroku workspace init

Interactively creates kiroku.workspace.json in the current directory.

{
  "version": 1,
  "projects": [
    { "dir": "apps/web", "name": "web" },
    { "dir": "apps/api", "name": "api" }
  ]
}

kiroku workspace update

Runs kiroku update for every project in the workspace and reports results per project.

kiroku workspace status

Health report for all projects: AI tool, ref, file count, and drift detection.

  ✓ apps/web        Claude Code  ref: main  14 files
  ✗ apps/api        Claude Code  ref: main  12 files  2 missing

Global options

| Flag | Default | Description | |---|---|---| | --dir <path> | cwd | Target project directory | | --ref <ref> | main | Git ref (branch, tag, SHA) to pull from | | --since <ISO date> | — | Lower bound for changelog | | --limit <n> | 30 | Max commits for changelog | | --force | false | Re-init even if lockfile exists | | --dry-run | false | Resolve and list files without writing | | -h, --help | — | Show help | | -v, --version | — | Show version |

Authentication

Skills are pulled from a private GitHub repository. The CLI looks for a token in this order:

1. KIROKU_AI_TOKEN environment variable
2. GH_TOKEN environment variable
3. //api.github.com/:_authToken= entry in ~/.npmrc or ./.npmrc
4. Interactive prompt (saved to ~/.npmrc on first run)

The token needs repo (read) permission on Kiroku-Solutions/kiroku-ai-standards.

Environment overrides

| Variable | Default | Description | |---|---|---| | KIROKU_AI_TOKEN | — | GitHub PAT for private repo access | | KIROKU_AI_ORG | Kiroku-Solutions | SSOT repository owner | | KIROKU_AI_REPO | kiroku-ai-standards | SSOT repository name | | KIROKU_AI_REF | main | Default git ref | | KIROKU_AI_SOURCE | — | Local path override (dev/testing) |

Development

cd CLI
pnpm install
node bin/kiroku-ai.mjs --help

# Test against a local checkout of the SSOT
KIROKU_AI_SOURCE=.. node bin/kiroku-ai.mjs init