Docs commands

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 reports a violation.

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.

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.

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.

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 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.

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, to move the site into an organization before the session expires.

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.

Use fern docs dev to run a local development server to preview your docs. The server includes the role selector and password login 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 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`.

New-ItemProperty -Path 'HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem' -Name 'LongPathsEnabled' -Value 1 -PropertyType DWORD -Force

port

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

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 still runs them.

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 before publishing to catch them.

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.

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.

fern docs dev --idle-timeout 15m

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.

{"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), 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:

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 aren’t supported with --legacy.

Use fern docs dev stop to cleanly stop a 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.

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

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.

fern docs dev stop --port 3002

json

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

{"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.

Use fern docs diff to generate visual diffs between your preview deployment and production docs. This command is intended for use in GitHub Actions. It captures screenshots of both versions and creates side-by-side comparison images.

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.

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.

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

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. See Export your docs for limits and security.

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 in the Dashboard.

Links in an html export are relative file paths, so any static file server can serve the folder:

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).

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.

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.

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

Use fern docs preview list to list all preview deployments for your organization.

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

limit

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

fern docs preview list --limit 20

page

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

fern docs preview list --page 2

Use fern docs preview delete to delete a preview deployment generated with fern generate --docs --preview. Pass the full preview URL, or use --id to delete by the identifier used during generation.

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.

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

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.

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.

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:

✓ All 42 MDX files are valid

Use fern docs md generate to generate MDX documentation pages from your library source code. The command reads libraries entries in docs.yml and produces pages for modules, classes, functions, and types.

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

By default, the command parses library source on your machine with 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.

fern docs md generate --remote

library

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

fern docs md generate --library plant-sdk

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

Use fern docs theme export to extract the theme-eligible fields from your docs.yml into a standalone directory. The exported theme.yml and its assets can then be uploaded with fern docs theme upload.

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.

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

Use fern docs theme upload to upload a theme to Fern’s registry. The command reads theme.yml from ./fern/theme/ and uploads it along with any referenced file assets.

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

name

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

fern docs theme upload --name my-theme

org

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

fern docs theme upload --org my-org

Use fern docs theme download to fetch a theme 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.

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.

fern docs theme download --name my-theme

org

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

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

output

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

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

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.

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

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.

◆ 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.

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.

# JSON output for programmatic use
fern docs link check --output json
# CSV output for spreadsheets or reporting
fern docs link check --output csv

Use fern docs theme list to list all themes uploaded for your organization.

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.

fern docs theme list --json

org

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

fern docs theme list --org my-org

Use fern mcp install to register your organization’s Fern MCP server 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 works from.

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.

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.

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.

fern mcp install --org my-org