Crate claude_wrapper 

A type-safe Claude Code CLI wrapper for Rust.

claude-wrapper provides a builder-pattern interface for invoking the claude CLI programmatically. It follows the same design philosophy as docker-wrapper and terraform-wrapper: each CLI subcommand is a builder struct that produces typed output.

Quick Start

use claude_wrapper::{Claude, ClaudeCommand, QueryCommand, OutputFormat};

let claude = Claude::builder().build()?;

// Simple oneshot query
let output = QueryCommand::new("explain this error: file not found")
    .model("sonnet")
    .output_format(OutputFormat::Json)
    .execute(&claude)
    .await?;

println!("{}", output.stdout);

Two-Layer Builder

The Claude client holds shared config (binary path, env vars, timeout). Command builders hold per-invocation options and call execute(&claude).

use claude_wrapper::{Claude, ClaudeCommand, QueryCommand, PermissionMode, Effort};

// Configure once, reuse across commands
let claude = Claude::builder()
    .env("AWS_REGION", "us-west-2")
    .timeout_secs(300)
    .build()?;

// Each command is a separate builder
let output = QueryCommand::new("review the code in src/main.rs")
    .model("opus")
    .system_prompt("You are a senior Rust developer")
    .permission_mode(PermissionMode::Plan)
    .effort(Effort::High)
    .max_turns(5)
    .no_session_persistence()
    .execute(&claude)
    .await?;

JSON Output Parsing

Use execute_json() to get structured results:

use claude_wrapper::{Claude, QueryCommand};

let claude = Claude::builder().build()?;
let result = QueryCommand::new("what is 2+2?")
    .execute_json(&claude)
    .await?;

println!("answer: {}", result.result);
println!("cost: ${:.4}", result.cost_usd.unwrap_or(0.0));
println!("session: {}", result.session_id);

MCP Config Generation

Generate .mcp.json files for use with --mcp-config:

use claude_wrapper::{Claude, ClaudeCommand, McpConfigBuilder, QueryCommand};

// Build a config file with multiple servers
let config_path = McpConfigBuilder::new()
    .http_server("my-hub", "http://127.0.0.1:9090")
    .stdio_server("my-tool", "npx", ["my-mcp-server"])
    .stdio_server_with_env(
        "secure-tool", "node", ["server.js"],
        [("API_KEY", "secret")],
    )
    .write_to("/tmp/my-project/.mcp.json")?;

// Use it in a query
let claude = Claude::builder().build()?;
let output = QueryCommand::new("list available tools")
    .mcp_config("/tmp/my-project/.mcp.json")
    .execute(&claude)
    .await?;

Working with Multiple Directories

Clone the client with a different working directory:

use claude_wrapper::{Claude, ClaudeCommand, QueryCommand};

let claude = Claude::builder().build()?;

for project in &["/srv/project-a", "/srv/project-b"] {
    let local = claude.with_working_dir(project);
    QueryCommand::new("summarize this project")
        .no_session_persistence()
        .execute(&local)
        .await?;
}

Streaming

Process NDJSON events in real time:

use claude_wrapper::{Claude, QueryCommand, OutputFormat};
use claude_wrapper::streaming::{StreamEvent, stream_query};

let claude = Claude::builder().build()?;
let cmd = QueryCommand::new("explain quicksort")
    .output_format(OutputFormat::StreamJson);

let output = stream_query(&claude, &cmd, |event: StreamEvent| {
    if event.is_result() {
        println!("Result: {}", event.result_text().unwrap_or(""));
    }
}).await?;

Escape Hatch

For subcommands or flags not yet covered by the typed API:

use claude_wrapper::{Claude, ClaudeCommand, RawCommand};

let claude = Claude::builder().build()?;
let output = RawCommand::new("some-future-command")
    .arg("--new-flag")
    .arg("value")
    .execute(&claude)
    .await?;

Re-exports

pub use command::ClaudeCommand;

pub use command::agents::AgentsCommand;

pub use command::auth::AuthStatusCommand;

pub use command::doctor::DoctorCommand;

pub use command::marketplace::MarketplaceAddCommand;

pub use command::marketplace::MarketplaceListCommand;

pub use command::marketplace::MarketplaceRemoveCommand;

pub use command::marketplace::MarketplaceUpdateCommand;

pub use command::mcp::McpAddCommand;

pub use command::mcp::McpAddFromDesktopCommand;

pub use command::mcp::McpAddJsonCommand;

pub use command::mcp::McpGetCommand;

pub use command::mcp::McpListCommand;

pub use command::mcp::McpRemoveCommand;

pub use command::mcp::McpResetProjectChoicesCommand;

pub use command::plugin::PluginDisableCommand;

pub use command::plugin::PluginEnableCommand;

pub use command::plugin::PluginInstallCommand;

pub use command::plugin::PluginListCommand;

pub use command::plugin::PluginUninstallCommand;

pub use command::plugin::PluginUpdateCommand;

pub use command::plugin::PluginValidateCommand;

pub use command::query::QueryCommand;

pub use command::raw::RawCommand;

pub use command::version::VersionCommand;

pub use error::Error;

pub use error::Result;

pub use exec::CommandOutput;

pub use mcp_config::TempMcpConfig;

pub use mcp_config::McpConfigBuilder;

pub use mcp_config::McpServerConfig;

pub use retry::BackoffStrategy;

pub use retry::RetryPolicy;

pub use session::Session;

pub use session::SessionQuery;

pub use version::CliVersion;

pub use version::VersionParseError;

pub use types::*;

Modules

command

error

exec

mcp_config

retry

session

Type-safe session management for multi-turn conversations.

streaming

types

version

Structs

Claude

The Claude CLI client. Holds shared configuration applied to all commands.

ClaudeBuilder

Builder for creating a Claude client.