11 files changed, 29 insertions, 4 deletions
diff --git a/packages/opencode/src/cli/cmd/debug/agent.ts b/packages/opencode/src/cli/cmd/debug/agent.ts
index 6bd04a0ee..ec5ef0c43 100644
--- a/packages/opencode/src/cli/cmd/debug/agent.ts
+++ b/packages/opencode/src/cli/cmd/debug/agent.ts
@@ -6,6 +6,7 @@ import { cmd } from "../cmd"
 
 export const AgentCommand = cmd({
   command: "agent <name>",
+  describe: "show agent configuration details",
   builder: (yargs) =>
     yargs.positional("name", {
       type: "string",
diff --git a/packages/opencode/src/cli/cmd/debug/config.ts b/packages/opencode/src/cli/cmd/debug/config.ts
index aafcf0469..af536f93c 100644
--- a/packages/opencode/src/cli/cmd/debug/config.ts
+++ b/packages/opencode/src/cli/cmd/debug/config.ts
@@ -5,6 +5,7 @@ import { cmd } from "../cmd"
 
 export const ConfigCommand = cmd({
   command: "config",
+  describe: "show resolved configuration",
   builder: (yargs) => yargs,
   async handler() {
     await bootstrap(process.cwd(), async () => {
diff --git a/packages/opencode/src/cli/cmd/debug/file.ts b/packages/opencode/src/cli/cmd/debug/file.ts
index 51196614c..d3136952b 100644
--- a/packages/opencode/src/cli/cmd/debug/file.ts
+++ b/packages/opencode/src/cli/cmd/debug/file.ts
@@ -6,6 +6,7 @@ import { Ripgrep } from "@/file/ripgrep"
 
 const FileSearchCommand = cmd({
   command: "search <query>",
+  describe: "search files by query",
   builder: (yargs) =>
     yargs.positional("query", {
       type: "string",
@@ -22,6 +23,7 @@ const FileSearchCommand = cmd({
 
 const FileReadCommand = cmd({
   command: "read <path>",
+  describe: "read file contents as JSON",
   builder: (yargs) =>
     yargs.positional("path", {
       type: "string",
@@ -38,6 +40,7 @@ const FileReadCommand = cmd({
 
 const FileStatusCommand = cmd({
   command: "status",
+  describe: "show file status information",
   builder: (yargs) => yargs,
   async handler() {
     await bootstrap(process.cwd(), async () => {
@@ -49,6 +52,7 @@ const FileStatusCommand = cmd({
 
 const FileListCommand = cmd({
   command: "list <path>",
+  describe: "list files in a directory",
   builder: (yargs) =>
     yargs.positional("path", {
       type: "string",
@@ -65,6 +69,7 @@ const FileListCommand = cmd({
 
 const FileTreeCommand = cmd({
   command: "tree [dir]",
+  describe: "show directory tree",
   builder: (yargs) =>
     yargs.positional("dir", {
       type: "string",
@@ -79,6 +84,7 @@ const FileTreeCommand = cmd({
 
 export const FileCommand = cmd({
   command: "file",
+  describe: "file system debugging utilities",
   builder: (yargs) =>
     yargs
       .command(FileReadCommand)
diff --git a/packages/opencode/src/cli/cmd/debug/index.ts b/packages/opencode/src/cli/cmd/debug/index.ts
index 789c726cc..8da6ff559 100644
--- a/packages/opencode/src/cli/cmd/debug/index.ts
+++ b/packages/opencode/src/cli/cmd/debug/index.ts
@@ -12,6 +12,7 @@ import { AgentCommand } from "./agent"
 
 export const DebugCommand = cmd({
   command: "debug",
+  describe: "debugging and troubleshooting tools",
   builder: (yargs) =>
     yargs
       .command(ConfigCommand)
@@ -25,6 +26,7 @@ export const DebugCommand = cmd({
       .command(PathsCommand)
       .command({
         command: "wait",
+        describe: "wait indefinitely (for debugging)",
         async handler() {
           await bootstrap(process.cwd(), async () => {
             await new Promise((resolve) => setTimeout(resolve, 1_000 * 60 * 60 * 24))
@@ -37,6 +39,7 @@ export const DebugCommand = cmd({
 
 const PathsCommand = cmd({
   command: "paths",
+  describe: "show global paths (data, config, cache, state)",
   handler() {
     for (const [key, value] of Object.entries(Global.Path)) {
       console.log(key.padEnd(10), value)
diff --git a/packages/opencode/src/cli/cmd/debug/lsp.ts b/packages/opencode/src/cli/cmd/debug/lsp.ts
index 97cb1a0f3..d83c4ed8a 100644
--- a/packages/opencode/src/cli/cmd/debug/lsp.ts
+++ b/packages/opencode/src/cli/cmd/debug/lsp.ts
@@ -6,6 +6,7 @@ import { EOL } from "os"
 
 export const LSPCommand = cmd({
   command: "lsp",
+  describe: "LSP debugging utilities",
   builder: (yargs) =>
     yargs.command(DiagnosticsCommand).command(SymbolsCommand).command(DocumentSymbolsCommand).demandCommand(),
   async handler() {},
@@ -13,6 +14,7 @@ export const LSPCommand = cmd({
 
 const DiagnosticsCommand = cmd({
   command: "diagnostics <file>",
+  describe: "get diagnostics for a file",
   builder: (yargs) => yargs.positional("file", { type: "string", demandOption: true }),
   async handler(args) {
     await bootstrap(process.cwd(), async () => {
@@ -25,6 +27,7 @@ const DiagnosticsCommand = cmd({
 
 export const SymbolsCommand = cmd({
   command: "symbols <query>",
+  describe: "search workspace symbols",
   builder: (yargs) => yargs.positional("query", { type: "string", demandOption: true }),
   async handler(args) {
     await bootstrap(process.cwd(), async () => {
@@ -37,6 +40,7 @@ export const SymbolsCommand = cmd({
 
 export const DocumentSymbolsCommand = cmd({
   command: "document-symbols <uri>",
+  describe: "get symbols from a document",
   builder: (yargs) => yargs.positional("uri", { type: "string", demandOption: true }),
   async handler(args) {
     await bootstrap(process.cwd(), async () => {
diff --git a/packages/opencode/src/cli/cmd/debug/ripgrep.ts b/packages/opencode/src/cli/cmd/debug/ripgrep.ts
index 4c18bce90..a4cebc5b8 100644
--- a/packages/opencode/src/cli/cmd/debug/ripgrep.ts
+++ b/packages/opencode/src/cli/cmd/debug/ripgrep.ts
@@ -6,12 +6,14 @@ import { cmd } from "../cmd"
 
 export const RipgrepCommand = cmd({
   command: "rg",
+  describe: "ripgrep debugging utilities",
   builder: (yargs) => yargs.command(TreeCommand).command(FilesCommand).command(SearchCommand).demandCommand(),
   async handler() {},
 })
 
 const TreeCommand = cmd({
   command: "tree",
+  describe: "show file tree using ripgrep",
   builder: (yargs) =>
     yargs.option("limit", {
       type: "number",
@@ -25,6 +27,7 @@ const TreeCommand = cmd({
 
 const FilesCommand = cmd({
   command: "files",
+  describe: "list files using ripgrep",
   builder: (yargs) =>
     yargs
       .option("query", {
@@ -56,6 +59,7 @@ const FilesCommand = cmd({
 
 const SearchCommand = cmd({
   command: "search <pattern>",
+  describe: "search file contents using ripgrep",
   builder: (yargs) =>
     yargs
       .positional("pattern", {
diff --git a/packages/opencode/src/cli/cmd/debug/scrap.ts b/packages/opencode/src/cli/cmd/debug/scrap.ts
index 3580aba90..f4b96e883 100644
--- a/packages/opencode/src/cli/cmd/debug/scrap.ts
+++ b/packages/opencode/src/cli/cmd/debug/scrap.ts
@@ -5,6 +5,7 @@ import { cmd } from "../cmd"
 
 export const ScrapCommand = cmd({
   command: "scrap",
+  describe: "list all known projects",
   builder: (yargs) => yargs,
   async handler() {
     const timer = Log.Default.time("scrap")
diff --git a/packages/opencode/src/cli/cmd/debug/skill.ts b/packages/opencode/src/cli/cmd/debug/skill.ts
index 8079b688e..ebe3df180 100644
--- a/packages/opencode/src/cli/cmd/debug/skill.ts
+++ b/packages/opencode/src/cli/cmd/debug/skill.ts
@@ -5,6 +5,7 @@ import { cmd } from "../cmd"
 
 export const SkillCommand = cmd({
   command: "skill",
+  describe: "list all available skills",
   builder: (yargs) => yargs,
   async handler() {
     await bootstrap(process.cwd(), async () => {
diff --git a/packages/opencode/src/cli/cmd/debug/snapshot.ts b/packages/opencode/src/cli/cmd/debug/snapshot.ts
index 1849fe270..4a409dc54 100644
--- a/packages/opencode/src/cli/cmd/debug/snapshot.ts
+++ b/packages/opencode/src/cli/cmd/debug/snapshot.ts
@@ -4,12 +4,14 @@ import { cmd } from "../cmd"
 
 export const SnapshotCommand = cmd({
   command: "snapshot",
+  describe: "snapshot debugging utilities",
   builder: (yargs) => yargs.command(TrackCommand).command(PatchCommand).command(DiffCommand).demandCommand(),
   async handler() {},
 })
 
 const TrackCommand = cmd({
   command: "track",
+  describe: "track current snapshot state",
   async handler() {
     await bootstrap(process.cwd(), async () => {
       console.log(await Snapshot.track())
@@ -19,6 +21,7 @@ const TrackCommand = cmd({
 
 const PatchCommand = cmd({
   command: "patch <hash>",
+  describe: "show patch for a snapshot hash",
   builder: (yargs) =>
     yargs.positional("hash", {
       type: "string",
@@ -34,6 +37,7 @@ const PatchCommand = cmd({
 
 const DiffCommand = cmd({
   command: "diff <hash>",
+  describe: "show diff for a snapshot hash",
   builder: (yargs) =>
     yargs.positional("hash", {
       type: "string",
diff --git a/packages/opencode/src/cli/cmd/web.ts b/packages/opencode/src/cli/cmd/web.ts
index fb32472d7..e2ecc1187 100644
--- a/packages/opencode/src/cli/cmd/web.ts
+++ b/packages/opencode/src/cli/cmd/web.ts
@@ -30,7 +30,7 @@ function getNetworkIPs() {
 export const WebCommand = cmd({
   command: "web",
   builder: (yargs) => withNetworkOptions(yargs),
-  describe: "starts a headless opencode server",
+  describe: "start opencode server and open web interface",
   handler: async (args) => {
     const opts = await resolveNetworkOptions(args)
     const server = Server.listen(opts)
diff --git a/packages/opencode/src/index.ts b/packages/opencode/src/index.ts
index 03ccf7604..e1c2cbd1d 100644
--- a/packages/opencode/src/index.ts
+++ b/packages/opencode/src/index.ts
@@ -101,9 +101,9 @@ const cli = yargs(hideBin(process.argv))
   .command(SessionCommand)
   .fail((msg) => {
     if (
-      msg.startsWith("Unknown argument") ||
-      msg.startsWith("Not enough non-option arguments") ||
-      msg.startsWith("Invalid values:")
+      msg?.startsWith("Unknown argument") ||
+      msg?.startsWith("Not enough non-option arguments") ||
+      msg?.startsWith("Invalid values:")
     ) {
       cli.showHelp("log")
     }