CLI reference

General commands

Commands that apply across SDKs and docs.

View as Markdown

These commands apply to every Fern project, whether it publishes docs, SDKs, or both. They create and validate a project, authenticate the CLI, update your API definition, and set the CLI version your organization runs. Each one accepts the global options.

CommandDescription
fern initCreate new Fern project from OpenAPI spec or scratch
fern checkValidate API definition & configuration
fern upgradeUpdate Fern CLI & generators to latest versions
fern downgradeMove the Fern CLI version in fern.config.json back to an older version
fern loginLogin to Fern CLI via GitHub, Google, Postman, or enterprise SSO
fern logoutLog out of the Fern CLI
fern tokenGenerate an organization-scoped API key for CI/CD
fern exportExport an OpenAPI spec for your API
fern api updateManually update your OpenAPI spec
fern api enrichMerge x-fern-examples from an overrides file into native OpenAPI examples
fern org getView your organization’s CLI version policy
fern org set cli-versionSet a minimum, maximum, or exact CLI version for your organization
fern org unset cli-versionClear your organization’s CLI version policy

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.

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

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://petstore3.swagger.io/api/v3/openapi.json

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:

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

For more information on getting started, check out our Quickstart Guide

Use fern export to generate an OpenAPI spec for your API. This is useful when you’ve defined your API in a format other than OpenAPI (such as the Fern Definition) and need to export it for integration with other tools or services.

The path argument is the output file to write. Use a .yml or .json extension to choose the format of the generated spec.

terminal
$# Write the exported spec as YAML
$fern export [--api <api>] path/to/openapi.yml
$
$# ...or as JSON
$fern export [--api <api>] path/to/openapi.json

api

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

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

indent

Use --indent to set the indentation size, in spaces, of the generated spec.

terminal
$fern export --indent 4 path/to/openapi.yml

The --broken-links and --strict-broken-links flags are deprecated. Use the broken-links validation rule in docs.yml instead.

Use fern check to validate your API definition and Fern configuration, including fern.config.json, 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.

Most fern check rules — including broken-links — validate against the navigation tree built from your local config and do not crawl your live deployed site or follow external URLs. The exception is the missing-redirects rule, which compares your local navigation against the previously published state and therefore requires fern login or FERN_TOKEN.

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

You can configure the severity of the validation rules run by fern check in your docs.yml file using the check.rules property.

docs.yml
1check:
2  rules:
3    broken-links: error
4    example-validation: warn
5    missing-redirects: error

To check links on a published site, use fern docs link check or the link checker in the Fern Dashboard instead.

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

Usage in a GitHub Action

.github/workflows/fern-check.yml
1name: Fern Validation Check
2
3on:
4  pull_request:
5  push:
6    branches:
7      - main
8
9jobs:
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 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.

terminal
$fern upgrade [--version <version>] [--from <version>] [--yes]

When your organization sets a CLI version policy, fern upgrade writes the highest version the policy allows rather than the latest published version. A --version below the organization’s minimum is raised to the minimum.

version

Use --version to upgrade to a specific published version of the fern-api package instead of the latest release. The version must be ahead of the version in fern.config.json; use fern downgrade to move to an older version.

$fern upgrade --version 5.45.0

from

Use --from to set the version that migrations run from. Fern infers this from fern.config.json and git history; pass it when that inference is wrong, such as after fern.config.json was edited by hand.

$fern upgrade --from 4.20.0

yes

Use --yes (-y) to answer yes to every migration prompt, for non-interactive environments like CI.

$fern upgrade --yes

Use fern downgrade to set the CLI version in fern.config.json to an older version. It rewrites the version field only: generator versions in generators.yml are left alone, and no migrations are reversed.

terminal
$fern downgrade <version>
$fern downgrade 5.40.0

A CLI version policy doesn’t block the downgrade, but it does override it: the new version is written to fern.config.json, and subsequent commands still run the minimum required by your organization.

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.

terminal
$fern login
$fern login --device-code
$fern login --email <email>

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

$fern login --device-code

email

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

$fern login --email user@example.com

To enable CI/CD, use fern token.

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.

terminal
$fern logout

After logging out, you’ll need to run fern login again to access protected features.

Use fern token to generate an API key for authenticating the Fern CLI in CI/CD environments. The API key is specific to your organization defined in fern.config.json and doesn’t expire. You can also create and manage API keys from the API keys page in the Dashboard.

terminal
$fern token

See Publishing your docs for instructions on using this API key in automated publishing workflows.

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.

terminal
$fern api update [--api <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.

terminal
$fern api update --api public-api

Use fern api enrich to convert AI-generated examples or manually authored x-fern-examples into portable OpenAPI examples that any OpenAPI-compatible tool can consume.

terminal
$fern api enrich <openapi> -f <overrides-file> -o <output-file>

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.
$# 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 → requestBody.content.*.example
  • response.body → responses.<status>.content.*.example

Use fern org get to view your organization’s CLI version policy.

terminal
$fern org get [--json] [--org <org>]

json

Use --json to output the raw cliVersionMin and cliVersionMax fields instead of a one-line description.

$fern org get --json

org

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

$fern org get --org my-org

Use fern org set cli-version to constrain the Fern CLI version used by every project in your organization. Requires an organization admin.

terminal
$fern org set cli-version [version] [--min <version>] [--max <version>] [--org <org>]
$# Pin an exact version
$fern org set cli-version 5.45.0
$
$# Set a minimum, a maximum, or both
$fern org set cli-version --min 5.40.0
$fern org set cli-version --max 5.50.0
$fern org set cli-version --min 5.40.0 --max 5.50.0

Each bound is an exact published version of the fern-api package.

org

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

$fern org set cli-version 5.45.0 --org my-org

Use fern org unset cli-version to remove your organization’s CLI version policy. Requires an organization admin.

terminal
$fern org unset cli-version [--min] [--max] [--org <org>]

Both bounds are removed by default. Pass --min or --max to clear one end and keep the other.

$fern org unset cli-version --max