Commands

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

$
fern init [--docs] [--openapi <path/url>]

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

$
fern/
>
├─ fern.config.json
>
├─ generators.yml # generators you're using
>
└─ openapi/
>
    └─ openapi.json # your OpenAPI specification

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

$
fern/
>
├─ fern.config.json
>
├─ generators.yml # generators you're using
>
└─ definition/
>
    ├─ api.yml  # API-level configuration
>
    └─ imdb.yml # endpoints, types, and errors

openapi

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

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

$
fern init --docs

The file added will contain:

1
instances:
2
  - url: https://your-organization.docs.buildwithfern.com
3
title: Your Organization | Documentation
4
navigation:
5
  - api: API Reference
6
colors:
7
accent-primary: '#ffffff'
8
background: '#000000'

To publish the API docs, run 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.

$
fern init --mintlify PATH_TO_MINT_CONFIG

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

$
fern/
>
├─ fern.config.json # root-level configuration
>
├─ docs.yml # docs configuration
>
└─ ... # any other files / pages needed in your docs

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.

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

$
fern init --readme URL_TO_README_DOCS_SITE

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

$
fern/
>
├─ fern.config.json # root-level configuration
>
├─ docs.yml # docs configuration
>
└─ ... # any other files / pages needed in your docs

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

$
fern generate [--group <group>] [--api <api>] [--version <version>] [--preview]

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

$
# Preview all SDKs
>
fern generate --preview
>
>
# Preview specific SDK group
>
fern generate --group python-sdk --preview

group

Use --group <group> to filter to a specific group within generators.yml. Required unless you have a default-group declared.

$
fern generate --group internal

api

Use --api <api> to specify the API for SDK generation.

$
fern generate --api public-api

version

Use --version to specify a version for SDKs and documentation. Adherence to semantic versioning is advised.

$
fern generate --version 2.11

Use fern check to validate your API definition and Fern configuration: fern.config.json, generators.yml, and docs.yml.

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

$
fern check [--api <api>] [--warnings]

api

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

$
fern check --api public-api

warnings

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

$
fern check --warnings

strict-broken-links

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

$
fern check --strict-broken-links

Usage in a GitHub Action

1
name: Fern Validation Check
2
3
on:
4
  pull_request:
5
  push:
6
    branches:
7
      - main
8
9
jobs:
10
  validate-fern-api:
11
    name: Validate using Fern's linter
12
    runs-on: ubuntu-latest
13
    steps:
14
      - name: Checkout repository
15
        uses: actions/checkout@v4
16
17
      - name: Install Fern CLI
18
        run: npm install -g fern-api
19
20
      - name: Validate API with Fern
21
        run: fern check

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

$
fern generate --docs [instance <instance-url>] [--preview]

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

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

$
fern docs dev [--port <port-number>]

port

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

$
fern docs dev --port 57908

Use fern upgrade to upgrade your compiler version in fern.config.json to the latest version. It will also upgrade generators in generators.yml to their minimum-compatible versions.

$
fern upgrade

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

$
fern login [--device code]

device-code

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

$
fern login --device-code

Use fern token to generate a FERN_TOKEN specific to your organization defined in fern.config.json. Use the token to authenticate with the API in CI. Tokens do not expire.

$
fern token

GitHub Actions

If using GitHub Actions as your CI, add the FERN_TOKEN as a GitHub Action secret in your Fern configuration repo. You can then reference the secret in your CI:

1
- name: Generate and Publish Documentation with Fern
2
  env:
3
      FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
4
  run: fern generate --docs

See the full example on GitHub.

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.

$
fern write-definition [--api <api>]

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

$
fern/
>
├─ fern.config.json
>
├─ generators.yml
>
└─ openapi/
>
    └─ openapi.json
>
  └─ .definition/ # <--- your Fern Definition
>
    └─ api.yml
>
    └─ __package__.yml

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.

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

$
fern write-overrides [--api <api>] [--exclude-models]

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

$
fern/
>
├─ fern.config.json
>
├─ generators.yml
>
└─ openapi/
>
    └─ openapi-overrides.yaml # <--- your overrides file
>
    └─ openapi.json

api

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

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

$
fern write-overrides --exclude-models

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

$
fern generator upgrade [--list] [--generator <generator-name>] [--group <group>]

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:

┌───────────────────────────────────────────────────────────────────────────────────┐
│                                                                                   │
│                                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.

$
fern generator upgrade --list

generator

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

$
fern generator upgrade --generator fernapi/fern-typescript-node-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.

$
fern generator upgrade --group public