@bdky/chat-pilot-kit-cli

@bdky/chat-pilot-kit-cli is a local CLI for chat-pilot-kit workflows. It helps agents and developers:

• query chat-pilot-kit contracts before writing code
• inspect and apply starter recipes
• diagnose project-level integration gaps
• lint protocol-level agent and extension issues

Install

npm install -g @bdky/chat-pilot-kit-cli

Verify the CLI is available:

which cpk

AI Tool Onboarding

Four ways an AI coding tool can pick up chat-pilot-kit contracts, depending on what's available in the environment:

1. Claude Code — team members with repo access

This repo ships a Claude Code plugin (.claude-plugin/marketplace.json at the repo root, libs/chat-pilot-kit-cli/.claude-plugin/plugin.json as the plugin root — its skills/ directory is auto-discovered). Inside Claude Code:

/plugin marketplace add ssh://[email protected]:8235/baidu/ai/keyue-fe-kit
/plugin install chat-pilot-kit

(claude has no non-interactive plugin marketplace/plugin install subcommand today, so this is a manual, in-app verification step — not scriptable in CI.) Once installed, restart Claude Code (or run /skills) to pick up skills/chat-pilot-kit/SKILL.md.

2. No-plugin environments — cpk skill install

If the plugin path above isn't available (e.g. a tool that doesn't support Claude Code plugins, or a project outside this repo), fall back to copying the SKILL file directly:

cpk skill install                 # once published to npm
node bin/cpk.js skill install     # current reality: run from this package,
                                   # e.g. from a monorepo checkout

This copies skills/chat-pilot-kit/SKILL.md into <target|cwd>/.claude/skills/ (or ~/.claude/skills/ with --global), idempotently.

3. Any LLM coding tool — llms.txt / llms-full.txt

Both files ship with this package (llms.txt for a concise API index, llms-full.txt for the signature-level expansion — full RN export surface, the four required pitfalls, recipe/doctor/lint rule tables, and the full cpk command surface). Any tool that reads llms.txt-style files from node_modules/@bdky/chat-pilot-kit-cli/ can use them directly. Uploading either file to a documentation site's /llms.txt root path is a maintainer action, not something this package automates.

4. Maintenance rule

plugin.json's version and marketplace.json's plugins[].version must be bumped alongside this package's own package.json version on every release (see src/__tests__/plugin-manifest.spec.ts for the assertion that keeps plugin.json in sync).

Local Smoke Test

Run these commands from libs/chat-pilot-kit-cli to verify the CLI locally without global installation:

yarn dev list --format json
yarn dev info node-system --detail --format markdown
yarn dev info event-system --detail --format json
yarn dev recipe list --format json
yarn dev recipe show custom-stream-node-extension --format json
yarn dev recipe apply event-observer --mode patch --format json

These commands cover topic discovery, node/event knowledge output, recipe discovery, recipe details, and generated sample output.

Commands

• cpk list
• cpk info
• cpk recipe list
• cpk recipe show
• cpk recipe apply
• cpk doctor
• cpk lint
• cpk skill install

Use the built-in help when needed:

cpk --help
cpk info --help
cpk -V

Recommended Workflow

1. Discover available topics with cpk list
2. Query the relevant contract with cpk info
3. Inspect recipes before scaffolding with cpk recipe list and cpk recipe show
4. Apply a recipe with cpk recipe apply
5. Run cpk doctor --format json
6. Run cpk lint --format json

Prefer --format json for agent-driven workflows.

Output Contract

cpk now emits a normalized result envelope.

Successful commands return:

• ok
• command
• summary
• data
• issues
• nextActions
• meta

Failed command execution returns:

• ok
• command
• error
• meta

meta.format reflects the selected output format, and meta.targetPath appears on path-scoped commands such as doctor, lint, and recipe apply --mode files.

Exit Codes

• 0: command executed successfully
• 1: invalid arguments or command execution failure
• 2: analysis failure for cpk lint

Scenarios

Discover available knowledge topics

Use list when an agent needs a concise topic index before choosing the right contract.

cpk list --format json
cpk list --category core --format text

JSON output includes topic id, title, category, summary, aliases, and relatedTopics.

Query contracts before writing code

Use info before editing controller, agent service, node, or extension code.

cpk info controller --format json
cpk info agent-message-data --format json
cpk info extension --format json
cpk info node-system --detail --format json
cpk info event-system --detail --format json

Use --detail when you need full guidance, examples, and verification steps:

cpk info agent-message-data --detail --format json
cpk info extension --detail --format markdown
cpk info controller --format text

info now merges two knowledge sources:

• curated manual guidance for whenToUse, rules, pitfalls, and verification
• generated facts from core source files, type definitions, and samples

Current high-value topics include:

• controller
• agent-message-data
• extension
• base-agent-service
• node-system
• event-system

Default info output focuses on concise guidance:

• key points
• important APIs
• related files

Detailed output adds:

• API shape
• rules
• verification
• sample references

Topic lookup also supports aliases and suggestions. For example:

cpk info controller-api --format text
cpk info controllr --format json

Inspect and apply recipes

Start with discovery:

cpk recipe list --format json
cpk recipe show react-basic-chat --format json
cpk recipe show custom-stream-node-extension --format json
cpk recipe show event-observer --format json

Use --mode patch when integrating into an existing codebase:

cpk recipe apply react-basic-chat --mode patch --format json
cpk recipe apply custom-stream-node-extension --mode patch --format json
cpk recipe apply event-observer --mode patch --format json

Use --mode files when the user wants starter files written directly:

cpk recipe apply headless-custom-agent --mode files --target ./examples --format json

Learn node and event systems

Use the focused topics and samples when building custom message plugins:

cpk info node-system --detail --format markdown
cpk info custom-plugin --detail --format json
cpk info event-system --detail --format json
cpk recipe show custom-stream-node-extension --format json
cpk recipe show event-observer --format json

The node sample covers MessageExtension.create(...), StreamableGenericNode, nodeBehavior: 'append', nodeCompleted, and hydrate(...). The event sample covers useChatPilotKitEvents(...), direct controller.emitter.on(...), node_add, node_update, ttft, error, and node_interaction.

Diagnose project-level gaps

Use doctor to understand app shape and missing integration pieces:

cpk doctor ./src --format json

Typical findings include:

• controller creation missing
• agent service implementation missing
• interrupt handling missing
• persistence capability missing
• completion handling missing

Lint protocol-level issues

Use lint after modifying streaming or extension code:

cpk lint ./src --format json

Current rules cover:

• missing sessionId
• missing queryId
• suspicious nodeType
• missing onCompleted() handling

Flags

| Flag | Purpose | |---|---| | --format | Output format: json, text, or markdown | | --category | Filter topic discovery for cpk list | | --detail | Include extra topic details for cpk info | | --mode | Recipe apply mode: patch or files | | --target | Output directory for cpk recipe apply --mode files | | --into-existing | cpk recipe apply: skip entrypoint/config files and emit mergeInstructions | | --global | cpk skill install: install into ~/.claude/skills instead of a project directory |

Example End-To-End Flow

cpk list --format json
cpk info node-system --detail --format json
cpk info event-system --detail --format json
cpk recipe show custom-stream-node-extension --format json
cpk recipe apply custom-stream-node-extension --mode patch --format json
cpk doctor ./src --format json
cpk lint ./src --format json