Crate claude_cli_sdk 

claude-cli-sdk

Rust SDK for programmatic interaction with the Claude Code CLI.

This crate provides strongly-typed, async-first access to Claude Code sessions via the CLI’s NDJSON stdio protocol.

Platform support

This SDK supports macOS, Linux, and Windows.

Quick start

use claude_cli_sdk::{query, ClientConfig};

#[tokio::main]
async fn main() -> claude_cli_sdk::Result<()> {
    let config = ClientConfig::builder()
        .prompt("List files in /tmp")
        .build();
    let messages = query(config).await?;
    for msg in &messages {
        if let Some(text) = msg.assistant_text() {
            println!("{text}");
        }
    }
    Ok(())
}

Timeouts

All timeouts are configurable via ClientConfig:

Timeout	Default	Purpose
connect_timeout	30s	Deadline for process spawn + init message
close_timeout	10s	Deadline for graceful shutdown; kills on expiry
read_timeout	None	Per-message recv deadline (detects hung processes)
default_hook_timeout	30s	Fallback when HookMatcher::timeout is None
version_check_timeout	5s	Deadline for --version check

Set any Option<Duration> to None to wait indefinitely.

Feature flags

Feature	Description
testing	Enables testing utilities (e.g., MockTransport)
efficiency	Reserved for future throughput optimisations
integration	Enables integration-test helpers (requires a live CLI)

Re-exports

pub use client::Client;

pub use config::ClientConfig;

pub use config::PermissionMode;

pub use config::SystemPrompt;

pub use errors::Error;

pub use errors::Result;

pub use types::content::ALLOWED_IMAGE_MIME_TYPES;

pub use types::content::Base64ImageSource;

pub use types::content::ContentBlock;

pub use types::content::ImageBlock;

pub use types::content::ImageSource;

pub use types::content::MAX_IMAGE_BASE64_BYTES;

pub use types::content::TextBlock;

pub use types::content::ThinkingBlock;

pub use types::content::ToolResultBlock;

pub use types::content::ToolResultContent;

pub use types::content::ToolUseBlock;

pub use types::content::UrlImageSource;

pub use types::content::UserContent;

pub use types::messages::AssistantMessage;

pub use types::messages::AssistantMessageInner;

pub use types::messages::McpServerStatus;

pub use types::messages::Message;

pub use types::messages::ResultMessage;

pub use types::messages::SessionInfo;

pub use types::messages::StreamEvent;

pub use types::messages::SystemMessage;

pub use types::messages::Usage;

pub use types::messages::UserMessage;

pub use types::messages::UserMessageInner;

pub use permissions::CanUseToolCallback;

pub use permissions::PermissionContext;

pub use permissions::PermissionDecision;

pub use hooks::HookCallback;

pub use hooks::HookContext;

pub use hooks::HookDecision;

pub use hooks::HookEvent;

pub use hooks::HookInput;

pub use hooks::HookMatcher;

pub use hooks::HookOutput;

pub use mcp::McpServerConfig;

pub use mcp::McpServers;

pub use discovery::check_cli_version;

pub use discovery::find_cli;

pub use transport::Transport;

pub use callback::MessageCallback;

Modules

callback

Message callback — a simple observe/filter hook for SDK consumers.

client

The core Client struct — multi-turn, bidirectional Claude Code sessions.

config

Client configuration — ClientConfig with typed builder pattern.

discovery

CLI discovery — locating the Claude Code binary on the system.

errors

Error types for the claude-cli-sdk.

hooks

Hook system for intercepting agent lifecycle events.

mcp

MCP (Model Context Protocol) server configuration types.

permissions

Permission types and the can_use_tool callback pattern.

transport

Transport layer — spawning and communicating with the Claude CLI.

types

Type definitions for the claude-cli-sdk.

Structs

CancellationToken

A token which can be used to signal a cancellation request to one or more tasks.

Functions

query

Run a one-shot query against Claude Code and collect all response messages.

query_stream

Run a streaming query against Claude Code, yielding messages as they arrive.

query_stream_with_content

Run a streaming multi-modal query, yielding messages as they arrive.

query_with_content

Run a one-shot multi-modal query and collect all response messages.