> This page is for Fern CLI.

> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://buildwithfern.com/learn/llms.txt. For task-scoped instructions for coding agents working in a Fern project, see https://buildwithfern.com/learn/home/fern-instructions.md.

# Docs commands

> Complete reference for all Fern CLI commands for generating and managing documentation.

These commands build, preview, and publish a Fern documentation site, and validate the MDX pages and links behind it. Creating a docs project with `fern init --docs` and validating `docs.yml` with `fern check` are [general commands](/learn/cli-api-reference/cli-reference/general-commands), and [SDK commands](/learn/cli-api-reference/cli-reference/sdk-commands) generate client libraries from the same API definition your docs render. Each docs command accepts the [global options](/learn/cli-api-reference/cli-reference/options).

| Command                                                 | Description                                                              |
| ------------------------------------------------------- | ------------------------------------------------------------------------ |
| [`fern docs dev`](#fern-docs-dev)                       | Run local documentation preview server                                   |
| [`fern docs dev stop`](#fern-docs-dev-stop)             | Stop a running local documentation preview server                        |
| [`fern docs diff`](#fern-docs-diff) Beta                | Generate visual diffs between preview and production docs                |
| [`fern docs export`](#fern-docs-export)                 | Download your live docs site as HTML, Markdown, or a PDF                 |
| [`fern generate --docs`](#fern-generate---docs)         | Build & publish documentation updates                                    |
| [`fern docs preview list`](#fern-docs-preview-list)     | List all preview deployments                                             |
| [`fern docs preview delete`](#fern-docs-preview-delete) | Delete a preview deployment                                              |
| [`fern docs md check`](#fern-docs-md-check)             | Validate MDX syntax in documentation files                               |
| [`fern docs md generate`](#fern-docs-md-generate)       | Generate MDX pages from library source code                              |
| [`fern docs theme export`](#fern-docs-theme-export)     | Export theme-eligible fields from `docs.yml` into a standalone directory |
| [`fern docs theme upload`](#fern-docs-theme-upload)     | Upload a theme to Fern's registry                                        |
| [`fern docs theme download`](#fern-docs-theme-download) | Download a theme from Fern's registry into a local directory             |
| [`fern docs link check`](#fern-docs-link-check)         | Check for broken links on a live documentation site                      |
| [`fern docs theme list`](#fern-docs-theme-list)         | List all themes for your organization                                    |
| [`fern mcp install`](#fern-mcp-install)                 | Connect a coding agent to your organization's Fern MCP server            |

## Detailed command documentation

#### fern generate --docs

Use `fern generate --docs` to create a documentation site for your API. The command validates your docs before publishing and fails if any rule set to `"error"` in [`check.rules`](/learn/docs/configuration/site-level-settings#check-configuration) reports a violation.

#### terminal

```bash
fern generate --docs [--instance <instance-url>] [--preview] [--id <name>] [--force] [--no-prompt] [--guest] [--new-session]
```

### instance

Use `--instance` to specify which instance URL in your `docs.yml` to generate documentation for.

```bash
fern generate --docs --instance your-organization.docs.buildwithfern.com
```

### preview

Use `--preview` to preview updates to your documentation before publishing changes to your production site.

```bash
fern generate --docs --preview
```

### id

Use `--id` with `--preview` to create a stable, named preview link. The preview URL follows the format `{org}-preview-{id}.docs.buildwithfern.com`, so rerunning with the same `--id` updates the existing preview in place rather than creating a new one.

```bash
fern generate --docs --preview --id my-feature
# -> https://your-org-preview-my-feature.docs.buildwithfern.com
```

This is useful in CI workflows where you want one preview URL per pull request. See [Preview changes](/learn/docs/preview-publish/preview-changes#preview-links) for details.

### force

When reusing an `--id` that already exists, Fern prompts you to confirm the overwrite. Use `--force` or `--no-prompt` to skip the confirmation. This is detected automatically in GitHub Actions, but is needed for other CI environments like Azure Pipelines.

```bash
fern generate --docs --preview --id my-feature --force
# or
fern generate --docs --preview --id my-feature --no-prompt
```

### guest

Use `--guest` to publish without a Fern account. The CLI starts a temporary guest session (or reuses the one saved in `fern/.guest-session`), ignores the `organization` in `fern.config.json` and the instance URL in `docs.yml`, and publishes to a `drop-<id>.docs.buildwithfern.com` site. The output includes a claim link; open it, or run `fern claim` after [`fern login`](/learn/cli-api-reference/cli-reference/general-commands#fern-login), to move the site into an organization before the session expires.

```bash
fern generate --docs --guest
```

`--guest` can't be combined with `FERN_TOKEN` or a saved login. Add `--new-session` to discard the saved guest session and start a fresh one.

#### fern docs dev

Use `fern docs dev` to run a local development server to preview your docs. The server includes the [role selector and password login](/learn/docs/preview-publish/preview-changes#local-development) for sites that use role-based access control or password protection. The server is for previewing on your own machine, not for hosting docs: to serve docs to readers, publish them with [`fern generate --docs`](#fern-generate---docs).

#### terminal

```bash
fern docs dev [--port <port-number>] [--skip-api] [--skip-validation]
              [--timeout <duration>] [--idle-timeout <duration>] [--json]
```

Once the server is ready, the CLI logs how to stop it, using this server's port and process ID:

```
To stop the server, press Ctrl-C, run `fern docs dev stop --port 3000`, or run `kill 12345`.
```

> **Windows: enable long path support**
>
> On Windows, `fern docs dev` requires [long path support](https://learn.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation#enable-long-paths-in-windows-10-version-1607-and-later) to be enabled.
>
> To enable long path support, run the following command in an elevated PowerShell prompt, then restart your terminal:
>
> ```powershell
> New-ItemProperty -Path 'HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem' -Name 'LongPathsEnabled' -Value 1 -PropertyType DWORD -Force
> ```
>
> If you can't enable long path support, use [Windows Subsystem for Linux (WSL)](https://learn.microsoft.com/en-us/windows/wsl/install) to run `fern docs dev` in a Linux environment instead.

### port

Use `--port <port-number>` to specify the port the docs preview will be run on.

```bash
fern docs dev --port 57908
```

### skip-api

Use `--skip-api` to preview without parsing your API specs, which makes startup much faster on sites with large or many API definitions. API Reference sections keep their overview page and hand-written pages and links, but generated endpoint and schema pages are left out of the preview. Validation checks that depend on API specs, including broken-link and OpenAPI example checks, are also skipped; [`fern check`](/learn/cli-api-reference/cli-reference/general-commands#fern-check) still runs them.

```bash
fern docs dev --skip-api
```

### skip-validation

Use `--skip-validation` to skip docs validation while previewing, so the preview is ready sooner on large sites. The CLI logs a warning, and docs errors aren't reported. Run [`fern check`](/learn/cli-api-reference/cli-reference/general-commands#fern-check) before publishing to catch them.

```bash
fern docs dev --skip-validation
```

### timeout

By default, the server runs until it's stopped. Use `--timeout <duration>` to stop it cleanly this long after it's ready; startup and bundle download don't count toward the limit. It accepts durations such as `30s`, `10m`, or `1h`; a plain number means seconds. When the timeout is reached, the CLI shuts down the server and exits with code `0`.

```bash
fern docs dev --timeout 10m
```

### idle-timeout

Use `--idle-timeout <duration>` to stop the server cleanly after this long with no HTTP request in flight. It accepts the same durations as `--timeout`. The live-reload connection doesn't count as activity, so a browser tab left open doesn't keep the server running.

```bash
fern docs dev --idle-timeout 15m
```

### json \[#docs-dev-json]

Use `--json` to write lifecycle events to stdout as one JSON object per line, with logs on stderr. Agents and CI jobs can wait for the `ready` event instead of parsing log output.

```json
{"event":"ready","url":"http://localhost:3000","port":3000,"backendPort":3001,"pid":12345,"stop":{"keys":"Ctrl-C","command":"fern docs dev stop --port 3000","kill":"kill 12345"}}
{"event":"reload","ok":true,"durationMs":412}
{"event":"reload","ok":false,"durationMs":380,"error":"..."}
{"event":"stopped","reason":"idle-timeout"}
```

A `reload` event is emitted after each rebuild triggered by a file change, with `error` present when the rebuild fails. The `ready` event's `stop` object holds the same stop instructions as the log line. The `stopped` event's `reason` is `timeout`, `idle-timeout`, `signal`, `shutdown-request` (stopped by [`fern docs dev stop`](#fern-docs-dev-stop)), or `renderer-exit`.

Combine `--json` with `--idle-timeout` to run a preview in the background, then stop it with `fern docs dev stop` once checks finish. The idle timeout stops the server if the cleanup step never runs:

```bash
fern docs dev --json --idle-timeout 15m > /tmp/fern-dev.ndjson 2> /tmp/fern-dev.log &
# Wait for the "ready" event, then request pages
curl -s http://localhost:3000/llms.txt
fern docs dev stop --port 3000
```

`--timeout`, `--idle-timeout`, `--json`, and [`fern docs dev stop`](#fern-docs-dev-stop) aren't supported with `--legacy`.

### "Version redirection is disabled, so it was not upgraded"

This message is informational. It appears when the CLI cannot redirect to a different version — for example, because the organization's version policy cannot be reached, or because the CLI is running in an environment where version redirection is suppressed. The command still runs using the locally pinned version from `fern.config.json`. It is safe to ignore during local development.

To verify which version is running, check `fern.config.json`. To inspect or change your organization's CLI version policy, use [`fern org get`](/learn/cli-api-reference/cli-reference/general-commands#fern-org-get) or update `fern.config.json` directly.

#### fern docs dev stop

Use `fern docs dev stop` to cleanly stop a [`fern docs dev`](#fern-docs-dev) server from another terminal or script, without finding its process. It stops the server on port `3000` unless `--port` is set, and stops one server per call. It doesn't load your project, so it works from any directory.

#### terminal

```bash
fern docs dev stop [--port <port-number>] [--json]
```

On success, the command waits for the port to close and logs `Stopped fern docs dev on <url> (<fern folder>).` It exits with code `0` when there's nothing to stop, so it's safe to run as an unconditional cleanup step:

* Nothing is listening on the port: `No fern docs dev server running on port 3000; nothing to stop.`
* Another process, or a `fern docs dev --legacy` server, is using the port: `Port 3000 is in use, but not by a fern docs dev server; nothing to stop.` That process keeps running.

It exits with code `1` if the server refuses the request or the port is still open 10 seconds later.

### port \[#docs-dev-stop-port]

Use `--port <port-number>` to stop the server on a port other than `3000`. Use the port from the server's "ready on" log line or its `ready` event. The command doesn't scan other ports.

```bash
fern docs dev stop --port 3002
```

### json \[#docs-dev-stop-json]

Use `--json` to write the result to stdout as a single JSON object, with logs on stderr:

```json
{"stopped":true,"port":3000,"url":"http://localhost:3000","pid":12345,"fernDirectory":"/path/to/project/fern"}
{"stopped":false,"port":3000,"reason":"no-server"}
{"stopped":false,"port":3000,"reason":"not-fern-docs-dev"}
{"stopped":false,"port":3000,"error":"..."}
```

`reason` is `no-server` when nothing is listening and `not-fern-docs-dev` when another process is using the port; both exit with code `0`. `error` is present when the stop fails, which exits with code `1`.

#### fern docs diff

Beta

Use `fern docs diff` to generate visual diffs between your preview deployment and production docs. This command is intended for use in [GitHub Actions](https://github.com/fern-api/docs/blob/main/.github/workflows/preview-docs.yml). It captures screenshots of both versions and creates side-by-side comparison images.

#### terminal

```bash
fern docs diff <preview-url> <files..> [--output <output-dir>]
```

Pass the preview URL from `fern generate --docs --preview` and one or more MDX file paths. Diff images are saved to `.fern/diff` by default.

```bash
fern docs diff acme-preview-abc123.docs.buildwithfern.com fern/pages/intro.mdx fern/pages/quickstart.mdx
```

### output

Use `--output` to specify a custom directory for diff images.

```bash
fern docs diff acme-preview-abc123.docs.buildwithfern.com fern/pages/intro.mdx --output ./my-diffs
```

#### fern docs export

Use `fern docs export` to download a copy of your live Fern-hosted docs site. The export reflects the latest published version. Run it from your Fern project after `fern login`; your account must belong to the organization in `fern.config.json`.

#### terminal

```bash
fern docs export [--format <html|md|pdf>] [--output <path>] [--instance <url>]
```

### format

* `html` (default): the full static site, including each page's Markdown copy, `llms.txt`, and assets.
* `md`: only each page's Markdown and `llms.txt`.
* `pdf`: one PDF of the site, the same as [PDF export](/learn/dashboard/configuration/pdf-export) in the Dashboard.

Pages in an `html` export use root-relative links, so serve the folder with a static file server instead of opening files directly:

```bash
fern docs export
npx serve docs-acme-com-html
```

### output

By default, the export is written to a folder named after the site and format, such as `docs-acme-com-html`, or to `docs-acme-com.pdf` for `pdf`. Use `--output` to choose another folder, or the file name for `pdf`. The command empties the output folder before writing (except `.git`).

```bash
fern docs export --format md --output ./docs-markdown
```

### instance

Use `--instance` to choose which `docs.yml` instance URL to export. Required when `docs.yml` lists more than one instance.

```bash
fern docs export --instance docs.acme.com
```

### PDF options

These options apply only to `--format pdf`:

* `--no-cover` and `--no-toc` leave out the cover page and the table of contents.
* `--cover-title` and `--cover-subtitle` set the cover text.
* `--header-left`, `--header-right`, `--footer-left`, and `--footer-right` add text to each page. Use `{pageIndex}` and `{totalPages}` for page numbers.

```bash
fern docs export --format pdf --no-toc --footer-right "Page {pageIndex} of {totalPages}"
```

#### fern docs preview list

Use `fern docs preview list` to list all [preview deployments](/learn/docs/preview-publish/preview-changes#manage-preview-links) for your organization.

#### terminal

```bash
fern docs preview list [--limit <number>] [--page <number>]
```

### limit

Use `--limit` to specify the number of preview deployments to display per page.

```bash
fern docs preview list --limit 20
```

### page

Use `--page` to specify which page of results to display.

```bash
fern docs preview list --page 2
```

#### fern docs preview delete

Use `fern docs preview delete` to delete a [preview deployment](/learn/docs/preview-publish/preview-changes#manage-preview-links) generated with `fern generate --docs --preview`. Pass the full preview URL, or use `--id` to delete by the identifier used during generation.

#### terminal

```bash
fern docs preview delete <url>

# Or delete by preview ID
fern docs preview delete --id <preview-id>
```

### id

Use `--id` to delete a preview deployment by the identifier used during generation instead of the full preview URL.

```bash
fern docs preview delete --id <preview-id>
```

#### fern docs md check

Use `fern docs md check` to validate MDX syntax across all documentation pages referenced in your navigation configuration, including `docs.yml`, versioned configuration files, and product-specific YAML files.

#### terminal

```bash
fern docs md check
```

The command parses each MDX file and reports syntax errors with file paths and line:column numbers. The command accounts for frontmatter offsets, so reported line numbers correspond to the actual lines in your file.

```plaintext
fern/pages/quickstart.mdx:12:5
  Unexpected closing tag, expected corresponding closing tag for `<CodeBlock>`

fern/pages/guide.mdx:45:1
  Expected a closing tag for `<Note>` before the end of `paragraph`
```

When all files are valid, you'll see a success message:

```plaintext
✓ All 42 MDX files are valid
```

#### fern docs md generate

Use `fern docs md generate` to generate [MDX documentation pages from your library source code](/learn/docs/api-references/library-reference). The command reads `libraries` entries in `docs.yml` and produces pages for modules, classes, functions, and types.

#### terminal

```bash
fern docs md generate [--remote] [--library <name>]
```

By default, the command parses library source on your machine with [Docker](https://docs.docker.com/get-docker/), for both `git` and `path` inputs. Local generation doesn't require authentication. The `--local` flag is still accepted for existing scripts but has no effect.

### remote

Use `--remote` to parse library source on Fern's servers instead of locally. Remote generation requires a `git` input and requires you to be logged in to Fern.

```bash
fern docs md generate --remote
```

### library

Use `--library` to generate docs for a single library when multiple libraries are configured.

```bash
fern docs md generate --library plant-sdk
```

When `--library` is omitted, all configured libraries are processed in parallel.

#### fern docs theme export

Use `fern docs theme export` to extract the [theme-eligible fields](/learn/docs/customization/global-themes) from your `docs.yml` into a standalone directory. The exported `theme.yml` and its assets can then be uploaded with `fern docs theme upload`.

#### terminal

```bash
fern docs theme export [--output <directory>]
```

By default, files are written to `./fern/theme/`.

### output

Use `--output` to specify a custom directory for the exported theme.

```bash
fern docs theme export --output ./my-theme
```

#### fern docs theme upload

Use `fern docs theme upload` to upload a [theme](/learn/docs/customization/global-themes) to Fern's registry. The command reads `theme.yml` from `./fern/theme/` and uploads it along with any referenced file assets.

#### terminal

```bash
fern docs theme upload [--name <name>] [--org <org>]
```

### name

Use `--name` to set the theme name. Defaults to `default`.

```bash
fern docs theme upload --name my-theme
```

### org

Use `--org` to override the organization ID from `fern.config.json`.

```bash
fern docs theme upload --org my-org
```

#### fern docs theme download

Use `fern docs theme download` to fetch a [theme](/learn/docs/customization/global-themes) from Fern's registry and write it as a local theme directory: `theme.yml` plus its logo, font, CSS, and JS assets with relative paths. This is the inverse of `fern docs theme upload`, and the output can be [vendored into a self-hosted image](/learn/docs/self-hosted/set-up#vendor-a-global-theme).

#### terminal

```bash
fern docs theme download --name <name> [--org <org>] [--output <directory>]
```

By default, files are written to `./fern/theme/`.

### name

Use `--name` to select the theme to download.

```bash
fern docs theme download --name my-theme
```

### org

Use `--org` to override the organization ID from `fern.config.json`.

```bash
fern docs theme download --name my-theme --org my-org
```

### output

Use `--output` to specify a custom directory for the downloaded theme.

```bash
fern docs theme download --name my-theme --output ./themes/my-theme
```

#### fern docs link check

Use `fern docs link check` to scan a live documentation site for broken links. The command crawls the published site, checks every link, and reports broken (404) and blocked (403) URLs along with their source pages.

#### terminal

```bash
fern docs link check [--url <url>] [--output <format>]
```

> **Info**
>
> Unlike the [`broken-links` rule](/learn/cli-api-reference/cli-reference/general-commands#fern-check) in `fern check`, which validates only internal links in your local YAML navigation tree, `fern docs link check` checks all links — internal and external — on your live deployed site.

By default, the command auto-detects your docs URL from the `instances` in `docs.yml`. When all links are valid, the command exits with a success message.

The command first scrapes every page on the site, then checks each link it finds. When broken links are found, the output includes a summary and a grouped list of broken URLs with status codes and source file paths.

```plaintext
◆ Checking links on your-org.docs.buildwithfern.com...

  Scraping pages [████████████████████] 100% | 42/42
  Checking links [████████████████████] 100% | 240/240

Finished in 2 minutes, 23 seconds

Summary
    Pages scanned    42
    Links checked    240
    ✓ Working        228
    ✗ Broken         8 (external)
    ⚠ Blocked        4

─────────────────────────────────────

External Broken Links (8)

  ✗ https://example.com/removed-page → 404
        fern/pages/quickstart.mdx
        fern/pages/overview.mdx

  ✗ https://example.com/old-endpoint → 404
        fern/pages/integrations.mdx
```

### url

Use `--url` to specify which docs site to check. This is useful when you have multiple instances or want to check a preview deployment.

```bash
fern docs link check --url https://your-org.docs.buildwithfern.com
```

### output

Use `--output` to control the output format. Supported values are `text` (default), `json`, and `csv`.

```bash
# JSON output for programmatic use
fern docs link check --output json

# CSV output for spreadsheets or reporting
fern docs link check --output csv
```

#### fern docs theme list

Use `fern docs theme list` to list all [themes](/learn/docs/customization/global-themes) uploaded for your organization.

#### terminal

```bash
fern docs theme list [--json] [--org <org>]
```

By default, outputs one theme name per line.

### json

Use `--json` to output the full list as a JSON array, including `updatedAt` timestamps.

```bash
fern docs theme list --json
```

### org

Use `--org` to override the organization ID from `fern.config.json`.

```bash
fern docs theme list --org my-org
```

#### fern mcp install

Use `fern mcp install` to register [your organization's Fern MCP server](/learn/docs/ai-features/fern-mcp-servers) with a coding agent, giving it Fern's own documentation and configuration reference alongside your live sites, deployments, analytics, and reader activity — the same tools [Fern Agent](/learn/docs/ai-features/fern-agent) works from.

#### terminal

```bash
fern mcp install [--client claude|cursor|codex] [--org <org>]
```

The command configures every supported agent installed on the machine, adding a `fern` server entry that holds the server URL and an `Authorization` header. Other entries and surrounding content in each file are preserved.

| Client      | Config file            |
| ----------- | ---------------------- |
| Claude Code | `~/.claude.json`       |
| Cursor      | `~/.cursor/mcp.json`   |
| Codex       | `~/.codex/config.toml` |

The token doesn't refresh, so re-run `fern login && fern mcp install` if the agent's Fern tools start failing.

### client

Use `--client` to configure specific agents instead of every one detected. Repeat the flag to name more than one.

```bash
fern mcp install --client claude --client cursor
```

### org

Use `--org` to override the organization ID from `fern.config.json`. The organization scopes the server URL to `https://fai.buildwithfern.com/organizations/<org>/mcp`. Outside a Fern project, the command falls back to the unscoped `https://fai.buildwithfern.com/mcp`.

```bash
fern mcp install --org my-org
```