General 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>] [--grpc] [--proto <path>]

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

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

grpc

Use --grpc to initialize a sample gRPC service and a generators.yml that generates a C# SDK. See gRPC.

fern init --grpc

proto

Use --proto to initialize from your own .proto file or a directory of them. The files are copied into fern/proto/.

fern init --proto ./proto

--grpc and --proto cannot be combined with each other or with --openapi, --fern-definition, --docs, --mintlify, or --readme.

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:

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.

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:

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:

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.

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

api

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

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

indent

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

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

audience

Use --audience to export only the endpoints, webhooks, and environments tagged for an audience, along with the types they reference. This produces a filtered spec, such as a public-only spec without internal endpoints. Tag API elements with audiences in the Fern Definition or x-fern-audiences in OpenAPI. Without --audience, the full API is exported.

fern export --audience public path/to/openapi.yml

Repeat the flag to export the union of multiple audiences:

fern export --audience public --audience internal path/to/openapi.yml

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

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.

check:
  rules:
    broken-links: error
    example-validation: warn
    missing-redirects: error

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

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

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

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.

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.

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

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.

fern logout

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

Use fern whoami to see which credential the CLI acts as in the current directory. Running it before generating or publishing confirms which account or API key a permission error applies to.

fern whoami
fern whoami --json

The report shows which login is in use:

• Organization token: a FERN_TOKEN environment variable is set. It takes precedence over a saved login.
• User login: a credential saved by fern login, shown with the account’s email (or username) and user ID. If Fern can’t verify the saved login, for example because it expired, the report says so and suggests running fern login again.
• Not logged in: neither a FERN_TOKEN nor a saved login is present.

If the repo has a guest session saved by fern generate --guest, the report also shows its session ID, organization, and expiry, plus the claim link while the session is live. An expired guest session is replaced by the next fern generate --guest run.

fern whoami always runs on the installed CLI, even in projects whose fern.config.json pins an older CLI version.

json

Use --json to print the report as a JSON object, for scripts and CI checks. The login.kind field is user, user-unverified, organization-token, or none. The guestSession field is present only when the repo has a saved guest session, and never includes the session token.

fern whoami --json

{
  "login": {
    "kind": "user",
    "userId": "<user-id>",
    "username": "<username>",
    "email": "user@example.com"
  },
  "guestSession": {
    "sessionId": "<session-id>",
    "organizationId": "<organization-id>",
    "expiresAt": "2026-11-12T00:00:00.000Z",
    "claimUrl": "<claim-url>",
    "live": true,
    "venusOrigin": "https://venus.buildwithfern.com"
  }
}

Use fern claim to keep the work published from a guest session. Run it after fern login in the repo that ran fern generate --guest; by default it turns the guest organization into your own, or pass --org to move the site into an organization you administer.

fern claim [--org <organization>]

The claim link printed by fern generate --guest does the same from the Fern Dashboard.

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. The key appears in fern org token list and on the API keys page in the Dashboard, and can be revoked from either. To name the key or manage existing keys, use the fern org token commands.

Generating an API key requires the Admin role in the organization. Members with the Editor or Viewer role receive a Failed to create token because you do not have the required permissions error and need an Admin to generate the key for them.

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.

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.

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.

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.

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.

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.

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

Use fern org token list to list your organization’s API keys, including revoked and expired keys. Each row shows the key’s name, token ID, status, creator, creation time, and last use. The secret value isn’t included; it’s shown only once, at creation.

The fern org token commands require a user session from fern login. They reject an organization API key set as FERN_TOKEN, so unset FERN_TOKEN before running them. Any member of the organization can list keys.

fern org token list [--json] [--csv] [--org <org>]

json

Use --json to output the keys as a JSON array with ISO 8601 timestamps.

fern org token list --json

csv

Use --csv to export the keys as CSV, for example to audit them in a spreadsheet. The columns are Name, Token ID, Status, Created by, Created at, and Last used at.

fern org token list --csv > api-keys.csv

org

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

fern org token list --org my-org

Use fern org token create to create an organization API key for CI/CD. Requires the Admin role.

fern org token create [--description <description>] [--json] [--org <org>]

The CLI prints the token ID and the secret. The secret is shown only once, so store it immediately (for example as a FERN_TOKEN secret in your CI/CD provider). Only the secret goes to stdout, so it can be piped:

fern org token create --description "GitHub Actions" | gh secret set FERN_TOKEN

description

Use --description to name the key. In an interactive terminal, the CLI prompts for an optional description when the flag is omitted.

json

Use --json to output { "tokenId": ..., "token": ... }.

org

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

Use fern org token revoke to revoke an API key by its token ID, which fern org token list shows. Revoked keys stop working immediately and can’t be restored. Requires the Admin role.

fern org token revoke <token-id> [--json]

json

Use --json to output { "success": true, "tokenId": ... }.