CLI flags

Complete reference for all OpenCode command-line flags

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: -d

When 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: -c

Use 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: -p

This 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: -f

Supported formats:

Format	Description	Example
text	Plain text output (default)	The answer is...
json	Response 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

Text format

$ 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: -q

By 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:

Interactive with debug

# 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.