From 2dea8f0f6bc358fd317478030a8dd880e96a8a87 Mon Sep 17 00:00:00 2001 From: Jay V Date: Mon, 18 Aug 2025 13:28:43 -0400 Subject: [PATCH] docs: add tui doc --- .opencode/agent/docs.md | 22 +- packages/web/astro.config.mjs | 2 +- packages/web/src/content/docs/docs/cli.mdx | 127 +------- packages/web/src/content/docs/docs/index.mdx | 16 +- .../web/src/content/docs/docs/providers.mdx | 2 - packages/web/src/content/docs/docs/tui.mdx | 280 ++++++++++++++++++ 6 files changed, 309 insertions(+), 140 deletions(-) create mode 100644 packages/web/src/content/docs/docs/tui.mdx diff --git a/.opencode/agent/docs.md b/.opencode/agent/docs.md index 39cb4743..54e5cdf9 100644 --- a/.opencode/agent/docs.md +++ b/.opencode/agent/docs.md @@ -1,6 +1,4 @@ --- -model: openai/gpt-5 -reasoningEffort: medium description: ALWAYS use this when writing docs --- @@ -8,7 +6,21 @@ You are an expert technical documentation writer You are not verbose -Every chunk of text should be followed by an example or something besides text -to look at. +The title of the page should be a word or a 2-3 word phrase -Chunks of text should not be more than 2 sentences long. +The description should be one short line, should not start with "The", should +avoid repeating the title of the page, should be 5-10 words long + +Chunks of text should not be more than 2 sentences long + +Each section is spearated by a divider of 3 dashes + +The section titles are short with only the first letter of the word capitalized + +The section titles are in the imperative mood + +The section titles should not repeat the term used in the page title, for +example, if the page title is "Models", avoid using a section title like "Add +new models". This might be unavoidable in some cases, but try to avoid it. + +Check out the /packages/web/src/content/docs/docs/index.mdx as an example. diff --git a/packages/web/astro.config.mjs b/packages/web/astro.config.mjs index c2dd1d5d..0ee6c4f2 100644 --- a/packages/web/astro.config.mjs +++ b/packages/web/astro.config.mjs @@ -69,7 +69,7 @@ export default defineConfig({ { label: "Usage", - items: ["docs/cli", "docs/ide", "docs/share", "docs/github"], + items: ["docs/tui", "docs/cli", "docs/ide", "docs/share", "docs/github"], }, { diff --git a/packages/web/src/content/docs/docs/cli.mdx b/packages/web/src/content/docs/docs/cli.mdx index f50a822e..ccf3f0af 100644 --- a/packages/web/src/content/docs/docs/cli.mdx +++ b/packages/web/src/content/docs/docs/cli.mdx @@ -1,137 +1,16 @@ --- title: CLI -description: The opencode CLI options and commands. +description: opencode CLI options and commands. --- import { Tabs, TabItem } from "@astrojs/starlight/components" -Running the opencode CLI starts it for the current directory. +The opencode CLI accepts commands as documented on this page. You can run any of the available commands to interact with opencode programmatically. ```bash -opencode +opencode run "Explain how closures work in JavaScript" ``` -Or you can start it for a specific working directory. - -```bash -opencode /path/to/project -``` - ---- - -## Slash commands - -When using the opencode CLI, you can type `/` followed by a command name to quickly execute actions. For example: - -:::tip -You can also use `@` to reference files in your messages. -::: - -```bash frame="none" -/help -``` - -Here are all available slash commands: - -- **`/help`** - - Show the help dialog. - -- **`/editor`** - - Open external editor for composing messages. Uses the editor set in your `EDITOR` environment variable. [Learn more](#editor-setup). - -- **`/export`** - - Export current conversation to Markdown and open in your default editor. Uses the editor set in your `EDITOR` environment variable. [Learn more](#editor-setup). - -- **`/new`** - - Start a new session. _Alias_: `/clear` - -- **`/sessions`** - - List and switch between sessions. _Aliases_: `/resume`, `/continue` - -- **`/share`** - - Share current session. [Learn more](/docs/share). - -- **`/unshare`** - - Unshare current session. [Learn more](/docs/share#un-sharing). - -- **`/compact`** - - Compact the current session. _Alias_: `/summarize` - -- **`/details`** - - Toggle tool execution details. - -- **`/models`** - - List available models. - -- **`/themes`** - - List available themes. - -- **`/init`** - - Create or update `AGENTS.md` file. [Learn more](/docs/rules). - -- **`/undo`** - - Undo last message. - -- **`/redo`** - - Redo message. - -- **`/exit`** - - Exit opencode. _Aliases_: `/quit`, `/q` - ---- - -### Bash commands - -Start a line with `!` to run a shell command. The output is added to the conversation as a tool result. - -```bash frame="none" -!ls -la -``` - ---- - -### Editor setup - -Both the `/editor` and `/export` commands use the editor specified in your `EDITOR` environment variable. - - - - ```bash export EDITOR=nano # or vim, code, etc. ``` To make it permanent, add this to your shell profile; - `~/.bashrc`, `~/.zshrc`, etc. - - - ```bash set EDITOR=notepad # or code, vim, etc. ``` To make it permanent, use **System Properties** > **Environment - Variables**. - - - ```bash $env:EDITOR = "notepad" # or "code", "vim", etc. ``` To make it permanent, add this to your PowerShell - profile. - - - -Popular editor options include: - -- `code` - Visual Studio Code -- `vim` - Vim editor -- `nano` - Nano editor -- `notepad` - Windows Notepad -- `subl` - Sublime Text - --- ## Commands diff --git a/packages/web/src/content/docs/docs/index.mdx b/packages/web/src/content/docs/docs/index.mdx index ccea974c..858a605b 100644 --- a/packages/web/src/content/docs/docs/index.mdx +++ b/packages/web/src/content/docs/docs/index.mdx @@ -157,16 +157,16 @@ help. You can ask opencode to explain the codebase to you. -```txt frame="none" +:::tip +Use the `@` key to fuzzy search for files in the project. +::: + +```txt frame="none" "@packages/functions/src/api/index.ts" How is authentication handled in @packages/functions/src/api/index.ts ``` This is helpful if there's a part of the codebase that you didn't work on. -:::tip -Use the `@` key to fuzzy search for files in the project. -::: - --- ### Add features @@ -238,7 +238,7 @@ You can ask opencode to add new features to your project. Though we first recomm For more straightforward changes, you can ask opencode to directly build it without having to review the plan first. -```txt frame="none" +```txt frame="none" "@packages/functions/src/settings.ts" "@packages/functions/src/notes.ts" We need to add authentication to the /settings route. Take a look at how this is handled in the /notes route in @packages/functions/src/notes.ts and implement the same logic in @packages/functions/src/settings.ts @@ -253,7 +253,7 @@ changes. Let's say you ask opencode to make some changes. -```txt frame="none" +```txt frame="none" "@packages/functions/src/api/index.ts" Can you refactor the function in @packages/functions/src/api/index.ts? ``` @@ -267,7 +267,7 @@ using the `/undo` command. opencode will now revert the changes you made and show your original message again. -```txt frame="none" +```txt frame="none" "@packages/functions/src/api/index.ts" Can you refactor the function in @packages/functions/src/api/index.ts? ``` diff --git a/packages/web/src/content/docs/docs/providers.mdx b/packages/web/src/content/docs/docs/providers.mdx index 27cb344f..9d7b808c 100644 --- a/packages/web/src/content/docs/docs/providers.mdx +++ b/packages/web/src/content/docs/docs/providers.mdx @@ -614,8 +614,6 @@ In this example: ### OpenAI -https://platform.openai.com/api-keys - 1. Head over to the [OpenAI Platform console](https://platform.openai.com/api-keys), click **Create new secret key**, and copy the key. 2. Run `opencode auth login` and select OpenAI. diff --git a/packages/web/src/content/docs/docs/tui.mdx b/packages/web/src/content/docs/docs/tui.mdx new file mode 100644 index 00000000..9697210b --- /dev/null +++ b/packages/web/src/content/docs/docs/tui.mdx @@ -0,0 +1,280 @@ +--- +title: TUI +description: Using the opencode terminal user interface. +--- + +import { Tabs, TabItem } from "@astrojs/starlight/components" + +opencode provides an interactive terminal interface or TUI for working on your projects with an LLM. + +Running opencode starts the TUI for the current directory. + +```bash +opencode +``` + +Or you can start it for a specific working directory. + +```bash +opencode /path/to/project +``` + +Once you're in the TUI, you can prompt it with a message. + +```text +Give me a quick summary of the codebase. +``` + +:::tip +You can also use `@` to reference files in your messages. +::: + +```text "@packages/functions/src/api/index.ts" +How is auth handled in @packages/functions/src/api/index.ts? +``` + +--- + +## Commands + +When using the opencode TUI, you can type `/` followed by a command name to quickly execute actions. For example: + +```bash frame="none" +/help +``` + +Most commands also have keybind using `ctrl+x` as the leader key, where `ctrl+x` is the default leader key. [Learn more](/docs/keybinds). + +Here are all available slash commands: + +--- + +### compact + +Compact the current session. _Alias_: `/summarize` + +```bash frame="none" +/compact +``` + +**Keybind:** `ctrl+x c` + +--- + +### details + +Toggle tool execution details. + +```bash frame="none" +/details +``` + +**Keybind:** `ctrl+x d` + +--- + +### editor + +Open external editor for composing messages. Uses the editor set in your `EDITOR` environment variable. [Learn more](#editor-setup). + +```bash frame="none" +/editor +``` + +**Keybind:** `ctrl+x e` + +--- + +### exit + +Exit opencode. _Aliases_: `/quit`, `/q` + +```bash frame="none" +/exit +``` + +**Keybind:** `ctrl+x q` + +--- + +### export + +Export current conversation to Markdown and open in your default editor. Uses the editor set in your `EDITOR` environment variable. [Learn more](#editor-setup). + +```bash frame="none" +/export +``` + +**Keybind:** `ctrl+x x` + +--- + +### help + +Show the help dialog. + +```bash frame="none" +/help +``` + +**Keybind:** `ctrl+x h` + +--- + +### init + +Create or update `AGENTS.md` file. [Learn more](/docs/rules). + +```bash frame="none" +/init +``` + +**Keybind:** `ctrl+x i` + +--- + +### models + +List available models. + +```bash frame="none" +/models +``` + +**Keybind:** `ctrl+x m` + +--- + +### new + +Start a new session. _Alias_: `/clear` + +```bash frame="none" +/new +``` + +**Keybind:** `ctrl+x n` + +--- + +### redo + +Redo a previously undone message. Only available after using `/undo`. **Any file changes that were reverted will also be restored.** + +```bash frame="none" +/redo +``` + +**Keybind:** `ctrl+x r` + +--- + +### sessions + +List and switch between sessions. _Aliases_: `/resume`, `/continue` + +```bash frame="none" +/sessions +``` + +**Keybind:** `ctrl+x l` + +--- + +### share + +Share current session. [Learn more](/docs/share). + +```bash frame="none" +/share +``` + +**Keybind:** `ctrl+x s` + +--- + +### themes + +List available themes. + +```bash frame="none" +/themes +``` + +**Keybind:** `ctrl+x t` + +--- + +### undo + +Undo last message in the conversation. Removes the most recent user message and all subsequent responses. **Any file changes made during the undone messages will also be reverted.** + +```bash frame="none" +/undo +``` + +**Keybind:** `ctrl+x u` + +--- + +### unshare + +Unshare current session. [Learn more](/docs/share#un-sharing). + +```bash frame="none" +/unshare +``` + +--- + +## Bash commands + +Start a line with `!` to run a shell command. The output is added to the conversation as a tool result. + +```bash frame="none" +!ls -la +``` + +--- + +## Editor setup + +Both the `/editor` and `/export` commands use the editor specified in your `EDITOR` environment variable. + + + + ```bash + export EDITOR=nano # or vim, code, etc. + ``` + + To make it permanent, add this to your shell profile; + `~/.bashrc`, `~/.zshrc`, etc. + + + + ```bash + set EDITOR=notepad # or code, vim, etc. + ``` + + To make it permanent, use **System Properties** > **Environment + Variables**. + + + + ```bash + $env:EDITOR = "notepad" # or "code", "vim", etc. + ``` + + To make it permanent, add this to your PowerShell + profile. + + + + +Popular editor options include: + +- `code` - Visual Studio Code +- `vim` - Vim editor +- `nano` - Nano editor +- `notepad` - Windows Notepad +- `subl` - Sublime Text