Creating Custom Commands
Explore how to create and configure custom commands in OpenCode to automate multi-step coding workflows. Learn to pass arguments, include live shell command outputs, and tailor commands to your project to improve efficiency and team consistency.
We'll cover the following...
- What are custom commands?
- How do we create custom commands?
- How do we pass arguments to commands?
- How do we include shell command output?
- How do we reference files in commands?
- What advanced options can we configure?
- What are some practical command examples?
- How do we define commands using JSON?
- How do commands compare to regular prompts?
- When should we create a custom command?
- What’s next?
We’ve learned how to use OpenCode’s built-in slash commands, such as /init, /undo, and /compact. These commands handle common workflows, but every project has its own patterns and repetitive tasks. Custom commands let us create shortcuts for the workflows we use most.
Custom commands turn repetitive multi-step tasks into single commands. Instead of typing out the same detailed instructions every time we want to run tests, review code, or generate documentation, we create a command that captures that workflow once and reuses it whenever we need it.
What are custom commands?
Custom commands are user-defined shortcuts that execute specific prompts or workflows. They work exactly like built-in slash commands but are tailored to our project’s needs.
For example, instead of typing:
Run the full test suite with coverage report and show any failures.Focus on the failing tests and suggest fixes.
We can create a /test command that does this automatically. We just type /test and OpenCode executes the full workflow.
Custom commands can reference files, run shell commands, accept arguments, and chain multiple steps together. They're essentially reusable prompt templates that make our most common workflows instant.
How do we create custom commands?
There are two ways to define custom commands: using JSON configuration or markdown files. Markdown files are usually simpler and easier to manage, so we'll focus on that approach.
Custom commands live in markdown files in one of two places:
Global commands (available in all projects):
~/.config/opencode/commands/... ...