Skip to content

feat: add print mode flag to run command #533

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 11 commits into
base: dev
Choose a base branch
from

Conversation

monotykamary
Copy link
Contributor

@monotykamary monotykamary commented Jun 29, 2025

Summary

Adds a -p/--print flag to the run command that enables print mode with multiple output formats, solving the feature request in #278. The implementation uses dynamic data sources to accurately reflect the actual runtime configuration.

Changes

  • Print Mode Flag: Added -p/--print flag to run command
  • Output Formats: Support for text (default), json, and stream-json formats
  • Dynamic Data: Replaced hard-coded values with dynamic functions that reflect actual runtime state
  • Validation: stream-json format requires --verbose flag
  • Error Handling: Proper validation and error messages for edge cases
  • Backward Compatibility: Existing run command behavior is unchanged

Usage Examples

Text Output (Default)

$ opencode run -p "what is 2+2?"
4

JSON Output

$ opencode run --print --output-format json "what is 2+2?"
{"type":"result","subtype":"success","is_error":false,"duration_ms":2231,"duration_api_ms":2227,"num_turns":1,"result":"4","session_id":"ses_844cdda80ffeaNCnvw65ycUC6k","total_cost_usd":0,"usage":{"input_tokens":4,"cache_creation_input_tokens":0,"cache_read_input_tokens":11329,"output_tokens":5,"server_tool_use":{"web_search_requests":0},"service_tier":"standard"}}

Stream JSON Output (with verbose)

$ opencode run -p --output-format stream-json --verbose "what is 2+2?"
{"type":"system","subtype":"init","cwd":"/path/to/project","session_id":"ses_844cdd08affeNGo8Caw4wSm6Gw","tools":["Bash","Edit","WebFetch","Glob","Grep","LS","lsp_diagnostics","lsp_hover","Read","Edit","Write","TodoWrite","TodoRead"],"mcp_servers":[],"model":"anthropic-claude-sonnet-4-20250514","permissionMode":"default","apiKeySource":"ANTHROPIC_OAUTH"}
{"type":"assistant","message":{"id":"msg_7bb322f8c001n8Ehhz6liEBL9L","type":"message","role":"assistant","model":"anthropic-claude-sonnet-4-20250514","content":[{"type":"text","text":"4"}],"stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":4,"cache_creation_input_tokens":0,"cache_read_input_tokens":11329,"output_tokens":5,"service_tier":"standard"}},"parent_tool_use_id":null,"session_id":"ses_844cdd08affeNGo8Caw4wSm6Gw"}
{"type":"result","subtype":"success","is_error":false,"duration_ms":2508,"duration_api_ms":2504,"num_turns":1,"result":"4","session_id":"ses_844cdd08affeNGo8Caw4wSm6Gw","total_cost_usd":0,"usage":{"input_tokens":4,"cache_creation_input_tokens":0,"cache_read_input_tokens":11329,"output_tokens":5,"server_tool_use":{"web_search_requests":0},"service_tier":"standard"}}

Validation & Error Handling

Stream-JSON requires verbose flag

$ opencode run -p --output-format stream-json "test"
Error: When using --print, --output-format=stream-json requires --verbose

Empty message validation

$ opencode run -p
Error: No message provided

Features

  • Multiple Output Formats:

    • text: Simple text output (default)
    • json: Structured JSON with session metadata, timing, costs, and token usage
    • stream-json: Multiple JSON objects including system init, assistant message, and final result
  • Dynamic Runtime Data: System init output reflects actual configuration:

    • Tools: Shows available tools from Provider.tools() and active MCP tools
    • MCP Servers: Lists active MCP server names from MCP.clients()
    • API Key Source: Detects actual authentication method (API key, OAuth, env vars)
  • Comprehensive Metadata: JSON formats include:

    • Session ID and timing information
    • API call duration and total duration
    • Token usage (input, output, cache read/write)
    • Cost tracking
    • Error status and handling
  • Validation:

    • stream-json format requires --verbose flag
    • Empty message validation with appropriate error responses
    • Proper exit codes for error conditions
  • Backward Compatibility: Normal run command behavior is completely unchanged

Implementation Details

  • Integrated into existing RunCommand rather than creating a separate command
  • Reuses existing session management and chat infrastructure
  • Maintains all existing run command functionality (continue, session, share, model options)
  • Clean separation between print mode and interactive mode logic
  • Dynamic data functions that query actual runtime state instead of using hard-coded values
  • Proper TypeScript interfaces for all output formats

Testing

All output formats and validation scenarios have been tested:

  • ✅ Text output format
  • ✅ JSON output format with full metadata
  • ✅ Stream-JSON output format with verbose mode
  • ✅ Dynamic tools, MCP servers, and API key source detection
  • ✅ Validation error for stream-json without verbose
  • ✅ Empty message validation
  • ✅ Normal run command behavior unchanged
  • ✅ Error handling and exit codes

Closes #278

🤖 Generated with opencode

Add -p/--print flag to run command with multiple output formats:
- text (default): simple text output
- json: structured JSON with metadata
- stream-json: multiple JSON objects (requires --verbose)

Includes validation, error handling, and maintains backward compatibility
with existing run command behavior.

Closes sst#278

🤖 Generated with [opencode](https://opencode.ai)

Co-Authored-By: opencode <[email protected]>
@monotykamary
Copy link
Contributor Author

monotykamary and others added 5 commits June 29, 2025 19:34
Replace static hard-coded arrays and strings in print mode with dynamic functions that reflect actual runtime configuration for tools, MCP servers, and API key sources.

🤖 Generated with [opencode](https://opencode.ai)

Co-Authored-By: opencode <[email protected]>
- Use existing TOOL mapping for consistent display names instead of custom switch statement
- Add missing tools to TOOL mapping: webfetch, lsp_diagnostics, lsp_hover, patch
- Simplify getAvailableTools function to leverage existing infrastructure
- Ensure all tools have proper display names in print mode output

🤖 Generated with [opencode](https://opencode.ai)

Co-Authored-By: opencode <[email protected]>
Replace generic "Todo" display name with specific "TodoWrite" and "TodoRead"
to clearly differentiate between the two todo-related tools in print mode output.

🤖 Generated with [opencode](https://opencode.ai)

Co-Authored-By: opencode <[email protected]>
- Create STREAM_TOOL_NAMES mapping for descriptive tool names in stream-json
- Keep existing TOOL mapping short for interactive UI space constraints
- Distinguish TodoWrite/TodoRead in stream-json while keeping "Todo" for UI
- Shorten some UI tool names: WebFetch->Fetch, LSP tools->LSP
- Maintain "List" as original for both UI and stream-json consistency

🤖 Generated with [opencode](https://opencode.ai)

Co-Authored-By: opencode <[email protected]>
Fixes issue where -p flag output was missing trailing newline character,
causing shell to display % symbol indicating incomplete output.

🤖 Generated with [opencode](https://opencode.ai)

Co-Authored-By: opencode <[email protected]>
@rblalock
Copy link

rblalock commented Jul 2, 2025

+1 for this!

@thdxr thdxr self-assigned this Jul 2, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

claude -p --output-format json-like functionality
3 participants