| name | cli-sync |
| description | This skill should be used when the user asks to "check CLI schema", "sync CLI version", "check for new CLI options", "update bundled CLI", "compare SDK structs", "check schema drift", "align message structs", "verify CLI compatibility", "check control protocol", or mentions CLI compatibility, schema alignment, or wants to ensure the SDK matches the current Claude CLI. Consolidates schema checking, options validation, control protocol coverage, and version management into a single workflow. |
| version | 2.0.0 |
CLI Sync
Synchronize the ClaudeCode Elixir SDK with the Claude CLI to detect schema changes, new options, control protocol drift, and update the bundled version.
Overview
The Claude CLI evolves independently of this SDK. This skill dispatches five parallel agents to check alignment across all layers: versions, message types, content blocks, control protocol, and CLI options. Each agent has self-contained instructions in a references/check-*.md file.
Canonical sources: The TypeScript SDK (@anthropic-ai/claude-agent-sdk) provides the SDKMessage union (message types) and SDKControl* types (control protocol). The Anthropic API SDK (@anthropic-ai/sdk) provides BetaContentBlock types. The Python SDK (claude-agent-sdk-python) provides cross-reference for options, field names, control protocol handling, and message parsing. See references/upstream-sources.md for the complete file-level mapping.
Workflow
Step 1: Check the Changelog
Before doing anything else, fetch and review the CLI changelog to understand what has changed since the last sync:
curl -sL "https://code.claude.com/docs/en/changelog.md" > .claude/skills/cli-sync/captured/docs/changelog.md
Read the fetched changelog and identify:
- New CLI features, options, or flags added
- Message type or content block changes
- Control protocol changes
- Breaking changes or deprecations
- SDK-relevant behavioral changes
This gives you a high-level roadmap of what to look for in the detailed sync analysis that follows. Note the specific changes that are relevant to the SDK so you can prioritize them in the subsequent steps.
Step 2: Refresh Captured Data
Run the capture script via Bash to fetch the latest CLI version, help output, and SDK type definitions:
.claude/skills/cli-sync/scripts/capture-cli-data.sh
This fetches claude --version, claude --help, TypeScript/Python SDK types from npm/GitHub, Anthropic API types, and official documentation (CLI reference, hooks, plugins reference, TS SDK docs, Python SDK docs). Verify the script completes without errors before proceeding.
Step 3: Dispatch Parallel Agents
Read the corresponding references/check-*.md file for each agent's full instructions, then dispatch all five in parallel.
| Agent | Reference File | What It Checks |
|---|
| Versions | references/check-versions.md | CLI vs bundled version alignment, SDK versions |
| Message Types | references/check-message-types.md | SDKMessage union vs Elixir message/ modules |
| Content Blocks | references/check-content-blocks.md | BetaContentBlock union vs Elixir content/ modules |
| Control Protocol | references/check-control-protocol.md | SDKControl* types vs control.ex and port.ex |
| Options | references/check-options.md | CLI flags and SDK options vs options.ex |
Each agent produces a structured report with coverage tables and summary counts.
Step 4: Summarize Findings
Collect all five agent reports into a unified summary:
- Version alignment -- synced or out of sync, SDK versions for reference
- Message type coverage -- table with status per SDKMessage type
- Content block coverage -- table with status per BetaContentBlock type + deltas
- Control protocol coverage -- four tables (outbound, inbound, responses, accessors)
- Options coverage -- table with status per CLI flag
Recommend next steps for any gaps found.
Step 5: Implement Changes
For each change identified, consult the appropriate reference file for patterns:
| Change Type | Pattern Reference | Test File |
|---|
| New struct fields | references/type-mapping.md | test/claude_code/message/<type>_test.exs or content/ |
| New CLI options | references/cli-flags.md | test/claude_code/options_test.exs, cli/command_test.exs |
| New control requests | references/type-mapping.md | test/claude_code/cli/control_test.exs |
| Version update | Update @default_cli_version in installer.ex and the doctest in lib/claude_code.ex (ClaudeCode.cli_version/0) | -- |
When adding new message or content types, also add a factory function in lib/claude_code/test/factory.ex and update lib/claude_code/test.ex if the type needs a user-facing test helper.
When adding new options, prefer Elixir-native syntax: atoms for enumerations, tagged tuples for variants with data, preprocessing in command.ex over direct mapping.
Step 6: Update Reference Files
After implementing changes, update the data reference files to reflect the new state:
references/type-mapping.md -- Add new rows to the appropriate table (message types, content blocks, control protocol, or other structs)references/cli-flags.md -- Add new flag mappings to the implemented flags table
Step 7: Verify
mix quality
mix test
After verification, update documentation:
- CLAUDE.md -- If new options or message types added
- CHANGELOG.md -- Document schema alignment changes
- Module docs -- Update option descriptions as needed
Additional Resources
Scripts
scripts/capture-cli-data.sh -- Main capture script (CLI version, help output, SDK type definitions)scripts/compare-versions.sh -- Quick version comparison
Captured SDK Sources
The capture script also fetches these into captured/:
ts-sdk-types.d.ts — TypeScript SDK type definitions (SDKMessage, SDKControl*, Options, etc.)ts-sdk-cli.js — Minified CLI implementation (gitignored, ~12MB). Contains the actual control protocol dispatch, message routing, hook execution, and permission handling. Useful for tracing protocol behavior when the type definitions alone are ambiguous.python-sdk-*.py — Python SDK sources (types, query, client, message parser, subprocess CLI)anthropic-api-messages.d.ts — Anthropic API types (BetaContentBlock, streaming events)
Captured Documentation
The capture script fetches these official docs into captured/docs/:
- Changelog:
changelog.md — CLI release notes, new features, breaking changes
- CLI Reference:
cli-reference.md — CLI flags, options, environment variables
- Hooks:
hooks.md — Hook events, lifecycle, configuration
- Plugins Reference:
plugins-reference.md — Plugin structure, manifest, components
- TypeScript SDK:
typescript.md — TS Agent SDK options, types, usage
- Python SDK:
python.md — Python Agent SDK options, types, usage
