# Generating CLI Docs for Holocron

Generate a full CLI reference site from your goke CLI using `generateDocs()` and [Holocron](https://holocron.so) (or Mintlify). Each command becomes an `.mdx` page with YAML frontmatter, and the script handles titles, icons, and auto-generated warnings. Holocron auto-generates descriptions from page content, so the script does not need to extract them.

## 1. Add the generate script

Create a script that imports your CLI, calls `generateDocs()`, and writes `.mdx` files with Holocron frontmatter.

**`basePath`** is important when your CLI docs live in a subdirectory like `/docs/cli`. Without it, relative links like `./database-create` resolve against the parent path (`/docs/database-create` instead of `/docs/cli/database-create`). `basePath` makes all links absolute so they work correctly regardless of nesting.

```ts
// scripts/generate-cli-docs.ts
import fs from 'node:fs'
import path from 'node:path'
import { generateDocs } from 'goke'
import { cli } from '../src/cli'

const outDir = path.resolve(import.meta.dirname, '../src/docs/cli')

// Map command group prefixes to Lucide icons for sidebar display
const icons: Record<string, string> = {
  login: 'lucide:log-in',
  logout: 'lucide:log-out',
  deploy: 'lucide:rocket',
  status: 'lucide:activity',
  logs: 'lucide:scroll-text',
}

const pages = generateDocs({ cli, basePath: '/docs/cli' })

if (fs.existsSync(outDir)) {
  fs.rmSync(outDir, { recursive: true })
}
fs.mkdirSync(outDir, { recursive: true })

console.log(`Generating ${pages.length} CLI doc pages into ${outDir}`)

for (const page of pages) {
  const title = page.command
    ? page.command.split(' ').map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(' ')
    : 'CLI Overview'
  const icon = icons[page.slug.split('-')[0]] || 'lucide:terminal'

  const frontmatter = [
    '---',
    '# This file is auto-generated by scripts/generate-cli-docs.ts. Do not edit manually.',
    '$schema: https://holocron.so/frontmatter.json',
    `title: "${title}"`,
    ...(title.length > 30 ? [`sidebarTitle: "${page.command || 'CLI'}"`] : []),
    `icon: ${icon}`,
    '---',
    '',
  ].join('\n')

  const filePath = path.join(outDir, `${page.slug}.mdx`)
  fs.writeFileSync(filePath, frontmatter + page.content)
  console.log(`  wrote docs/cli/${page.slug}.mdx`)
}

console.log('Done!')
```

## 2. Add the script to package.json

```json
{
  "scripts": {
    "generate:cli-docs": "bun scripts/generate-cli-docs.ts"
  }
}
```

Use `bun` instead of `tsx` if your CLI source uses TypeScript parameter properties or other syntax that Node's strip-only mode rejects.

## 3. Add pages to docs.jsonc

Register the generated pages in your Holocron navigation. Group commands by feature area for a clean sidebar.

```jsonc
{
  "tabs": [
    {
      "tab": "CLI",
      "icon": "lucide:terminal",
      "groups": [
        {
          "group": "General",
          "pages": [
            "docs/cli/index",
            "docs/cli/login",
            "docs/cli/logout"
          ]
        },
        {
          "group": "Deploy",
          "pages": [
            "docs/cli/deploy-up",
            "docs/cli/deploy-status",
            "docs/cli/deploy-logs"
          ]
        }
      ]
    }
  ]
}
```

## 4. Run it

```bash
pnpm run generate:cli-docs
```

Each `.mdx` file includes a frontmatter comment warning not to edit it manually. Regenerate whenever the CLI changes.

## Tips

- **`sidebarTitle`** is only added when the title exceeds 30 characters, keeping short titles clean in the sidebar.
- **Icons** are mapped by the first segment of the slug (e.g. `deploy-up` matches `deploy`). Fall back to `lucide:terminal` for unmatched commands.
- **Angle brackets** in descriptions like `<id>` and `<fingerprint>` are automatically escaped by `generateDocs()` (goke 6.12.3+) so MDX parsing does not break.