***

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`](#fern-init)             | Create new Fern project from OpenAPI spec or scratch |
| [`fern check`](#fern-check)           | Validate API definition & configuration              |
| [`fern upgrade`](#fern-upgrade)       | Update Fern CLI & generators to latest versions      |
| [`fern login`](#fern-login)           | Login to Fern CLI via GitHub or Google               |
| [`fern logout`](#fern-logout)         | Log out of the Fern CLI                              |
| [`fern export`](#fern-export)         | Export an OpenAPI spec for your API                  |
| [`fern api update`](#fern-api-update) | Manually update your OpenAPI spec                    |

## Documentation commands

| Command                                                                          | Description                                               |
| -------------------------------------------------------------------------------- | --------------------------------------------------------- |
| [`fern docs dev`](#fern-docs-dev)                                                | Run local documentation preview server                    |
| [`fern docs diff`](#fern-docs-diff) <Badge intent="warning" minimal>Beta</Badge> | Generate visual diffs between preview and production docs |
| [`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                               |

## SDK generation commands

| Command                                             | Description                                                                              |
| --------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| [`fern generate`](#fern-generate)                   | Build & publish SDK updates                                                              |
| [`fern write-definition`](#fern-write-definition)   | Convert OpenAPI specifications to [Fern Definition](/learn/api-definition/fern/overview) |
| [`fern write-overrides`](#fern-write-overrides)     | Create OpenAPI customizations                                                            |
| [`fern generator upgrade`](#fern-generator-upgrade) | Update SDK generators to latest versions                                                 |

## Detailed command documentation

<AccordionGroup>
  <Accordion title="fern init">
    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>
  </Accordion>

  <Accordion title="fern export">
    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>
  </Accordion>

  <Accordion title="fern generate">
    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>

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

  <Accordion title="fern check">
    Use `fern check` to validate your API definition and Fern configuration: [`fern.config.json`](/learn/sdks/overview/project-structure#fernconfigjson), `generators.yml`, and `docs.yml`.

    When successfully executed, this command will not produce any output.

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

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

    ### strict-broken-links

    Use `--strict-broken-links` to fail the command if any broken links are found in your API docs.

    ```bash
    fern check --strict-broken-links
    ```

    <Note>
      For comprehensive link checking, use the [Fern Dashboard](https://dashboard.buildwithfern.com/), which validates both internal and external links on your live published site. This is recommended over `--strict-broken-links` because the Dashboard checks your actual published site and can verify external links that the CLI cannot.
    </Note>

    ## 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>
  </Accordion>

  <Accordion title="fern generate --docs">
    Use `fern generate --docs` to create a documentation site for your API.

    <CodeBlock title="terminal">
      ```bash
      fern generate --docs [instance <instance-url>] [--preview]
      ```
    </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
    ```
  </Accordion>

  <Accordion title="fern docs preview list">
    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
    ```
  </Accordion>

  <Accordion title="fern docs preview delete">
    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>
  </Accordion>

  <Accordion title="fern docs dev">
    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>

    ### port

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

    ```bash
    fern docs dev --port 57908
    ```
  </Accordion>

  <Accordion title="fern docs diff">
    <Badge intent="warning" minimal>
      Beta
    </Badge>

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

  <Accordion title="fern upgrade">
    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>
  </Accordion>

  <Accordion title="fern login">
    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 [--device code]
      ```
    </CodeBlock>

    ### device-code

    Use `--device-code` to login via device code authorization.

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

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

  <Accordion title="fern logout">
    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.
  </Accordion>

  <Accordion title="fern token">
    Use `fern token` to generate a token for authenticating the Fern CLI in CI/CD environments. The token is specific to your organization defined in [`fern.config.json`](/learn/sdks/overview/project-structure#fernconfigjson) and doesn't expire.

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

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

  <Accordion title="fern write-definition">
    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
    ```
  </Accordion>

  <Accordion title="fern write-overrides">
    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
    ```
  </Accordion>

  <Accordion title="fern generator upgrade">
    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.
  </Accordion>

  <Accordion title="fern api update">
    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).

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

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

    <CodeBlock title="terminal">
      ```bash
      fern api update --api public-api
      ```
    </CodeBlock>
  </Accordion>
</AccordionGroup>