mirror of
https://github.com/aljazceru/opencode.git
synced 2025-12-28 21:24:19 +01:00
docs: edit commands
This commit is contained in:
Jay V
@@ -3,7 +3,13 @@ title: Commands
|
||||
description: Create custom commands for repetitive tasks.
|
||||
---
|
||||
|
||||
Define custom commands to automate repetitive coding tasks.
|
||||
Custom commands let you specify a prompt you want to run when that command is executed in the TUI.
|
||||
|
||||
```bash frame="none"
|
||||
/my-command
|
||||
```
|
||||
|
||||
Custom commands are in addition to the built-in commands like `/init`, `/undo`, `/redo`, `/share`, `/help`. [Learn more](/docs/tui#commands).
|
||||
|
||||
---
|
||||
|
||||
@@ -34,12 +40,78 @@ Use the command by typing `/` followed by the command name.
|
||||
|
||||
---
|
||||
|
||||
## Use arguments
|
||||
## Configure
|
||||
|
||||
You can add custom commands through the opencode config or by creating markdown files in the `command/` directory.
|
||||
|
||||
---
|
||||
|
||||
### JSON
|
||||
|
||||
Use the `command` option in your opencode [config](/docs/config):
|
||||
|
||||
```json title="opencode.jsonc" {4-12}
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"command": {
|
||||
// This becomes the name of the command
|
||||
"test": {
|
||||
// This is the prompt that will be sent to the LLM
|
||||
"template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes.",
|
||||
// This is show as the description in the TUI
|
||||
"description": "Run tests with coverage",
|
||||
"agent": "build",
|
||||
"model": "anthropic/claude-3-5-sonnet-20241022"
|
||||
},
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Now you can run this command in the TUI:
|
||||
|
||||
```bash frame="none"
|
||||
/test
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Markdown
|
||||
|
||||
You can also define commands using markdown files. Place them in:
|
||||
|
||||
- Global: `~/.config/opencode/command/`
|
||||
- Per-project: `.opencode/command/`
|
||||
|
||||
```markdown title="~/.config/opencode/command/test.md"
|
||||
---
|
||||
description: Run tests with coverage
|
||||
agent: build
|
||||
model: anthropic/claude-3-5-sonnet-20241022
|
||||
---
|
||||
|
||||
Run the full test suite with coverage report and show any failures.
|
||||
Focus on the failing tests and suggest fixes.
|
||||
```
|
||||
|
||||
The markdown file name becomes the command name. For example, `test.md` lets
|
||||
you run:
|
||||
|
||||
```bash frame="none"
|
||||
/test
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Prompt config
|
||||
|
||||
The prompts for the custom commands support several special placeholders and syntax.
|
||||
|
||||
---
|
||||
|
||||
### Arguments
|
||||
|
||||
Pass arguments to commands using the `$ARGUMENTS` placeholder.
|
||||
|
||||
Create `.opencode/command/component.md`:
|
||||
|
||||
```md title=".opencode/command/component.md"
|
||||
---
|
||||
description: Create a new component
|
||||
@@ -52,16 +124,18 @@ Include proper typing and basic structure.
|
||||
Run the command with arguments:
|
||||
|
||||
```bash frame="none"
|
||||
"/component Button"
|
||||
/component Button
|
||||
```
|
||||
|
||||
And `$ARGUMENTS` will be replaced with `Button`.
|
||||
|
||||
---
|
||||
|
||||
## Inject shell output
|
||||
### Shell output
|
||||
|
||||
Use !`command` to inject shell command output into your prompt.
|
||||
Use _!`command`_ to inject [bash command](/docs/tui#bash-commands) output into your prompt.
|
||||
|
||||
Create `.opencode/command/analyze-coverage.md`:
|
||||
For example, to create a custom command that analyzes test coverage:
|
||||
|
||||
```md title=".opencode/command/analyze-coverage.md"
|
||||
---
|
||||
@@ -74,7 +148,7 @@ Here are the current test results:
|
||||
Based on these results, suggest improvements to increase coverage.
|
||||
```
|
||||
|
||||
Create `.opencode/command/review-changes.md`:
|
||||
Or to review recent changes:
|
||||
|
||||
```md title=".opencode/command/review-changes.md"
|
||||
---
|
||||
@@ -91,12 +165,10 @@ Commands run in your project's root directory and their output becomes part of t
|
||||
|
||||
---
|
||||
|
||||
## Reference files
|
||||
### File references
|
||||
|
||||
Include files in your command using `@` followed by the filename.
|
||||
|
||||
Create `.opencode/command/review-component.md`:
|
||||
|
||||
```md title=".opencode/command/review-component.md"
|
||||
---
|
||||
description: Review component
|
||||
@@ -110,47 +182,90 @@ The file content gets included in the prompt automatically.
|
||||
|
||||
---
|
||||
|
||||
## Command properties
|
||||
## Options
|
||||
|
||||
Configure commands with these optional frontmatter properties:
|
||||
Let's look at the configuration options in detail.
|
||||
|
||||
- **description**: Brief explanation of what the command does
|
||||
- **agent**: Agent to use (defaults to "build")
|
||||
- **model**: Specific model to use for this command
|
||||
|
||||
Create `.opencode/command/code-review.md`:
|
||||
|
||||
```md title=".opencode/command/code-review.md"
|
||||
---
|
||||
description: Code review assistant
|
||||
agent: build
|
||||
model: anthropic/claude-3-5-sonnet-20241022
|
||||
---
|
||||
|
||||
Review the code for best practices and suggest improvements.
|
||||
### Template
|
||||
|
||||
The `template` option defines the prompt that will be sent to the LLM when the command is executed.
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"command": {
|
||||
"test": {
|
||||
"template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes."
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Command directory
|
||||
|
||||
Store command files in these locations:
|
||||
|
||||
- `.opencode/command/` - Project-specific commands
|
||||
- `command/` - Global commands in config directory
|
||||
|
||||
Project commands take precedence over global ones.
|
||||
This is a **required** config option.
|
||||
|
||||
---
|
||||
|
||||
## Built-in commands
|
||||
### Description
|
||||
|
||||
opencode includes several built-in commands:
|
||||
Use the `description` option to provide a brief description of what the command does.
|
||||
|
||||
- `/init` - Initialize project and create AGENTS.md
|
||||
- `/undo` - Revert the last changes
|
||||
- `/redo` - Restore reverted changes
|
||||
- `/share` - Share the current conversation
|
||||
- `/help` - Show available commands and keybinds
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"command": {
|
||||
"test": {
|
||||
"description": "Run tests with coverage"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Use `/help` to see all available commands in your setup.
|
||||
This is shown as the description in the TUI when you type in the command.
|
||||
|
||||
---
|
||||
|
||||
### Agent
|
||||
|
||||
Use the `agent` config to optionally specify which [agent](/docs/agents) should execute this command.
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"command": {
|
||||
"review": {
|
||||
"agent": "plan"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
This is an **optional** config option. If not specified, defaults to "build".
|
||||
|
||||
---
|
||||
|
||||
### Model
|
||||
|
||||
Use the `model` config to override the default model for this command.
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"command": {
|
||||
"analyze": {
|
||||
"model": "anthropic/claude-3-5-sonnet-20241022"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
This is an **optional** config option.
|
||||
|
||||
---
|
||||
|
||||
## Built-in
|
||||
|
||||
opencode includes several built-in commands like `/init`, `/undo`, `/redo`, `/share`, `/help`; [learn more](/docs/tui#commands).
|
||||
|
||||
:::note
|
||||
Custom commands can override built-in commands.
|
||||
:::
|
||||
|
||||
If you define a custom command with the same name, it will override the built-in command.
|
||||
|
||||
@@ -152,6 +152,32 @@ By default, sharing is set to manual mode where you need to explicitly share con
|
||||
|
||||
---
|
||||
|
||||
### Commands
|
||||
|
||||
You can configure custom commands for repetitive tasks through the `command` option.
|
||||
|
||||
```jsonc title="opencode.jsonc"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"command": {
|
||||
"test": {
|
||||
"template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes.",
|
||||
"description": "Run tests with coverage",
|
||||
"agent": "build",
|
||||
"model": "anthropic/claude-3-5-sonnet-20241022"
|
||||
},
|
||||
"component": {
|
||||
"template": "Create a new React component named $ARGUMENTS with TypeScript support.\nInclude proper typing and basic structure.",
|
||||
"description": "Create a new component"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
You can also define commands using markdown files in `~/.config/opencode/command/` or `.opencode/command/`. [Learn more here](/docs/commands).
|
||||
|
||||
---
|
||||
|
||||
### Keybinds
|
||||
|
||||
You can customize your keybinds through the `keybinds` option.
|
||||
@@ -220,6 +246,11 @@ You can configure permissions to control what AI agents can do in your codebase
|
||||
}
|
||||
```
|
||||
|
||||
This allows you to configure explicit approval requirements for sensitive operations:
|
||||
|
||||
- `edit` - Controls whether file editing operations require user approval (`"ask"` or `"allow"`)
|
||||
- `bash` - Controls whether bash commands require user approval (can be `"ask"`/`"allow"` or a pattern map)
|
||||
|
||||
[Learn more about permissions here](/docs/permissions).
|
||||
|
||||
---
|
||||
@@ -259,13 +290,6 @@ about rules here](/docs/rules).
|
||||
|
||||
You can disable providers that are loaded automatically through the `disabled_providers` option. This is useful when you want to prevent certain providers from being loaded even if their credentials are available.
|
||||
|
||||
The `disabled_providers` option accepts an array of provider IDs. When a provider is disabled:
|
||||
|
||||
- It won't be loaded even if environment variables are set
|
||||
- It won't be loaded even if API keys are configured through `opencode auth login`
|
||||
- The provider's models won't appear in the model selection list
|
||||
|
||||
|
||||
```json title="opencode.json"
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
@@ -273,12 +297,11 @@ The `disabled_providers` option accepts an array of provider IDs. When a provide
|
||||
}
|
||||
```
|
||||
|
||||
The permissions system allows you to configure explicit approval requirements for sensitive operations:
|
||||
The `disabled_providers` option accepts an array of provider IDs. When a provider is disabled:
|
||||
|
||||
- `edit` - Controls whether file editing operations require user approval (`"ask"` or `"allow"`)
|
||||
- `bash` - Controls whether bash commands require user approval (can be `"ask"`/`"allow"` or a pattern map)
|
||||
|
||||
[Learn more about permissions here](/docs/permissions).
|
||||
- It won't be loaded even if environment variables are set.
|
||||
- It won't be loaded even if API keys are configured through `opencode auth login`.
|
||||
- The provider's models won't appear in the model selection list.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -25,6 +25,12 @@ Once you're in the TUI, you can prompt it with a message.
|
||||
Give me a quick summary of the codebase.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## File references
|
||||
|
||||
You can reference files in your messages using `@`. This does a fuzzy file search in the current working directory.
|
||||
|
||||
:::tip
|
||||
You can also use `@` to reference files in your messages.
|
||||
:::
|
||||
@@ -33,6 +39,20 @@ You can also use `@` to reference files in your messages.
|
||||
How is auth handled in @packages/functions/src/api/index.ts?
|
||||
```
|
||||
|
||||
The content of the file is added to the conversation automatically.
|
||||
|
||||
---
|
||||
|
||||
## Bash commands
|
||||
|
||||
Start a message with `!` to run a shell command.
|
||||
|
||||
```bash frame="none"
|
||||
!ls -la
|
||||
```
|
||||
|
||||
The output of the command is added to the conversation as a tool result.
|
||||
|
||||
---
|
||||
|
||||
## Commands
|
||||
@@ -235,18 +255,6 @@ Unshare current session. [Learn more](/docs/share#un-sharing).
|
||||
|
||||
---
|
||||
|
||||
## Bash commands
|
||||
|
||||
Start a message with `!` to run a shell command.
|
||||
|
||||
```bash frame="none"
|
||||
!ls -la
|
||||
```
|
||||
|
||||
The output of the command is added to the conversation as a tool result.
|
||||
|
||||
---
|
||||
|
||||
## Editor setup
|
||||
|
||||
Both the `/editor` and `/export` commands use the editor specified in your `EDITOR` environment variable.
|
||||
@@ -300,6 +308,8 @@ Popular editor options include:
|
||||
- `notepad` - Windows Notepad
|
||||
- `subl` - Sublime Text
|
||||
|
||||
:::tip
|
||||
Some editors need command-line arguments to run in blocking mode. The --wait flag makes the editor process block until closed, which is necessary for opencode to function correctly.
|
||||
:::note
|
||||
Some editors like VS Code need to be started with the `--wait` flag.
|
||||
:::
|
||||
|
||||
Some editors need command-line arguments to run in blocking mode. The `--wait` flag makes the editor process block until closed.
|
||||
|
||||
Reference in New Issue
Block a user