OpenCode Commands: Custom Commands, Arguments, and Safe Reuse

OpenCode includes built-in TUI commands such as /init, /undo, /redo, /share, and /help. They are not shell aliases and they are not entries that belong in your repository's package.json. Type them in the OpenCode interface where the prompt is accepted, then read the confirmation or result before continuing.

/help is the safest first check when you are unsure which commands the installed version exposes. /undo and /redo affect the session's change history, so use them as part of a reviewable Git workflow rather than as a replacement for commits. /share can create a shareable session state; inspect what the command makes visible before using it with private repositories or client code.

The exact built-in set can change with OpenCode releases. Treat the official Commands documentation and the installed /help output as the authority. This page focuses on the stable model for finding and authoring commands, not on pretending that a static list can never change.

1. Create .opencode/commands/review.md in the project root.
2. Add a short frontmatter description and a prompt with one clear responsibility.
3. Run the new command in a small branch, inspect the generated prompt and diff, then share it with the team.

---
description: Review the current changes
---
Review the current Git changes. Explain risky behavior,
missing tests, and the smallest safe follow-up.
Do not edit files until I approve the plan.

The filename becomes the command name, so the file above is invoked as /review. A global file under ~/.config/opencode/commands/ is available across projects, while a file under .opencode/commands/ stays with one repository. Prefer the project directory for commands that mention local paths, test conventions, or team policy. Prefer the global directory for a generic personal workflow that does not expose private assumptions.

Keep the prompt explicit about output and boundaries. “Review the current changes and suggest a plan” is easier to validate than “fix everything”. The command can be powerful because it is reusable; it should not be vague because it is reusable.

OpenCode also supports custom commands through the command object in its JSON or JSONC configuration. Use this route when the command should be reviewed beside other project settings, or when you need a compact definition with a specific agent or model. Do not confuse this with the full question of config precedence; use the opencode.jsonc guide for locations, schema, permissions, and rollback.

{
  "$schema": "https://opencode.ai/config.json",
  "command": {
    "test-review": {
      "template": "Review the latest test output and list the first three fixes.",
      "description": "Review test output",
      "agent": "plan"
    }
  }
}

JSON configuration is not a secret store. Keep API keys, tokens, and private endpoints in the provider's supported credential path. A command template can mention a file or run a shell expression, so the config deserves the same review as a script even when it is only a few lines.

---
description: Create a file with supplied values
---
Create a file named $1 in directory $2.
Use this content: $3
Show the proposed path before writing.

A call such as /create-file config.json src "{ \"key\": \"value\" }" supplies three values. The template should state how each value is used and what the agent should show before editing. If you only need one free-form phrase, $ARGUMENTS is simpler than positional placeholders.

Two other forms are useful but deserve extra caution. Put @src/components/Button.tsx in the prompt when the command should include a known file reference. Put !`npm test` or !`git log --oneline -10` in a template when current shell output is part of the prompt. Commands run from the project root, and their output becomes context; do not include destructive or secret-bearing shell commands in a reusable template.

Arguments are input, not permission. A command that accepts a path, a shell fragment, or pasted JSON still runs under the configured OpenCode permission policy. Start with read-only output, then approve a narrow edit, and only then consider an automated command for a trusted repository.

Custom commands can override built-in commands when they use the same name. Avoid names such as help, undo, or share unless you deliberately want that behavior and have a rollback plan. A unique name like review-tests tells the next developer what to expect and reduces accidental behavior changes after an upgrade.

Use Git to review command files like code. Check the prompt diff, the generated response, the files it references, and the shell commands it proposes. When a command selects an agent or model, verify those identifiers in the provider and Agents guide. When it relies on Skills or MCP context, keep those boundaries explicit with the Skills guide and MCP guide.

1. Scope: write one sentence describing the command's input and output.
2. Location: choose project or global storage and make the choice obvious in the README or guide.
3. Inputs: test normal, missing, quoted, and path-like arguments.
4. Context: inspect file references and shell output before asking for an edit.
5. Permissions: begin with ask or read-only behavior, then approve the smallest useful change.
6. Rollback: keep the command in Git and record how to disable or rename it if it conflicts with a built-in command.

This workflow is intentionally slower than pasting a large prompt once. The payoff is repeatability: the next run starts with the same naming, context, and review boundary. It also makes failures diagnosable. A missing command points to its file path; a bad result points to the template or arguments; a failed edit points to permissions; a model error points to provider configuration.