Starting a non-interactive session
Non-interactive sessions provide a method to use Bob Shell directly from the command line without entering an interactive session. Use for automation, scripting, and batch processing tasks.
Starting a non-interactive session
Use the bob run subcommand to run Bob Shell non-interactively from the command line.
Syntax
bob run [options] [prompt...]You can also pipe a prompt through stdin:
echo "Explain this project" | bob runOptions
| Option | Description |
|---|---|
--format <format> | Output format: pretty (default), json, or stream-json |
--mode <mode> | Starting mode (for example, agent, plan, ask) |
--max-cost <bobcoins> | Maximum spend in Bobcoins before the session stops |
--max-turns <n> | Maximum number of agentic turns before the session stops |
--disable-mcp | Disable all MCP servers for this session |
--disable-subagents | Disable subagent spawning for this session |
--disable-tool-groups <groups> | Disable specific tool groups (comma-separated, for example execute,mcp) |
--workspace <path> | Override the workspace root directory |
--log-level <level> | Log verbosity: error, warn, info, debug, or trace |
--list-tasks | List available tasks for the workspace and exit |
--limit <n> | Maximum number of tasks to display with --list-tasks |
--resume <task-id> | Resume a previous task by task ID |
--resume latest | Resume the most recent task |
--team-id <id> | Run under a specific team context (required when using an API key of type general) |
--trust | Mark the current folder as trusted |
--accept-license | Accept the IBM license agreement and continue without prompting |
Basic usage
Run a prompt directly
bob run "Explain this project"Pipe content as input
You can pipe text content to Bob Shell:
cat buildError.txt | bob run "Explain this build error"Save results to a file
Redirect the output to save results:
bob run "Review @bigFile.java" > review.mdReference project files
Use the @ symbol to reference files in your project:
bob run "Summarize the functionality in @src/main.js"Set cost and turn limits
bob run --max-cost 0.50 --max-turns 10 "Refactor @app.js"Output formats
The --format option controls how bob run writes its output. Use this option when capturing output for scripts or CI pipelines.
pretty (default)
Human-readable text output suitable for terminal display.
json
Emits a single JSON object after the session completes. Use this format to capture the full result for programmatic processing.
Schema:
| Field | Type | Description |
|---|---|---|
type | string | Always "result" |
timestamp | string | ISO 8601 (date-time standard) completion timestamp |
status | string | "success" or "error" |
stats | object | Session statistics — see fields below |
stats.task_id | string | Unique identifier for the completed task |
stats.total_tokens | number | Total tokens used |
stats.input_tokens | number | Input tokens used |
stats.output_tokens | number | Output tokens generated |
stats.cache_read_tokens | number | Tokens read from cache |
stats.cache_write_tokens | number | Tokens written to cache |
stats.cache_ratio | number | Cache hit ratio |
stats.duration_ms | number | Session duration in milliseconds |
stats.session_costs | number | Total cost for the session |
stats.tool_calls | number | Number of tool calls made |
last_message | string | Final assistant message |
Example:
bob run --format json "What is the entry point?" > result.jsonstream-json
Emits newline-delimited JSON (NDJSON) — one event object per line — as the session progresses. Use this format to stream output into a pipeline or process events in real time.
Event types:
| Event type | Key fields | Description |
|---|---|---|
message | role, content, isReasoning? | A user or assistant message |
tool_use | tool_name, tool_id, parameters | A tool call initiated by Bob |
tool_result | tool_id, status, output?, error? | The result returned by a tool |
error | severity, message | Cost/turn limit reached |
result | status, stats, last_message | Final summary emitted when the session ends |
Pipeline example:
bob run --format stream-json "Audit @src/" \
| grep '"type":"result"' \
| jq '.last_message'When running non-interactively with bob run, all tools are pre-approved. You are not prompted to approve tool calls during execution.
Session management
List recent tasks
bob run --list-tasks
bob run --list-tasks --limit 20Resume a previous session
bob run --resume <task-id> "Continue from where we left off"
bob run --resume latest "Keep going"When to use a non-interactive session
Non-interactive sessions work best for:
- Integrating Bob Shell into automation scripts
- Processing multiple files with a single command
- Getting quick insights without starting an interactive session
- Generating documentation from code
- CI/CD pipelines that need structured JSON output
Tips for effective use
- When processing large files or projects, be specific about which files to analyze.
- Use
--format jsonor--format stream-jsonfor reliable parsing in scripts. - Use
--max-costand--max-turnsto cap resource use in automated workflows. - For multi-line prompts, save them to a file and pipe to
bob run:
cat prompt.txt | bob runStarting an interactive session
Interactive sessions provide a conversational interface to Bob directly in your terminal, allowing real-time assistance with your development tasks.
Usage examples
Practical examples showing how to use Bob Shell for debugging, code improvement, file creation, documentation generation, and learning new concepts.