---
title: "CLI reference"
url: "/help/buuk/cli-reference"
updated: "2026-10-22T11:13:55.712Z"
---
# CLI reference

The Buuk CLI is a machine interface for your workspace, sitting alongside the public REST API. It has three commands — `init`, `suggest`, and `export` — and all of them are driven by environment variables, which is what makes it a natural fit for CI.

## Setup

Create a token in **Settings → Developers** — the full value starts with `buuk_cli_` and is shown once. Pick **Can write** for `init` and `suggest`; a **Read only** token is enough for `export`. Store the secret somewhere safe — see [API tokens and MCP](./api-tokens-and-mcp).

```bash
export BUUK_API_TOKEN=buuk_cli_…      # required by every command
export BUUK_API_URL=https://your-buuk-host   # defaults to a local app
export BUUK_WORKSPACE=your-slug       # or pass --workspace each time
```

The workspace slug must match the token — a token is scoped to exactly one workspace.

## buuk init

A short interactive setup: it prompts for a workspace name, an optional website URL, and an optional brand hex color, then creates the workspace with its starter content and prints the dashboard URL and next steps. Use it to spin up a workspace from a script before pointing other tools at it.

```bash
buuk init
```

## buuk suggest

Suggest posts one message into the Suggestions queue — the same review list that connected tools feed. It never publishes and never touches pages on its own: an editor decides what happens next, see [Suggested updates](./suggested-updates).

- The message text — what the suggestion is about, in your words.
- --source `ci` or `cli` labels where it came from.
- --title names the suggestion; --workspace overrides the slug from the environment.
- The same message is deduplicated, so a nightly rerun does not pile up copies — a duplicate answers `Suggestion already queued or deduplicated`.

<!-- One call -->

```bash
buuk suggest "Error-code table missing in Payments docs" \
  --source ci --title "Payments docs gap" --workspace acme
```

<!-- GitHub Actions -->

```yaml
name: docs-suggestions
on:
  schedule:
    - cron: "0 4 * * *"   # nightly
jobs:
  suggest:
    runs-on: ubuntu-latest
    steps:
      - run: |
          while IFS= read -r note; do
            [ -n "$note" ] && buuk suggest "$note" --source ci \
              --workspace "$BUUK_WORKSPACE"
          done < release-notes.txt
        env:
          BUUK_API_TOKEN: ${{ secrets.BUUK_API_TOKEN }}
          BUUK_WORKSPACE: acme
```

The command sends one message per call, so in CI you decide what to feed it — a loop over release notes, dependency upgrades, or support transcripts. The nightly sketch above is the usual pattern: run on a schedule, read your source of truth, call `suggest` once per item.

## buuk export

Export copies your published docs to disk as plain files: one `.mdx` per published help article, guide, and FAQ with frontmatter, each OpenAPI spec as JSON, and changelog entries as markdown. Drafts are not included, and uploaded media is not bundled.

- --format `mdx+openapi` (the default) or `mint`, which also writes a `mint.json` mapping the whole navigation.
- --output sets the target directory; it defaults to `./buuk-export`.

<!-- mdx+openapi -->

```bash
buuk export --workspace acme --output ./buuk-export
```

<!-- mint -->

```bash
buuk export --workspace acme --format mint --output ./docs-out
```

For the full file layout and the walkthrough, see [Export your docs](./export-your-docs).

## Where CI fits

A common rhythm: a nightly job runs `suggest` against your newest release notes so gaps land in Suggestions by morning, while a scheduled `export` gets committed to a repo as a versioned backup you can diff. `init` rarely repeats — it is the once-per-workspace setup step.

> [!WARNING]
> Put BUUK_API_TOKEN in your CI secret store, never in the workflow file or code. Use a read-only token where nothing is written, and Can write only where suggestions are created.

## Related

- Minting and revoking tokens: [API tokens and MCP](./api-tokens-and-mcp).
- The export walkthrough: [Export your docs](./export-your-docs).
- Where CI suggestions land: [Suggested updates](./suggested-updates).
- Push changes out instead: [Webhooks](./webhooks).