cli-sync

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:

# Fetch the changelog
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:

1. Version alignment -- synced or out of sync, SDK versions for reference
2. Message type coverage -- table with status per SDKMessage type
3. Content block coverage -- table with status per BetaContentBlock type + deltas
4. Control protocol coverage -- four tables (outbound, inbound, responses, accessors)
5. 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    # Compile, format, credo, dialyzer
mix test       # All tests pass

After verification, update documentation:

1. CLAUDE.md -- If new options or message types added
2. CHANGELOG.md -- Document schema alignment changes
3. 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