Struct QueryCommand 

pub struct QueryCommand { /* private fields */ }

Builder for claude -p <prompt> (oneshot print-mode queries).

This is the primary command for programmatic use. It runs a single prompt through Claude and returns the result.

Example

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

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

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

Implementations

impl QueryCommand

pub fn new(prompt: impl Into<String>) -> Self

Create a new query command with the given prompt.

pub fn model(self, model: impl Into<String>) -> Self

Set the model to use (e.g. “sonnet”, “opus”, or a full model ID).

pub fn system_prompt(self, prompt: impl Into<String>) -> Self

Set a custom system prompt (replaces the default).

pub fn append_system_prompt(self, prompt: impl Into<String>) -> Self

Append to the default system prompt.

pub fn output_format(self, format: OutputFormat) -> Self

Set the output format.

pub fn max_budget_usd(self, budget: f64) -> Self

Set the maximum budget in USD.

pub fn permission_mode(self, mode: PermissionMode) -> Self

Set the permission mode.

pub fn allowed_tools( self, tools: impl IntoIterator<Item = impl Into<String>>, ) -> Self

Add allowed tools (e.g. “Bash”, “Read”, “mcp__my-server__*”).

pub fn allowed_tool(self, tool: impl Into<String>) -> Self

Add a single allowed tool.

pub fn disallowed_tools( self, tools: impl IntoIterator<Item = impl Into<String>>, ) -> Self

Add disallowed tools.

pub fn mcp_config(self, path: impl Into<String>) -> Self

Add an MCP config file path.

pub fn add_dir(self, dir: impl Into<String>) -> Self

Add an additional directory for tool access.

pub fn effort(self, effort: Effort) -> Self

Set the effort level.

pub fn max_turns(self, turns: u32) -> Self

Set the maximum number of turns.

pub fn json_schema(self, schema: impl Into<String>) -> Self

Set a JSON schema for structured output validation.

pub fn continue_session(self) -> Self

Continue the most recent conversation.

pub fn resume(self, session_id: impl Into<String>) -> Self

Resume a specific session by ID.

pub fn session_id(self, id: impl Into<String>) -> Self

Use a specific session ID.

pub fn fallback_model(self, model: impl Into<String>) -> Self

Set a fallback model for when the primary model is overloaded.

pub fn no_session_persistence(self) -> Self

Disable session persistence (sessions won’t be saved to disk).

pub fn dangerously_skip_permissions(self) -> Self

Bypass all permission checks. Only use in sandboxed environments.

pub fn agent(self, agent: impl Into<String>) -> Self

Set the agent for the session.

pub fn agents_json(self, json: impl Into<String>) -> Self

Set custom agents as a JSON object.

Example: {"reviewer": {"description": "Reviews code", "prompt": "You are a code reviewer"}}

pub fn tools(self, tools: impl IntoIterator<Item = impl Into<String>>) -> Self

Set the list of available built-in tools.

Use "" to disable all tools, "default" for all tools, or specific tool names like ["Bash", "Edit", "Read"]. This is different from allowed_tools which controls MCP tool permissions.

pub fn file(self, spec: impl Into<String>) -> Self

Add a file resource to download at startup.

Format: file_id:relative_path (e.g. file_abc:doc.txt).

pub fn include_partial_messages(self) -> Self

Include partial message chunks as they arrive.

Only works with --output-format stream-json.

pub fn input_format(self, format: InputFormat) -> Self

Set the input format.

pub fn strict_mcp_config(self) -> Self

Only use MCP servers from --mcp-config, ignoring all other MCP configurations.

pub fn settings(self, settings: impl Into<String>) -> Self

Path to a settings JSON file or a JSON string.

pub fn fork_session(self) -> Self

When resuming, create a new session ID instead of reusing the original.

pub fn retry(self, policy: RetryPolicy) -> Self

Set a per-command retry policy, overriding the client default.

Example

use claude_wrapper::{Claude, ClaudeCommand, QueryCommand, RetryPolicy};
use std::time::Duration;

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

let output = QueryCommand::new("explain quicksort")
    .retry(RetryPolicy::new()
        .max_attempts(5)
        .initial_backoff(Duration::from_secs(2))
        .exponential()
        .retry_on_timeout(true))
    .execute(&claude)
    .await?;

pub fn to_command_string(&self, claude: &Claude) -> String

Return the full command as a string that could be run in a shell.

Constructs a command string using the binary path from the Claude instance and the arguments from this query. Arguments containing spaces or special shell characters are shell-quoted to be safe for shell execution.

Example

use claude_wrapper::{Claude, QueryCommand};

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

let cmd = QueryCommand::new("explain quicksort")
    .model("sonnet");

let command_str = cmd.to_command_string(&claude);
println!("Would run: {}", command_str);

pub async fn execute_json(&self, claude: &Claude) -> Result<QueryResult>

Execute the query and parse the JSON result.

This is a convenience method that sets OutputFormat::Json and deserializes the response into a QueryResult.

Trait Implementations

impl ClaudeCommand for QueryCommand

type Output = CommandOutput

The typed result of executing this command.

fn args(&self) -> Vec<String>

Build the CLI argument list for this command.

async fn execute(&self, claude: &Claude) -> Result<CommandOutput>

Execute the command using the given claude client.

impl Clone for QueryCommand

fn clone(&self) -> QueryCommand

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for QueryCommand

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.