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<I, T>(self, tools: I) -> Self

where I: IntoIterator<Item = T>, T: Into<ToolPattern>,

Add allowed tool patterns.

Accepts anything convertible into ToolPattern, including bare strings (e.g. "Bash", "Bash(git log:*)", "mcp__my-server__*") and values produced by ToolPattern’s constructors.

use claude_wrapper::{QueryCommand, ToolPattern};

let cmd = QueryCommand::new("hi")
    .allowed_tools(["Bash", "Read"]) // raw strings still work
    .allowed_tool(ToolPattern::tool_with_args("Bash", "git log:*"))
    .allowed_tool(ToolPattern::all("Write"));

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

Add a single allowed tool pattern.

pub fn disallowed_tools<I, T>(self, tools: I) -> Self

where I: IntoIterator<Item = T>, T: Into<ToolPattern>,

Add disallowed tool patterns.

pub fn disallowed_tool(self, tool: impl Into<ToolPattern>) -> Self

Add a single disallowed tool pattern.

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 worktree(self) -> Self

Create a new git worktree for this session, providing an isolated working directory.

pub fn brief(self) -> Self

Enable brief mode, which activates the SendUserMessage tool for agent-to-user communication.

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

Enable debug logging with an optional filter (e.g., “api,hooks”).

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

Write debug logs to the specified file path.

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

Beta feature headers for API key authentication.

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

Load plugins from the specified directory for this session.

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

Comma-separated list of setting sources to load (e.g., “user,project,local”).

pub fn tmux(self) -> Self

Create a tmux session for the worktree.

pub fn bare(self) -> Self

Run in minimal mode (--bare).

Skips hooks, LSP, plugin sync, attribution, auto-memory, background prefetches, keychain reads, and CLAUDE.md auto-discovery. Sets CLAUDE_CODE_SIMPLE=1 inside the child. Anthropic auth is restricted to ANTHROPIC_API_KEY or apiKeyHelper via --settings; OAuth and keychain are never read. Third-party providers (Bedrock/Vertex/Foundry) use their own credentials as normal.

Intended for headless/CI use where you want deterministic context: provide everything explicitly via --system-prompt, --append-system-prompt, --add-dir, --mcp-config, --settings, --agents, and --plugin-dir. Skills still resolve via explicit /skill-name references.

pub fn disable_slash_commands(self) -> Self

Disable all slash-command skills (--disable-slash-commands).

pub fn include_hook_events(self) -> Self

Include every hook lifecycle event in the stream-json output (--include-hook-events). Only meaningful with OutputFormat::StreamJson.

pub fn exclude_dynamic_system_prompt_sections(self) -> Self

Move per-machine sections (cwd, env info, memory paths, git status) out of the system prompt and into the first user message (--exclude-dynamic-system-prompt-sections). Improves cross-user prompt-cache reuse. Only applies with the default system prompt; ignored with --system-prompt.

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

Set a display name for this session (--name). Shown in the prompt box, /resume picker, and terminal title.

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

Resume a session linked to a PR by number or URL (--from-pr <value>).

This wrapper only supports the valued form; the CLI’s no-value mode opens an interactive picker and would hang a headless caller.

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.

pub fn execute_sync(&self, claude: &Claude) -> Result<CommandOutput>

Blocking analog of QueryCommand::execute that honours the configured RetryPolicy.

Overrides the blanket ClaudeCommandSyncExt::execute_sync impl so retries still fire on the sync path.

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

Blocking mirror of QueryCommand::execute_json.

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.