docs/fern/products/cli-api-reference/pages/commands.mdx at b1fdd9e2c3af2668c8dc9772c2c0c8e3183973fa · fern-api/docs

title	Commands
description	Complete reference for all Fern CLI commands for generating SDKs and developer documentation.
subtitle	Learn about the Fern CLI commands.
hideOnThisPage	true

Command	Description
`fern init`	Create new Fern project from OpenAPI spec or scratch
`fern check`	Validate API definition & configuration
`fern upgrade`	Update Fern CLI & generators to latest versions
`fern login`	Login to Fern CLI via GitHub, Google, Postman, or enterprise SSO
`fern logout`	Log out of the Fern CLI
`fern export`	Export an OpenAPI spec for your API
`fern api update`	Manually update your OpenAPI spec
`fern api enrich`	Merge `x-fern-examples` from an overrides file into native OpenAPI examples

Documentation commands

Command	Description
`fern docs dev`	Run local documentation preview server
`fern docs diff` Beta	Generate visual diffs between preview and production docs
`fern generate --docs`	Build & publish documentation updates
`fern docs preview list`	List all preview deployments
`fern docs preview delete`	Delete a preview deployment
`fern docs md check`	Validate MDX syntax in documentation files
`fern docs theme export`	Export theme-eligible fields from `docs.yml` into a standalone directory
`fern docs theme upload`	Upload a theme to Fern's registry
`fern docs theme list`	List all themes for your organization

SDK generation commands

Command	Description
`fern generate`	Build & publish SDK updates
`fern write-definition`	Convert OpenAPI specifications to Fern Definition
`fern write-overrides`	Create OpenAPI customizations
`fern generator upgrade`	Update SDK generators to latest versions

Detailed command documentation

Use `fern init` to initialize a new Fern workspace in the current folder. By default, you'll see the IMDb API example.

<CodeBlock title="terminal">
```bash
fern init [--docs] [--openapi <path/url>]
```
</CodeBlock>

When initializing with OpenAPI, your project structure will look like this:

<Files>
  <Folder name="fern" defaultOpen>
    <File name="fern.config.json" />
    <File name="generators.yml" comment="generators you're using" />
    <Folder name="openapi" defaultOpen>
      <File name="openapi.json" comment="your OpenAPI specification" />
    </Folder>
  </Folder>
</Files>

For Fern Definition initialization (without OpenAPI), you'll see this structure:

<Files>
  <Folder name="fern" defaultOpen>
    <File name="fern.config.json" />
    <File name="generators.yml" comment="generators you're using" />
    <Folder name="definition" defaultOpen>
      <File name="api.yml" comment="API-level configuration" />
      <File name="imdb.yml" comment="endpoints, types, and errors" />
    </Folder>
  </Folder>
</Files>

### openapi

Use `--openapi` to initialize a project from an OpenAPI specification:

```bash
# Initialize from local file
fern init --openapi ./path/to/openapi.yml

# Initialize from URL
fern init --openapi https://link.buildwithfern.com/petstore-openapi
```

### docs

By adding `--docs`, you'll also get a sample documentation website for your API with an API Reference section.

```bash
fern init --docs
```

The file added will contain:

```yaml docs.yaml
instances:
  - url: https://your-organization.docs.buildwithfern.com
title: Your Organization | Documentation
navigation:
  - api: API Reference
colors:
accent-primary: '#ffffff'
background: '#000000'
```

