From 73e9274bacc76738a6372849293e9d7577df27a6 Mon Sep 17 00:00:00 2001 From: Wesam Abousaid Date: Mon, 18 May 2026 19:59:40 +0200 Subject: [PATCH] docs(reference): add CLI, slash-commands, permissions, FAQ, changelog, further-reading MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Six reference pages, each a single-purpose cheatsheet: - cli.md: full CLI surface (21 commands + global flags + experimental env vars) sourced from packages/web/src/content/docs/cli.mdx - slash-commands.md: every built-in TUI slash command verified against packages/web/src/content/docs/tui.mdx - permissions.md: all 17 permission keys verified against PermissionConfig in the JSON schema (read, edit, bash, glob, grep, list, task, todowrite, question, external_directory, repo_clone, repo_overview, webfetch, websearch, lsp, skill, doom_loop) - faq.md: covers free-vs-paid, OpenCode vs Claude Code, offline, model picks (multi-provider, not Anthropic-only), config locations, sharing, privacy, migration, troubleshooting - changelog.md: notable releases through v1.15.4 (verified via GitHub releases API, published 2026-05-17T17:44Z) - further-reading.md: curated external resources — only links that resolve (link-checked at commit time) --- docs/reference/changelog.md | 64 ++++++ docs/reference/cli.md | 311 ++++++++++++++++++++++++++++++ docs/reference/faq.md | 252 ++++++++++++++++++++++++ docs/reference/further-reading.md | 69 +++++++ docs/reference/permissions.md | 179 +++++++++++++++++ docs/reference/slash-commands.md | 58 ++++++ 6 files changed, 933 insertions(+) create mode 100644 docs/reference/changelog.md create mode 100644 docs/reference/cli.md create mode 100644 docs/reference/faq.md create mode 100644 docs/reference/further-reading.md create mode 100644 docs/reference/permissions.md create mode 100644 docs/reference/slash-commands.md diff --git a/docs/reference/changelog.md b/docs/reference/changelog.md new file mode 100644 index 0000000..11eb77f --- /dev/null +++ b/docs/reference/changelog.md @@ -0,0 +1,64 @@ +# Changelog Highlights + +> Notable OpenCode releases. For the authoritative, complete list, see [github.com/anomalyco/opencode/releases](https://github.com/anomalyco/opencode/releases). + +This document tracks **what's new at a high level** — the things that change how you use OpenCode. Bug fixes and small polish items aren't listed here. + +## v1.15.x — May 2026 + +Current stable line. Run `opencode upgrade` to get the latest. + +**Verified latest release:** `v1.15.4`, published 2026-05-17 17:44 UTC ([GitHub release](https://github.com/anomalyco/opencode/releases/tag/v1.15.4)). + +**Highlights:** + +- **Agent Skills compatibility** — discoverable workflows via `SKILL.md` folders; compatible with Claude Code skill format. +- **Glob-pattern bash permissions** — fine-grained `allow`/`ask`/`deny` per command pattern, with most-specific wins. +- **Managed configs** — `/Library/Application Support/opencode/` (macOS), `/etc/opencode/` (Linux), `%ProgramData%\opencode` (Windows), plus macOS MDM preferences for enterprise rollouts. +- **ACP server** (`opencode acp`) — Agent Client Protocol server for editor integrations. +- **Remote MCP with auto-OAuth** — Dynamic Client Registration (RFC 7591) handled automatically. +- **Desktop app (beta)** — macOS, Windows, Linux at [opencode.ai/download](https://opencode.ai/download). +- **`AGENTS.md` is canonical** — `CLAUDE.md` remains a fallback for migration (`OPENCODE_DISABLE_CLAUDE_CODE=1` disables it). + +## Earlier 2026 + +- **Plugin event surface expanded** — `session.idle`, `session.compacted`, `tui.toast.show` and more. +- **`opencode pr `** — check out a GitHub PR branch and start a session in it. +- **`opencode stats`** — per-day, per-model, per-project breakdowns. +- **TUI command palette** (`ctrl+p`) — fuzzy-pick slash commands. +- **`tools` glob patterns** — enable/disable groups of MCP tools. +- **`/details` and `/thinking`** — toggle tool-output and thinking-block visibility from inside the TUI. + +## 2025 + +Founding releases. Highlights from this period: + +- **TUI launch** — terminal UI as the primary interface. +- **MCP support** — both local and remote servers. +- **Plugin system** — JS/TS event-driven extensions. +- **OpenCode Zen** — curated model gateway with pay-as-you-go billing. +- **`/share`** — public conversation links via `opncd.ai/s/`. +- **`opencode serve` / `opencode web`** — headless and web-UI modes. + +--- + +## Coming soon (roadmap topics) + +These are themes the OpenCode team has discussed publicly — not commitments to ship by a specific date. + +- Deeper IDE integrations via ACP +- Expanded plugin event surface +- More built-in agents and skills +- Workspace sync across devices + +For the current state, check the [GitHub repo](https://github.com/anomalyco/opencode), the [discussions](https://github.com/anomalyco/opencode/discussions), and [opencode.ai/docs](https://opencode.ai/docs). + +--- + +## Deprecations + +- `CLAUDE.md` as a primary instructions file — use `AGENTS.md`. (Fallback still works; disable with `OPENCODE_DISABLE_CLAUDE_CODE=1`.) + +--- + +*Last reviewed: 2026-05-18 · For the authoritative list, see [GitHub releases](https://github.com/anomalyco/opencode/releases) · Canonical docs: [opencode.ai/docs](https://opencode.ai/docs/).* diff --git a/docs/reference/cli.md b/docs/reference/cli.md new file mode 100644 index 0000000..7cd58f5 --- /dev/null +++ b/docs/reference/cli.md @@ -0,0 +1,311 @@ +# CLI Reference + +> Complete command-line reference for OpenCode. All commands run from a terminal. + +``` +opencode [command] [flags] +``` + +## Default behavior + +Running `opencode` with no command starts the TUI in the current directory. This is the same as `opencode tui`. + +## Global flags + +| Flag | Purpose | +|---|---| +| `--help`, `-h` | Display help | +| `--version`, `-v` | Print version | +| `--print-logs` | Print logs to stderr | +| `--log-level ` | `DEBUG` \| `INFO` \| `WARN` \| `ERROR` | +| `--pure` | Run without loading external plugins | + +--- + +## `opencode` / `opencode tui` + +Start the terminal UI. + +```bash +opencode [project] [flags] +``` + +| Flag | Purpose | +|---|---| +| `--continue`, `-c` | Continue the last session | +| `--session `, `-s` | Continue a specific session | +| `--fork` | Fork the session when continuing | +| `--prompt ` | Pre-fill prompt | +| `--model `, `-m` | Set model (`provider/model-id`) | +| `--agent ` | Start with a specific agent | +| `--port`, `--hostname` | Bind the underlying server | +| `--mdns`, `--mdns-domain` | mDNS discovery | +| `--cors ` | Additional browser origins for CORS | + +--- + +## `opencode run` + +Run OpenCode non-interactively with a prompt. + +```bash +opencode run "summarize the last 5 commits" +opencode run --format json "list every TODO with file and line" +opencode run --agent plan --model anthropic/claude-haiku-4-5 "audit src/ for missing input validation" +``` + +| Flag | Purpose | +|---|---| +| `--continue`, `-c` | Continue the last session | +| `--session `, `-s` | Continue a specific session | +| `--fork` | Fork the session when continuing | +| `--share` | Share the session | +| `--model `, `-m` | Model in `provider/model-id` form | +| `--agent ` | Agent to use | +| `--file `, `-f` | Attach file(s) to the message | +| `--format ` | Output format | +| `--title ` | Title for the session | +| `--attach ` | Attach to a running OpenCode server | +| `--password`, `-p` · `--username`, `-u` | Basic auth for the attached server | +| `--dir ` | Directory to run in | +| `--port` | Port for the local server backing this run | +| `--variant ` | Model variant | +| `--thinking` | Show thinking blocks | +| `--command ` | Run a saved command | +| `--dangerously-skip-permissions` | Auto-approve everything that isn't explicitly denied. **CI only.** | + +--- + +## `opencode auth` + +Manage provider credentials. + +```bash +opencode auth login [--provider ] [--method