ralph ask Command

This document provides comprehensive documentation for the ralph ask command, which sends a single-shot prompt to Claude. Nothing is stored.

Code Locations

Component	File	Description
CLI args	`crates/ralph/src/cli/mod.rs`	AskArgs struct definition
Permission mode	`crates/ralph/src/invoke.rs`, `crates/ralph/src/config.rs`	resolve_permission_mode(), AppConfig::ask_permission_mode()
Shared engine	`crates/ralph/src/invoke.rs`	InvocationConfig, invoke(), command building
Prompt source	`crates/ralph/src/prompt_source.rs`	classify_prompt_source(), read_from_source()
Execution	`crates/ralph/src/main.rs`	execute_ask(), build_invocation_config(), resolve_ask_prompt()
Summary	`crates/ralph/src/startup/display.rs`	display_ask_summary()
Config	`crates/ralph/src/config.rs`	AppConfig with AskSection

The ralph ask command provides a streamlined interface for quick LLM interactions. ask sends a single prompt and displays the response. It keeps no session, history, or log on disk; each call is independent. Use ralph chat for a conversation that persists.

CLI Flags

Flag	Type	Default	Description
`[PROMPT]`	positional	stdin	The prompt to send (inline, file path, or `-` for stdin)
`--theme`	string	`base16-ocean.dark`	Syntax highlighting theme
`--no-background`	flag	false	Disable theme background colors
`--timeout`	u64	600	Subprocess timeout in seconds
`--verbose-tools`	string	none	Verbose output for tools (omit value for all, or specify names)
`--no-prompt`	flag	false	Suppress prompt display before execution
`--permission-mode`	string	`bypassPermissions`	Permission mode for tool execution

Verbose Tools Examples

ralph ask --verbose-tools 'prompt'       # Enable for all tools
ralph ask --verbose-tools=grep,bash 'prompt'  # Enable for specific tools

Prompt Resolution

The prompt can be provided from multiple sources:

Source	Example	Description
Positional argument	`ralph ask 'What is 2+2?'`	Inline prompt text
File path	`ralph ask /path/to/prompt.txt`	Read prompt from file (if path exists)
Stdin explicit	`ralph ask -`	Read from stdin (explicit)
Stdin piped	`echo 'prompt' \| ralph ask`	Read from stdin when piped (automatic)

Resolution Priority

If argument is -, read from stdin
If argument is a valid file path, read from file
If argument is any other string, use as inline prompt
If no argument and stdin is piped (non-terminal), read from stdin
If no argument and stdin is terminal, error (no prompt provided)

Permission Modes

The --permission-mode flag sets claude --permission-mode. ask has its own setting, default bypassPermissions: the user is present, watching, and can stop the run with Ctrl+C. Chat and its workers use [chat] permission_mode and RALPH_CHAT_PERMISSION_MODE, default auto, which do not change ask. Choices are claude’s: acceptEdits, auto, bypassPermissions, manual, dontAsk, plan (see claude --help).

ralph ask --permission-mode plan 'Analyze this code'

Configuration Precedence

CLI flag (--permission-mode)
Environment variable (RALPH_ASK_PERMISSION_MODE, ignored when empty)
[ask] permission_mode in ~/.config/ralph/config.toml
Default (bypassPermissions)

Config file example:

[ask]
permission_mode = "acceptEdits"

Theme Configuration

Theme settings follow this precedence:

CLI flag (--theme, --no-background)
Environment variable (RALPH_THEME, RALPH_NO_BACKGROUND)
Config file (if present)
Default: base16-ocean.dark

Output Patterns

Prompt Display

Before execution (unless --no-prompt):

╭─── Prompt ────────────────────────────────────────────────────╮
│ What is Rust?                                                 │
╰───────────────────────────────────────────────────────────────╯

Streaming Response

Response is streamed with syntax highlighting for code blocks.

Summary

After completion:

✓ Ask Complete

─── Metrics ───
Cost: $0.0234
Duration: 5.2s
Tokens: 1.2K input | 567 output

Examples

Basic Usage

# Simple question
ralph ask 'What is the capital of France?'

# Multi-line prompt from heredoc
ralph ask <<'EOF'
Review this function for potential improvements:

fn add(a: i32, b: i32) -> i32 {
    a + b
}
EOF

# Prompt from file
ralph ask /path/to/detailed-prompt.txt

Piping

# Pipe prompt from another command
cat requirements.txt | ralph ask 'Analyze these dependencies'

# Pipe through multiple tools
git diff | ralph ask 'Review this diff'

# Use with process substitution
ralph ask < <(echo "Combined prompt from $(pwd)")

Permission Control

# Read-only exploration
ralph ask --permission-mode plan 'What files are in src/?'

# Trusted editing
ralph ask --permission-mode acceptEdits 'Add error handling to main.rs'

# Full automation (default)
ralph ask 'Refactor the test suite'

Theme and Display

# Custom theme
ralph ask --theme 'Solarized (dark)' 'prompt'

# No background colors
ralph ask --no-background 'prompt'

# Hide prompt display
ralph ask --no-prompt 'prompt'

# Verbose tool output
ralph ask --verbose-tools=bash 'Run the tests'

ralph chat Command - Persistent chat with compressed memory

Keyboard shortcuts

ralph