> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/opencode-ai/opencode/llms.txt
> Use this file to discover all available pages before exploring further.

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

<ParamField path="--help" type="flag" default="false">
  Display help information about OpenCode and its usage.

  **Short form:** `-h`

  ```bash theme={null}
  opencode --help
  opencode -h
  ```
</ParamField>

<ParamField path="--version" type="flag" default="false">
  Print the current version of OpenCode and exit.

  **Short form:** `-v`

  ```bash theme={null}
  opencode --version
  opencode -v
  ```
</ParamField>

<ParamField path="--debug" type="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

  ```bash theme={null}
  opencode --debug
  opencode -d
  ```
</ParamField>

<ParamField path="--cwd" type="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

  ```bash theme={null}
  opencode --cwd /path/to/project
  opencode -c ~/my-project
  ```
</ParamField>

## Non-interactive mode flags

These flags control OpenCode's behavior in non-interactive mode.

<ParamField path="--prompt" type="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

  ```bash theme={null}
  opencode --prompt "Explain the use of context in Go"
  opencode -p "Review the code in main.go"
  ```

  <Info>
    Multi-line prompts can be provided using shell quoting:

    ```bash theme={null}
    opencode -p 'Review this code:
    - Check for bugs
    - Suggest improvements
    - Look for security issues'
    ```
  </Info>
</ParamField>

<ParamField path="--output-format" type="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

  ```bash theme={null}
  # Text output (default)
  opencode -p "Explain context in Go" -f text

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

  <CodeGroup>
    ```text Text format theme={null}
    $ opencode -p "What is Go?" -f text
    Go is a statically typed, compiled programming language designed at Google...
    ```

    ```json JSON format theme={null}
    $ opencode -p "What is Go?" -f json
    {
      "response": "Go is a statically typed, compiled programming language designed at Google..."
    }
    ```
  </CodeGroup>
</ParamField>

<ParamField path="--quiet" type="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

  ```bash theme={null}
  # With spinner (default)
  opencode -p "Explain Go"

  # Without spinner
  opencode -p "Explain Go" --quiet
  opencode -p "Explain Go" -q
  ```

  <Tip>
    Combine with `--output-format json` for clean, parseable output:

    ```bash theme={null}
    opencode -p "List Go features" -f json -q | jq '.response'
    ```
  </Tip>
</ParamField>

## Flag combinations

Flags can be combined to achieve different behaviors:

<CodeGroup>
  ```bash Interactive with debug theme={null}
  # Launch TUI with debug logging
  opencode -d
  ```

  ```bash Interactive in specific directory theme={null}
  # Launch TUI in a specific project directory
  opencode -c /path/to/project
  ```

  ```bash Non-interactive basic theme={null}
  # Quick query without TUI
  opencode -p "Explain Docker"
  ```

  ```bash Non-interactive with format theme={null}
  # Query with JSON output
  opencode -p "List Python benefits" -f json
  ```

  ```bash Non-interactive quiet theme={null}
  # Query without spinner (script-friendly)
  opencode -p "What is Rust?" -q
  ```

  ```bash Non-interactive full theme={null}
  # Query with JSON output, no spinner
  opencode -p "Explain Kubernetes" -f json -q
  ```

  ```bash Debug in directory theme={null}
  # Debug mode in specific directory
  opencode -d -c ~/project
  ```

  ```bash Everything combined theme={null}
  # Non-interactive, specific directory, JSON output, quiet
  opencode -c /path/to/project -p "Review main.go" -f json -q
  ```
</CodeGroup>

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

```bash theme={null}
# These are equivalent
opencode --debug
opencode --debug=true
opencode -d

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

## Common patterns

### Development workflow

```bash theme={null}
# Start debugging in a project
opencode -d -c ~/my-project
```

### Scripting

```bash theme={null}
#!/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

```bash theme={null}
# Use in GitHub Actions or other CI
opencode -p "Analyze test coverage" -f json -q > report.json
```

### Quick queries

```bash theme={null}
# Fast answers without launching TUI
alias ask='opencode -p'
ask "How do I use channels in Go?"
```

## Tips

<Tip>
  **Use short forms for faster typing**: `-d` instead of `--debug`, `-p` instead of `--prompt`, etc.
</Tip>

<Tip>
  **Combine with shell features**: Use command substitution, pipes, and redirection:

  ```bash theme={null}
  opencode -p "$(cat prompt.txt)" -f json | jq
  ```
</Tip>

<Warning>
  The `--output-format` and `--quiet` flags only apply in non-interactive mode (when using `--prompt`). They are ignored in interactive mode.
</Warning>