Skip to main content
OpenCode supports various command-line flags to customize its behavior. All flags can be used in both interactive and non-interactive modes unless otherwise noted.

​
Global flags

These flags are available for all OpenCode commands.
​
--help
flag
default:"false"
Display help information about OpenCode and its usage.Short form: -h
opencode --help
opencode -h
​
--version
flag
default:"false"
Print the current version of OpenCode and exit.Short form: -v
opencode --version
opencode -v
​
--debug
flag
default:"false"
Enable debug mode with verbose logging output. Useful for troubleshooting issues or understanding OpenCode’s internal operations.Short form: -dWhen enabled:
  • Log level is set to debug
  • Detailed information about operations is displayed
  • Helpful for debugging configuration or integration issues
opencode --debug
opencode -d
​
--cwd
string
default:"current directory"
Set the current working directory for OpenCode. The application will change to this directory before starting and use it as the root for all file operations.Short form: -cUse cases:
  • Work with a specific project directory
  • Run OpenCode from anywhere while targeting a specific location
  • Useful in scripts where the working directory may vary
opencode --cwd /path/to/project
opencode -c ~/my-project

​
Non-interactive mode flags

These flags control OpenCode’s behavior in non-interactive mode.
​
--prompt
string
default:""
Run a single prompt in non-interactive mode. When this flag is provided, OpenCode:
  • Processes the prompt immediately
  • Prints the AI response to stdout
  • Exits after completion
  • Auto-approves all permissions for the session
  • Does not launch the TUI
Short form: -pThis mode is ideal for:
  • Scripting and automation
  • Quick queries without launching the full interface
  • CI/CD pipelines
  • Testing prompts
opencode --prompt "Explain the use of context in Go"
opencode -p "Review the code in main.go"
Multi-line prompts can be provided using shell quoting:
opencode -p 'Review this code:
- Check for bugs
- Suggest improvements
- Look for security issues'
​
--output-format
string
default:"text"
Specify the output format for non-interactive mode. Only applies when used with --prompt.Short form: -fSupported formats:
FormatDescriptionExample
textPlain text output (default)The answer is...
jsonResponse wrapped in JSON object{"response": "The answer is..."}
The JSON format is useful for:
  • Parsing responses programmatically
  • Integration with other tools
  • Structured data processing
  • API-like usage
# Text output (default)
opencode -p "Explain context in Go" -f text

# JSON output
opencode -p "Explain context in Go" -f json

$ opencode -p "What is Go?" -f text
Go is a statically typed, compiled programming language designed at Google...
​
--quiet
flag
default:"false"
Hide the spinner animation in non-interactive mode. Only applies when used with --prompt.Short form: -qBy default, OpenCode displays a spinner while processing your prompt. Use this flag to suppress the spinner when:
  • Running from scripts
  • Piping output to other commands
  • Using in automated workflows
  • Logging output to files
  • The spinner interferes with other terminal output
# With spinner (default)
opencode -p "Explain Go"

# Without spinner
opencode -p "Explain Go" --quiet
opencode -p "Explain Go" -q
Combine with --output-format json for clean, parseable output:
opencode -p "List Go features" -f json -q | jq '.response'

​
Flag combinations

Flags can be combined to achieve different behaviors: 
# Launch TUI with debug logging
opencode -d

​
Flag precedence

When multiple configuration sources are present, OpenCode follows this precedence order:
  1. Command-line flags (highest priority)
  2. Environment variables
  3. Local config file (.opencode.json in working directory)
  4. Global config file (~/.opencode.json or ~/.config/opencode/.opencode.json)
  5. Default values (lowest priority)
For example, if debug is set in both the config file and via the -d flag, the flag takes precedence.

​
Boolean flags

Boolean flags like --debug, --quiet, and --help can be specified in multiple ways: 
# These are equivalent
opencode --debug
opencode --debug=true
opencode -d

# Explicitly disable (rarely needed)
opencode --debug=false

​
Common patterns

​
Development workflow

# Start debugging in a project
opencode -d -c ~/my-project

​
Scripting

#!/bin/bash
# Script to get code review

project_dir="$1"
file_path="$2"

response=$(opencode -c "$project_dir" \
  -p "Review the code in $file_path for potential issues" \
  -f json -q)

echo "$response" | jq -r '.response'

​
CI/CD integration

# Use in GitHub Actions or other CI
opencode -p "Analyze test coverage" -f json -q > report.json

​
Quick queries

# Fast answers without launching TUI
alias ask='opencode -p'
ask "How do I use channels in Go?"

​
Tips

Use short forms for faster typing: -d instead of --debug, -p instead of --prompt, etc.
Combine with shell features: Use command substitution, pipes, and redirection:
opencode -p "$(cat prompt.txt)" -f json | jq
The --output-format and --quiet flags only apply in non-interactive mode (when using --prompt). They are ignored in interactive mode.

Build docs developers (and LLMs) love

Get started for freeTalk to us