{"meta":{"title":"SDK and CLI compatibility","intro":"This document outlines which Copilot CLI features are available through the SDK and which are CLI-only.","product":"GitHub Copilot","breadcrumbs":[{"href":"/en/copilot","title":"GitHub Copilot"},{"href":"/en/copilot/how-tos","title":"How-tos"},{"href":"/en/copilot/how-tos/copilot-sdk","title":"Copilot SDK"},{"href":"/en/copilot/how-tos/copilot-sdk/troubleshooting","title":"Troubleshooting"},{"href":"/en/copilot/how-tos/copilot-sdk/troubleshooting/compatibility","title":"Compatibility"}],"documentType":"article"},"body":"# SDK and CLI compatibility\n\nThis document outlines which Copilot CLI features are available through the SDK and which are CLI-only.\n\n\n\n\n\n## Overview\n\nThe Copilot SDK communicates with the CLI via JSON-RPC protocol. Features must be explicitly exposed through this protocol to be available in the SDK. Many interactive CLI features are terminal-specific and not available programmatically.\n\n## Feature comparison\n\n### ✅ Available in SDK\n\n| Feature | SDK Method | Notes |\n| ------------------------------ | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------- |\n| **Session Management** | | |\n| Create session | `createSession()` | Full config support |\n| Resume session | `resumeSession()` | With infinite session workspaces |\n| Disconnect session | `disconnect()` | Release in-memory resources |\n| Destroy session *(deprecated)* | `destroy()` | Use `disconnect()` instead |\n| Delete session | `deleteSession()` | Remove from storage |\n| List sessions | `listSessions()` | All stored sessions |\n| Get last session | `getLastSessionId()` | For quick resume |\n| Get foreground session | `getForegroundSessionId()` | Multi-session coordination |\n| Set foreground session | `setForegroundSessionId()` | Multi-session coordination |\n| **Messaging** | | |\n| Send message | `send()` | With attachments |\n| Send and wait | `sendAndWait()` | Blocks until complete |\n| Steering (immediate mode) | `send({ mode: \"immediate\" })` | Inject mid-turn without aborting |\n| Queueing (enqueue mode) | `send({ mode: \"enqueue\" })` | Buffer for sequential processing (default) |\n| File attachments | `send({ attachments: [{ type: \"file\", path }] })` | Images auto-encoded and resized |\n| Directory attachments | `send({ attachments: [{ type: \"directory\", path }] })` | Attach directory context |\n| Get history | `getEvents()` | All session events |\n| Abort | `abort()` | Cancel in-flight request |\n| **Tools** | | |\n| Register custom tools | `registerTools()` | Full JSON Schema support |\n| Tool permission control | `onPreToolUse` hook | Allow/deny/ask |\n| Tool result modification | `onPostToolUse` hook | Transform results |\n| Available/excluded tools | `availableTools`, `excludedTools` config | Filter tools |\n| **Models** | | |\n| List models | `listModels()` | With capabilities, billing, policy |\n| Set model (at creation) | `model` in session config | Per-session |\n| Switch model (mid-session) | `session.setModel()` | Also via `session.rpc.model.switchTo()` |\n| Get current model | `session.rpc.model.getCurrent()` | Query active model |\n| Reasoning effort | `reasoningEffort` config | For supported models |\n| **Agent Mode** | | |\n| Get current mode | `session.rpc.mode.get()` | Returns current mode |\n| Set mode | `session.rpc.mode.set()` | Switch between modes |\n| **Plan Management** | | |\n| Read plan | `session.rpc.plan.read()` | Get plan.md content and path |\n| Update plan | `session.rpc.plan.update()` | Write plan.md content |\n| Delete plan | `session.rpc.plan.delete()` | Remove plan.md |\n| **Workspace Files** | | |\n| List workspace files | `session.rpc.workspace.listFiles()` | Files in session workspace |\n| Read workspace file | `session.rpc.workspace.readFile()` | Read file content |\n| Create workspace file | `session.rpc.workspace.createFile()` | Create file in workspace |\n| **Authentication** | | |\n| Get auth status | `getAuthStatus()` | Check login state |\n| Use token | `gitHubToken` option | Programmatic auth |\n| **Connectivity** | | |\n| Ping | `client.ping()` | Health check with server timestamp |\n| Get server status | `client.getStatus()` | Protocol version and server info |\n| **MCP Servers** | | |\n| Local/stdio servers | `mcpServers` config | Spawn processes |\n| Remote HTTP/SSE | `mcpServers` config | Connect to services |\n| **Hooks** | | |\n| Pre-tool use | `onPreToolUse` | Permission, modify args |\n| Post-tool use (success) | `onPostToolUse` | Modify results |\n| Post-tool use (failure) | `onPostToolUseFailure` | Observe failed tool calls, inject retry guidance |\n| User prompt | `onUserPromptSubmitted` | Modify prompts |\n| Session start/end | `onSessionStart`, `onSessionEnd` | Lifecycle with source/reason |\n| Error handling | `onErrorOccurred` | Custom handling |\n| **Events** | | |\n| All session events | `on()`, `once()` | 40+ event types |\n| Streaming | `streaming: true` | Delta events |\n| **Session Config** | | |\n| Custom agents | `customAgents` config | Define specialized agents |\n| System message | `systemMessage` config | Append or replace |\n| Custom provider | `provider` config | BYOK support |\n| Infinite sessions | `infiniteSessions` config | Auto-compaction |\n| Permission handler | `onPermissionRequest` | Approve/deny requests; optionally attach a `decisionContext` for auto-approval telemetry |\n| User input handler | `onUserInputRequest` | Handle ask\\_user |\n| Skills | `skillDirectories` config | Custom skills |\n| Disabled skills | `disabledSkills` config | Disable specific skills |\n| Config directory | `configDir` config | Override default config location |\n| Client name | `clientName` config | Identify app in User-Agent |\n| Working directory | `workingDirectory` config | Set session cwd |\n| Additional directories | `additionalDirectories` config | Grant session access beyond the working directory; re-supply on resume |\n| **Experimental** | | |\n| Agent management | `session.rpc.agent.*` | List, select, deselect, get current agent |\n| Fleet mode | `session.rpc.fleet.start()` | Parallel sub-agent execution; see [Fleet mode](/en/copilot/how-tos/copilot-sdk/features/fleet-mode) |\n| Manual compaction | `session.rpc.history.compact()` | Trigger compaction on demand |\n| Context clearing | `session.rpc.history.clearContext()` | Replace conversation context from a terminal tool |\n| History truncation | `session.rpc.history.truncate()` | Remove events from a point onward |\n| Session forking | `server.rpc.sessions.fork()` | Fork a session at a point in history |\n\n### ❌ Not available in SDK (CLI-only)\n\n| Feature | CLI Command/Option | Reason |\n| ----------------------------- | ------------------------------------- | ------------------------------------------------------ |\n| **Session Export** | | |\n| Export to file | `--share`, `/share` | Not in protocol |\n| Export to gist | `--share-gist`, `/share gist` | Not in protocol |\n| **Interactive UI** | | |\n| Slash commands | `/help`, `/clear`, `/exit`, etc. | TUI-only |\n| Agent picker dialog | `/agent` | Interactive UI |\n| Diff mode dialog | `/diff` | Interactive UI |\n| Feedback dialog | `/feedback` | Interactive UI |\n| Theme picker | `/theme` | Terminal UI |\n| Model picker | `/model` | Interactive UI (use SDK `setModel()` instead) |\n| Copy to clipboard | `/copy` | Terminal-specific |\n| Context management | `/context` | Interactive UI |\n| **Research & History** | | |\n| Deep research | `/research` | TUI workflow with web search |\n| Session history tools | `/chronicle` | Standup, tips, improve, reindex |\n| **Terminal Features** | | |\n| Color output | `--no-color` | Terminal-specific |\n| Screen reader mode | `--screen-reader` | Accessibility |\n| Rich diff rendering | `--plain-diff` | Terminal rendering |\n| Startup banner | `--banner` | Visual element |\n| Streamer mode | `/streamer-mode` | TUI display mode |\n| Alternate screen buffer | `--alt-screen`, `--no-alt-screen` | Terminal rendering |\n| Mouse support | `--mouse`, `--no-mouse` | Terminal input |\n| **Path/Permission Shortcuts** | | |\n| Allow all paths | `--allow-all-paths` | Use permission handler |\n| Allow all URLs | `--allow-all-urls` | Use permission handler |\n| Allow all permissions | `--yolo`, `--allow-all`, `/allow-all` | Use permission handler |\n| Granular tool permissions | `--allow-tool`, `--deny-tool` | Use `onPreToolUse` hook |\n| URL access control | `--allow-url`, `--deny-url` | Use permission handler |\n| Reset allowed tools | `/reset-allowed-tools` | TUI command |\n| **Directory Management** | | |\n| Add directory | `/add-dir`, `--add-dir` | Configure in session |\n| List directories | `/list-dirs` | TUI command |\n| Change directory | `/cwd` | TUI command |\n| **Plugin/MCP Management** | | |\n| Plugin commands | `/plugin` | Interactive management |\n| MCP server management | `/mcp` | Interactive UI |\n| **Account Management** | | |\n| Login flow | `/login`, `copilot auth login` | OAuth device flow |\n| Logout | `/logout`, `copilot auth logout` | Direct CLI |\n| User info | `/user` | TUI command |\n| **Session Operations** | | |\n| Clear conversation | `/clear` | TUI-only |\n| Plan view | `/plan` | TUI-only (use SDK `session.rpc.plan.*` instead) |\n| Session management | `/session`, `/resume`, `/rename` | TUI workflow |\n| Fleet mode (interactive) | `/fleet` | TUI-only (use SDK `session.rpc.fleet.start()` instead) |\n| **Skills Management** | | |\n| Manage skills | `/skills` | Interactive UI |\n| **Task Management** | | |\n| View background tasks | `/tasks` | TUI command |\n| **Usage & Stats** | | |\n| Token usage | `/usage` | Subscribe to usage events |\n| **Code Review** | | |\n| Review changes | `/review` | TUI command |\n| **Delegation** | | |\n| Delegate to PR | `/delegate` | TUI workflow |\n| **Terminal Setup** | | |\n| Shell integration | `/terminal-setup` | Shell-specific |\n| **Development** | | |\n| Toggle experimental | `/experimental`, `--experimental` | Runtime flag |\n| Custom instructions control | `--no-custom-instructions` | CLI flag |\n| Diagnose session | `/diagnose` | TUI command |\n| View/manage instructions | `/instructions` | TUI command |\n| Collect debug logs | `/collect-debug-logs` | Diagnostic tool |\n| Reindex workspace | `/reindex` | TUI command |\n| IDE integration | `/ide` | IDE-specific workflow |\n| **Non-interactive Mode** | | |\n| Prompt mode | `-p`, `--prompt` | Single-shot execution |\n| Interactive prompt | `-i`, `--interactive` | Auto-execute then interactive |\n| Silent output | `-s`, `--silent` | Script-friendly |\n| Continue session | `--continue` | Resume most recent |\n| Agent selection | `--agent ` | CLI flag |\n\n## Workarounds\n\n### Fleet mode\n\nFleet mode is available through `session.rpc.fleet.start()` for SDK applications that want the runtime to dispatch parallel sub-agents for a larger objective. Use it when independent subtasks can run concurrently and then be summarized by the main session. For a full guide, see [Fleet mode](/en/copilot/how-tos/copilot-sdk/features/fleet-mode).\n\n### Session export\n\nThe `--share` option is not available via SDK. Workarounds:\n\n1. **Collect events manually** - Subscribe to session events and build your own export:\n\n ```typescript\n const events: SessionEvent[] = [];\n session.on((event) => events.push(event));\n // ... after conversation ...\n const messages = await session.getEvents();\n // Format as markdown yourself\n ```\n\n2. **Use CLI directly for export** - Run the CLI with `--share` for one-off exports.\n\n### Permission control\n\nThe SDK uses a **deny-by-default** permission model. All permission requests (file writes, shell commands, URL fetches, etc.) are denied unless your app provides an `onPermissionRequest` handler.\n\nInstead of `--allow-all-paths` or `--yolo`, use the permission handler:\n\n```typescript\nconst session = await client.createSession({\n onPermissionRequest: approveAll,\n});\n```\n\n### Token usage tracking\n\nInstead of `/usage`, subscribe to usage events:\n\n```typescript\nsession.on(\"assistant.usage\", (event) => {\n console.log(\"Tokens used:\", {\n input: event.data.inputTokens,\n output: event.data.outputTokens,\n });\n});\n```\n\n### Context compaction\n\nInstead of `/compact`, configure automatic compaction or trigger it manually:\n\n```typescript\n// Automatic compaction via config\nconst session = await client.createSession({\n infiniteSessions: {\n enabled: true,\n backgroundCompactionThreshold: 0.80, // Start background compaction at 80% context utilization\n bufferExhaustionThreshold: 0.95, // Block and compact at 95% context utilization\n },\n});\n\n// Manual compaction (experimental)\nconst result = await session.rpc.history.compact();\nconsole.log(`Removed ${result.tokensRemoved} tokens, ${result.messagesRemoved} messages`);\n```\n\n> \\[!NOTE]\n> Thresholds are context utilization ratios (0.0-1.0), not absolute token counts.\n\n### Plan management\n\nRead and write session plans programmatically:\n\n```typescript\n// Read the current plan\nconst plan = await session.rpc.plan.read();\nif (plan.exists) {\n console.log(plan.content);\n}\n\n// Update the plan\nawait session.rpc.plan.update({ content: \"# My Plan\\n- Step 1\\n- Step 2\" });\n\n// Delete the plan\nawait session.rpc.plan.delete();\n```\n\n### Message steering\n\nInject a message into the current LLM turn without aborting:\n\n```typescript\n// Steer the agent mid-turn\nawait session.send({ prompt: \"Focus on error handling first\", mode: \"immediate\" });\n\n// Default: enqueue for next turn\nawait session.send({ prompt: \"Next, add tests\" });\n```\n\n## Protocol limitations\n\nThe SDK can only access features exposed through the CLI's JSON-RPC protocol. If you need a CLI feature that's not available:\n\n1. **Check for alternatives** - Many features have SDK equivalents (see workarounds above)\n2. **Use the CLI directly** - For one-off operations, invoke the CLI\n3. **Request the feature** - Open an issue to request protocol support\n\n## Version compatibility\n\n| SDK Protocol Range | CLI Protocol Version | Compatibility |\n| ------------------ | -------------------- | ------------------------------------ |\n| v2–v3 | v3 | Full support |\n| v2–v3 | v2 | Supported with automatic v2 adapters |\n\nThe SDK negotiates protocol versions with the CLI at startup. The SDK supports protocol versions 2 through 3. When connecting to a v2 CLI server, the SDK automatically adapts `tool.call` and `permission.request` messages to the v3 event model—no code changes required.\n\nCheck versions at runtime:\n\n```typescript\nconst status = await client.getStatus();\nconsole.log(\"Protocol version:\", status.protocolVersion);\n```\n\n## See also\n\n* [Build your first Copilot-powered app](/en/copilot/how-tos/copilot-sdk/getting-started)\n* [Session hooks](/en/copilot/how-tos/copilot-sdk/hooks/hooks-overview)\n* [Using MCP servers with the GitHub Copilot SDK](/en/copilot/how-tos/copilot-sdk/features/mcp)\n* [Debugging guide](/en/copilot/how-tos/copilot-sdk/troubleshooting/debugging)"}