To publish the API docs, run [`fern generate --docs`](/learn/cli-api/cli-reference/commands#fern-generate---docs).

### mintlify

By adding `--mintlify PATH_TO_MINT_CONFIG`, the CLI will automatically convert your Mintlify docs folder into a Fern docs site, based on the `mint.json` file.

```bash
fern init --mintlify PATH_TO_MINT_CONFIG
```

The CLI will create a `fern/` folder with the following structure:

<Files>
  <Folder name="fern" defaultOpen>
    <File name="fern.config.json" comment="root-level configuration" />
    <File name="docs.yml" comment="docs configuration" />
    <File name="..." comment="any other files / pages needed in your docs" />
  </Folder>
</Files>

### readme

The `fern init` command supports importing Readme generated docs sites. This requires having a local chromium browser instance installed.
You can ensure this is installed by installing the `fern` cli from source, following the instructions [here](https://github.com/fern-api/fern/blob/main/CONTRIBUTING.md).

By adding `--readme URL_TO_README_DOCS_SITE`, the CLI will automatically convert the Readme generated docs site into a Fern docs site.

```bash
fern init --readme URL_TO_README_DOCS_SITE
```

The CLI will create a `fern/` folder with the following structure:

<Files>
  <Folder name="fern" defaultOpen>
    <File name="fern.config.json" comment="root-level configuration" />
    <File name="docs.yml" comment="docs configuration" />
    <File name="..." comment="any other files / pages needed in your docs" />
  </Folder>
</Files>

<Tip>
For more information on getting started, check out our [Quickstart Guide](/learn/docs/getting-started/quickstart)
</Tip>

Use `fern export` to generate an OpenAPI spec for your API.

This command is useful when you've defined your API in a format other than OpenAPI (such as the [Fern Definition](/api-definitions/ferndef/overview)) and need to export it as an OpenAPI spec for integration with other tools or services.


<CodeBlock title="terminal">
```bash
fern export [--api <api>] path/to/openapi.yml
fern export [--api <api>] path/to/openapi.json
```
</CodeBlock>

### api

Use `--api` to specify which API to export when you have multiple APIs defined in your `fern/apis/` folder.

    <CodeBlock title="terminal">
```bash
fern export --api public-api path/to/openapi.yml
fern export --api public-api path/to/openapi.json
```
</CodeBlock>

Use `fern generate` to run the Fern compiler and create SDKs for your API.

<CodeBlock title="terminal">
```bash
fern generate [--group <group>] [--api <api>] [--version <version>] [--preview] [--fernignore <path>] [--local] [--force]
```
</CodeBlock>

### group

Use `--group <group>` to specify which generator group to run. You can use either a group name or an alias name. Aliases are [defined in your `generators.yml`](/learn/sdks/reference/generators-yml#aliases) and map to multiple groups, allowing you to run several groups in parallel with a single command.

```bash
# Run a specific group
fern generate --group python-sdk

# Run all groups defined in the "all" alias
fern generate --group all

# Run all groups defined in the "frontend" alias
fern generate --group frontend

# Run a specific group locally (self-hosted)
fern generate --group python-sdk --local
```

You can also set an alias as your `default-group` in `generators.yml`, so running `fern generate` without any arguments will run all groups in that alias.

The `--group` flag can be combined with other flags like `--local` for [self-hosted SDK generation](/learn/sdks/deep-dives/self-hosted), `--preview` for local testing, or `--version` to specify the SDK version.

### preview

Use `--preview` to test SDK changes locally before publishing. This is especially useful during development:
- Generates SDK into a local `.preview/` folder
- Allows quick iteration on your Fern definition
- No changes are published to package managers or GitHub

```bash
# Preview all SDKs
fern generate --preview

# Preview specific SDK group
fern generate --group python-sdk --preview
```

### api

Use `--api <api>` to specify the API for SDK generation. This is useful when your project contains multiple API definitions. The API name should match the directory name in your `fern/apis/` folder.

```bash
fern generate --api public-api
```

### version

Use `--version` to specify the SDK version number, typically following semantic versioning (semver) format (`MAJOR.MINOR.PATCH`). This is particularly useful in CI/CD pipelines when publishing SDK releases.

```bash
# Generate all SDKs with version 2.11.0
fern generate --version 2.11.0

# Generate Python SDK for the payments API with version 1.2.3
fern generate --api payments-api --group python-sdk --version 1.2.3
```

### fernignore

Use `--fernignore` to specify a custom `.fernignore` file path for SDK generation. This allows you to temporarily test different ignore configurations without modifying the committed `.fernignore` in your repository.

Fern will use the specified file instead of the one on the main branch and commit the new `.fernignore` to your repository as part of the generation process.

```bash
fern generate --fernignore ./custom-fernignore
```

### local

Use `--local` to run SDK generation on your own machine instead of using Fern's cloud infrastructure. This is useful for organizations with strict security or compliance requirements. See [self-hosted SDKs](/learn/sdks/deep-dives/self-hosted) for setup instructions.

```bash
# Generate all SDKs locally
fern generate --local

# Generate specific SDK group locally
fern generate --group python-sdk --local
```

<Note>
A Docker daemon must be running on your machine, as SDK generation runs inside a Docker container.
</Note>

By default, the CLI pulls generator images from Docker Hub. To pull from a custom container registry, use the [`image` field](/learn/sdks/reference/generators-yml#image) in your `generators.yml` instead of `name`. See [custom container registry](/learn/sdks/deep-dives/self-hosted#optional-configure-a-custom-container-registry) for details.

### force

Use `--force` to skip confirmation prompts during generation. This is useful in CI/CD environments where interactive prompts would block the pipeline.

```bash
# Generate without confirmation prompts
fern generate --group python-sdk --force
```

<Warning>
The `--broken-links` and `--strict-broken-links` flags are deprecated. Use the [`broken-links` validation rule](/learn/docs/configuration/site-level-settings#check-configuration) in `docs.yml` instead.

You can also use the [Fern Dashboard](https://dashboard.buildwithfern.com/) to validate both internal and external links on your live published site.
</Warning>

Use `fern check` to validate your API definition and Fern configuration, including [`fern.config.json`](/learn/sdks/overview/project-structure#fernconfigjson), `generators.yml`, and `docs.yml`. It checks for broken links, invalid API examples, configuration errors, and more. When all checks pass, the command produces no output.

<CodeBlock title="terminal">
```bash
fern check [--api <api>] [--warnings]
```
</CodeBlock>

You can configure the severity of the validation rules run by `fern check` in your `docs.yml` file [using the `check.rules` property](/learn/docs/configuration/site-level-settings#check-configuration).

```yaml docs.yml
check:
  rules:
    broken-links: error
    example-validation: warn
    missing-redirects: error
```

### api

Use `--api <api>` to specify which API you'd like to check. 

```bash
fern check --api public-api
```

### warnings

Use `--warnings` to log warnings in addition to errors. 

```bash
fern check --warnings
```

## Usage in a GitHub Action

<CodeBlock title = ".github/workflows/fern-check.yml" >
```yml maxLines=14 
name: Fern Validation Check

on:
  pull_request:
  push:
    branches:
      - main

jobs:
  validate-fern-api:
    name: Validate using Fern's linter
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Install Fern CLI
        run: npm install -g fern-api

      - name: Validate API with Fern
        run: fern check

```
</CodeBlock>

Use `fern generate --docs` to create a documentation site for your API. 

<CodeBlock title="terminal">
```bash
fern generate --docs [instance <instance-url>] [--preview] [--id <name>] [--force]
```
</CodeBlock>

### 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` 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
```

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

<CodeBlock title="terminal">
```bash
fern docs preview list [--limit <number>] [--page <number>]
```
</CodeBlock>

### 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
```

Use `fern docs preview delete` to delete a preview deployment generated with `fern generate --docs --preview`. The `<url>` argument is the full preview URL to delete.

<CodeBlock title="terminal">
```bash
fern docs preview delete <url>
```
</CodeBlock>

Use `fern docs dev` to run a local development server to preview your docs.

<CodeBlock title="terminal">
```bash
fern docs dev [--port <port-number>]
```
</CodeBlock>

<Warning title="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.
</Warning>

### port

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

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

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.

<CodeBlock title="terminal">
```bash
fern docs md check
```
</CodeBlock>

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

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.

<CodeBlock title="terminal">
```bash
fern docs diff <preview-url> <files..> [--output <output-dir>]
```
</CodeBlock>

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

Use `fern upgrade` to upgrade your compiler version in [`fern.config.json`](/learn/sdks/overview/project-structure#fernconfigjson) to the
latest version. It will also upgrade generators in `generators.yml` to their minimum-compatible versions.

<CodeBlock title="terminal">
```bash
fern upgrade
```
</CodeBlock>

Use `fern login` to login to the Fern CLI via GitHub or Google. Logging in allows you 
join GitHub organizations, gain permissions, and contribute to projects.

<CodeBlock title="terminal">
```bash
fern login
fern login --device-code
fern login --email <email>
```
</CodeBlock>

By default, `fern login` opens a browser for GitHub, Google, or Postman authentication. Two alternative flows are available:

### device-code

Use `--device-code` to login via device code authorization in environments where a browser cannot open automatically (e.g., SSH sessions or containers).

```bash
fern login --device-code
```

### email

Use `--email` to login via enterprise SSO. Pass the email address associated with your organization's SSO provider.

```bash
fern login --email user@example.com
```

<Note>
To enable CI/CD, use [`fern token`](/learn/cli-api/cli-reference/commands#fern-token).
</Note>

Use `fern logout` to log out of the Fern CLI. This will clear your authentication 
credentials and revoke access to your GitHub organizations and permissions.

<CodeBlock title="terminal">
```bash
fern logout
```
</CodeBlock>

After logging out, you'll need to run [`fern login`](#fern-login) again to access protected features.

<Markdown src="/snippets/fern-token.mdx" />

See [Publishing your docs](/learn/docs/preview-publish/publishing-your-docs#usage-in-github-actions) for instructions on using this token in automated publishing workflows.

Use `fern write-definition` to convert your OpenAPI Specification into a Fern Definition. 
You must have a `fern/openapi/` folder that contains an OpenAPI Specification file in `.json` or `.yaml` format.

<CodeBlock title="terminal">
```bash
fern write-definition [--api <api>]
```
</CodeBlock>

When run, this command creates a new folder within `fern/` called `.definition/`. 

<Files>
  <Folder name="fern" defaultOpen>
    <File name="fern.config.json" />
    <File name="generators.yml" />
    <Folder name="openapi" defaultOpen>
      <File name="openapi.json" />
    </Folder>
    <Folder name=".definition" defaultOpen comment="your Fern Definition" highlighted>
      <File name="api.yml" highlighted />
      <File name="__package__.yml" highlighted />
    </Folder>
  </Folder>
</Files>

<Warning>
If you do not see the `.definition/` folder, use the appropriate command or configuration to view hidden folders (`ls -a` in `bash` and `zsh`).
</Warning>

If your `fern/` folder contains both an `openapi/` and a `definition/` folder, Fern defaults to reading your OpenAPI Specification. To use your Fern Definition as input, you must:
- Rename the `.definition/` folder to `definition/`.
- Remove or rename the `openapi/` folder. For example, you can rename it to `.openapi/`. 

### api

Use `--api` to specify the API to write the definition for if you have multiple defined in your `fern/apis/` folder. 

```bash
fern write-definition --api public-api
```

Use `fern write-overrides` to generate a basic OpenAPI overrides file. An overrides file allows for 
reversible revisions to the API specification, including adding request and response examples for 
code snippets in Fern Docs.

<CodeBlock title="terminal">
```bash
fern write-overrides [--api <api>] [--exclude-models]
```
</CodeBlock>

When run, this command creates a new file within `fern/openapi/` called `openapi-overrides.yml`. 

<Files>
  <Folder name="fern" defaultOpen>
    <File name="fern.config.json" />
    <File name="generators.yml" />
    <Folder name="openapi" defaultOpen>
      <File name="openapi-overrides.yaml" comment="your overrides file" highlighted />
      <File name="openapi.json" />
    </Folder>
  </Folder>
</Files>

### api

Use `--api` to specify the API to run the command on if multiple are defined.  

```bash
fern write-overrides --api public-api
```

### exclude-models

Use `--exclude-models` to stub the models while generating the initial overrides (in addition to the endpoints).

```bash
fern write-overrides --exclude-models
```

Use `fern generator upgrade` to update all generators in your `generators.yml` to their latest versions.

<Note>
This is different from `fern upgrade` which updates the Fern CLI version. Use both commands to keep your entire Fern toolchain up to date.
</Note>

<CodeBlock title="terminal">
```bash
fern generator upgrade [--list] [--generator <generator-name>] [--group <group>] [--include-major]
```
</CodeBlock>

This command will:
- Check for updates to all generators specified in your `generators.yml`
- Update the generator versions to their latest compatible releases
- Maintain compatibility with your current Fern compiler version

Here's what you might see when updates are available:

```plaintext
┌───────────────────────────────────────────────────────────────────────────────────┐
│                                                                                   │
│                                Upgrades available                                 │
│                                                                                   │
│                                                                                   │
│             C# SDK (API: openapi, Group: csharp-sdk) 1.9.11 → 1.9.15              │
│              Java SDK (API: openapi, Group: java-sdk) 2.2.0 → 2.11.3              │
│           Python SDK (API: openapi, Group: python-sdk) 4.3.10 → 4.3.11            │
│                                                                                   │
│              Run fern generator upgrade to upgrade your generators.               │
│   Run fern generator upgrade --list to see the full list of generator upgrades    │
│                                    available.                                     │
│                                                                                   │
└───────────────────────────────────────────────────────────────────────────────────┘
```

### list

Use `--list` to see the full list of generator upgrades available.

```bash
fern generator upgrade --list
```

### generator

Use `--generator` to specify a particular generator type to upgrade.

```bash
fern generator upgrade --generator fernapi/fern-typescript-sdk
fern generator upgrade --generator fernapi/fern-python-sdk
```

### group

Use `--group` to upgrade generators within a specific group in your `generators.yml`. If not specified, all generators of the specified type will be upgraded.

```bash
fern generator upgrade --group public
```

### include-major

```bash
fern generator upgrade --include-major
```

 Use `--include-major` to include major version upgrades. Major versions are skipped by default to prevent breaking changes.

Pulls the latest OpenAPI spec from the specified `origin` in `generators.yml` and updates the local spec. Alternatively, you can [automate this process by setting up a GitHub Action](/api-definitions/openapi/sync-your-open-api-specification). ```bash fern api update [--api ] ```

api

Use --api to specify the API to update if there are multiple specs with a defined origin in generators.yml. If you don't specify an API, all OpenAPI specs with an origin will be updated.

```bash fern api update --api public-api ```

Use `fern api enrich` to convert [AI-generated examples](/learn/docs/ai-features/ai-examples) or manually authored [`x-fern-examples`](/learn/api-definitions/openapi/extensions/request-response-examples) into portable OpenAPI examples that any OpenAPI-compatible tool can consume.

<CodeBlock title="terminal">
```bash
fern api enrich <openapi> -f <overrides-file> -o <output-file>
```
</CodeBlock>

The command merges examples from an overrides file into native OpenAPI `example` fields and strips the `x-fern-examples` keys from the output. When an endpoint has multiple examples, each is stored as a named entry under the plural `examples` field.

The command requires two flags:

- `-f` (or `--file`) — the overrides file containing `x-fern-examples` (e.g., `ai_examples_override.yml`).
- `-o` (or `--output`) — the path for the enriched output file. Supports `.yml` and `.json` extensions.

```bash
# Output as YAML
fern api enrich openapi.yml -f overrides.yml -o enriched-openapi.yml

# Output as JSON
fern api enrich openapi.yml -f overrides.yml -o enriched-openapi.json
```

Each `x-fern-examples` field is mapped to its standard OpenAPI location:

- `path-parameters` → `parameters[].example` (where `in: path`)
- `query-parameters` → `parameters[].example` (where `in: query`)
- `headers` → `parameters[].example` (where `in: header`)
- `request.body` → `requestBody.content.*.example`
- `response.body` → `responses.<status>.content.*.example`

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

<CodeBlock title="terminal">
```bash
fern docs theme export [--output <directory>]
```
</CodeBlock>

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

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.

<CodeBlock title="terminal">
```bash
fern docs theme upload [--name <name>] [--org <org>]
```
</CodeBlock>

### 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
```

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

<CodeBlock title="terminal">
```bash
fern docs theme list [--json] [--org <org>]
```
</CodeBlock>

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Documentation commands

SDK generation commands

Detailed command documentation

api

FilesExpand file tree

commands.mdx

Latest commit

History

commands.mdx

File metadata and controls

Documentation commands

SDK generation commands

Detailed command documentation

api