Commands

Documentation Commands

Generation Commands

Detailed Command Documentation

fern init

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

fern generate

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

fern check

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: - main
7
8
jobs:
9
validate-fern-api:
10
name: Validate using Fern's linter
11
runs-on: ubuntu-latest
12
steps: - name: Checkout repository
13
uses: actions/checkout@v4
14
15
      - name: Install Fern CLI
16
        run: npm install -g fern-api
17
18
      - name: Validate API with Fern
19
        run: fern check

fern generate --docs

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

fern docs dev

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

fern upgrade

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 login

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

--device-code

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

$
fern login --device-code

fern token

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.

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.

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.

$
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

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.

$
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

fern generator upgrade

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

fern export

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

$
fern export [--api <api>] <path>

--api

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

$
fern export --api public-api path/to/openapi.yml