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

# Commands

> Complete command reference for OpenCode CLI

OpenCode provides a comprehensive command-line interface for terminal-based AI assistance. Below is the complete reference for all available commands and subcommands.

## Root command

```bash theme={null}
opencode [flags]
```

The root command launches OpenCode in interactive mode by default, providing a terminal user interface (TUI) for AI-assisted coding.

### Description

OpenCode is a powerful terminal-based AI assistant that helps with software development tasks. It provides an interactive chat interface with AI capabilities, code analysis, and LSP integration to assist developers in writing, debugging, and understanding code directly from the terminal.

### Examples

<CodeGroup>
  ```bash Interactive mode theme={null}
  # Run in interactive mode with TUI
  opencode
  ```

  ```bash Debug mode theme={null}
  # Run with debug logging enabled
  opencode -d
  ```

  ```bash Specific directory theme={null}
  # Run in a specific project directory
  opencode -c /path/to/project
  ```

  ```bash Combined flags theme={null}
  # Run with debug logging in a specific directory
  opencode -d -c /path/to/project
  ```

  ```bash Version theme={null}
  # Print version information
  opencode -v
  ```

  ```bash Non-interactive prompt theme={null}
  # Run a single prompt without launching the TUI
  opencode -p "Explain the use of context in Go"
  ```

  ```bash JSON output theme={null}
  # Run a prompt with JSON output format
  opencode -p "Explain the use of context in Go" -f json
  ```

  ```bash Quiet mode theme={null}
  # Run without the spinner animation (useful for scripts)
  opencode -p "Explain the use of context in Go" -q
  ```
</CodeGroup>

## Interactive mode

When launched without the `-p` flag, OpenCode starts in interactive mode with a full terminal user interface.

### Features

* **Interactive chat**: Chat with AI models in real-time
* **Session management**: Create, switch, and manage multiple conversation sessions
* **Tool integration**: AI can execute commands, search files, and modify code
* **File tracking**: Visualize file changes during sessions
* **External editor**: Open your preferred editor for composing messages
* **LSP integration**: Language server protocol support for code intelligence
* **Permission system**: Control what actions the AI can perform

### Keyboard shortcuts

See the [keyboard shortcuts documentation](/usage/keyboard-shortcuts) for a complete list of available shortcuts in interactive mode.

## Non-interactive mode

When you provide a prompt with the `-p` flag, OpenCode runs in non-interactive mode.

### Behavior

* Processes the prompt immediately
* Prints the AI response to standard output
* Exits after completion
* Auto-approves all permissions for the session
* No TUI is launched

### Use cases

* **Scripting**: Integrate OpenCode into shell scripts and automation
* **Quick queries**: Get fast answers without launching the full TUI
* **CI/CD pipelines**: Use AI assistance in automated workflows
* **Testing**: Automate testing of prompts and responses

### Output formats

Non-interactive mode supports multiple output formats:

| Format | Description                       |
| ------ | --------------------------------- |
| `text` | Plain text output (default)       |
| `json` | Response wrapped in a JSON object |

Use the `-f` or `--output-format` flag to specify the desired format.

### Spinner display

By default, a spinner animation displays while the AI processes your query. Use the `-q` or `--quiet` flag to disable the spinner, which is particularly useful when:

* Running OpenCode from scripts
* Piping output to other commands
* Using in automated workflows
* Logging output to files

## Built-in commands

OpenCode includes several built-in commands accessible via `Ctrl+K` in interactive mode:

<AccordionGroup>
  <Accordion title="Initialize project">
    Creates or updates the OpenCode.md memory file with project-specific information. This command helps the AI understand your project structure and context.
  </Accordion>

  <Accordion title="Compact session">
    Manually triggers summarization of the current session, creating a new session with the summary. Useful when you want to reduce context size while preserving important information.
  </Accordion>
</AccordionGroup>

## Custom commands

OpenCode supports user-defined custom commands stored as Markdown files. These allow you to create reusable prompts for common tasks.

### Command locations

**User commands** (prefixed with `user:`):

* `$XDG_CONFIG_HOME/opencode/commands/` (typically `~/.config/opencode/commands/`)
* `$HOME/.opencode/commands/`

**Project commands** (prefixed with `project:`):

* `<PROJECT_DIR>/.opencode/commands/`

### Creating custom commands

1. Create a `.md` file in one of the command directories
2. Add your prompt content to the file
3. Use named arguments with `$NAME` syntax for placeholders
4. Access via `Ctrl+K` in interactive mode

### Named arguments

Custom commands support named arguments using the format `$NAME` where NAME consists of uppercase letters, numbers, and underscores, and must start with a letter.

<CodeGroup>
  ```markdown Simple command theme={null}
  # Review Context

  RUN git ls-files
  READ README.md
  ```

  ```markdown Command with arguments theme={null}
  # Fetch Issue Context

  RUN gh issue view $ISSUE_NUMBER --json title,body,comments
  RUN git grep --author="$AUTHOR_NAME" -n .
  ```

  ```markdown Multiple uses of same argument theme={null}
  # Search and Replace

  RUN grep -R "$SEARCH_PATTERN" $DIRECTORY
  RUN sed -i 's/$SEARCH_PATTERN/$REPLACE_WITH/g' $DIRECTORY/*
  ```
</CodeGroup>

### Organizing commands

Organize commands in subdirectories for better structure:

```
~/.config/opencode/commands/
├── git/
│   ├── commit.md
│   └── review.md
├── testing/
│   ├── unit.md
│   └── integration.md
└── refactor/
    └── optimize.md
```

Subdirectories create nested command IDs:

* `user:git:commit`
* `user:git:review`
* `user:testing:unit`

## Exit codes

| Code | Description    |
| ---- | -------------- |
| 0    | Success        |
| 1    | Error occurred |

The command returns a non-zero exit code when an error occurs, making it suitable for use in scripts and automation workflows.