Commands
Learn about the Fern CLI commands.
Use fern init to initialize a new Fern workspace in the current folder. By default, you’ll see the IMDb API example.
When initializing with OpenAPI, your project structure will look like this:
Use --openapi to initialize a project from an OpenAPI specification:
By adding --docs, you’ll also get a sample documentation website for your API with an API Reference section.
The file added will contain:
To publish the API docs, run fern generate --docs.
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.
The CLI will create a fern/ folder with the following structure:
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.
The CLI will create a fern/ folder with the following structure:
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.
Use --api to specify which API to export when you have multiple APIs defined in your fern/apis/ folder.
Use fern generate to run the Fern compiler and create SDKs for your API.
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 and map to multiple groups, allowing you to run several groups in parallel with a single command.
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, --preview for local testing, or --version to specify the SDK version.
Use --preview to test SDK changes locally before publishing. This is especially useful during development:
.preview/ folderUse --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.
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.
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.
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 for setup instructions.
A Docker daemon must be running on your machine, as SDK generation runs inside a Docker container.
By default, the CLI pulls generator images from Docker Hub. To pull from a custom container registry, use the image field in your generators.yml instead of name. See custom container registry for details.
Use --force to skip confirmation prompts during generation. This is useful in CI/CD environments where interactive prompts would block the pipeline.
Use --no-replay to skip Fern Replay’s patch detection and application phase for a single generation. The generation still produces the new SDK code, but tracked customization patches aren’t applied on top. Useful for a clean regeneration — for example, to debug whether a conflict is caused by a specific patch.
--no-replay works only for local generation (--local).
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.
You can configure the severity of the validation rules run by fern check in your docs.yml file using the check.rules property.
To check links on a published site, use fern docs link check or the link checker in the Fern Dashboard instead.
Use --api <api> to specify which API you’d like to check.
Use --warnings to log warnings in addition to errors.
Use fern generate --docs to create a documentation site for your API.
Use --instance to specify which instance URL in your docs.yml to generate documentation for.
Use --preview to preview updates to your documentation before publishing changes to your production site.
Use --id with --preview to create a stable, named preview link. The preview URL follows the format {org}-preview-{id}.docs.buildwithfern.com, so rerunning with the same --id updates the existing preview in place rather than creating a new one.
This is useful in CI workflows where you want one preview URL per pull request. See Preview changes for details.
When reusing an --id that already exists, Fern prompts you to confirm the overwrite. Use --force to skip the confirmation. This is detected automatically in GitHub Actions, but is needed for other CI environments like Azure Pipelines.
Use fern docs preview list to list all preview deployments for your organization.
Use --limit to specify the number of preview deployments to display per page.
Use --page to specify which page of results to display.
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.
Use fern docs dev to run a local development server to preview your docs.
On Windows, fern docs dev requires long path support to be enabled.
To enable long path support, run the following command in an elevated PowerShell prompt, then restart your terminal:
If you can’t enable long path support, use Windows Subsystem for Linux (WSL) to run fern docs dev in a Linux environment instead.
Use --port <port-number> to specify the port the docs preview will be run on.
Use fern docs link check to scan a live documentation site for broken links. The command crawls the published site, checks every link, and reports broken (404) and blocked (403) URLs along with their source pages.
Unlike the broken-links rule in fern check, which validates only internal links in your local YAML navigation tree, fern docs link check checks all links — internal and external — on your live deployed site.
By default, the command auto-detects your docs URL from the instances in docs.yml. When all links are valid, the command exits with a success message.
The command first scrapes every page on the site, then checks each link it finds. When broken links are found, the output includes a summary and a grouped list of broken URLs with status codes and source file paths.
Use --url to specify which docs site to check. This is useful when you have multiple instances or want to check a preview deployment.
Use --output to control the output format. Supported values are text (default), json, and csv.
Use fern docs md check to validate MDX syntax across all documentation pages referenced in your navigation configuration, including docs.yml, versioned configuration files, and product-specific YAML files.
The command parses each MDX file and reports syntax errors with file paths and line:column numbers. The command accounts for frontmatter offsets, so reported line numbers correspond to the actual lines in your file.
When all files are valid, you’ll see a success message:
Use fern docs diff to generate visual diffs between your preview deployment and production docs. This command is intended for use in GitHub Actions. It captures screenshots of both versions and creates side-by-side comparison images.
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.
Use --output to specify a custom directory for diff images.
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.
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.
By default, fern login opens a browser for GitHub, Google, or Postman authentication. Two alternative flows are available:
Use --device-code to login via device code authorization in environments where a browser cannot open automatically (e.g., SSH sessions or containers).
Use --email to login via enterprise SSO. Pass the email address associated with your organization’s SSO provider.
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.
After logging out, you’ll need to run fern login again to access protected features.
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 and doesn’t expire.
See Publishing your docs for instructions on using this token in automated publishing workflows.
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.
When run, this command creates a new file within fern/openapi/ called openapi-overrides.yml.
Use --api to specify the API to run the command on if multiple are defined.
Use --exclude-models to stub the models while generating the initial overrides (in addition to the endpoints).
Use fern generator upgrade to update all generators in your generators.yml to their latest versions.
This is different from fern upgrade which updates the Fern CLI version. Use both commands to keep your entire Fern toolchain up to date.
This command will:
generators.ymlHere’s what you might see when updates are available:
Use --list to see the full list of generator upgrades available.
Use --generator to specify a particular generator type to upgrade.
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.
Use --include-major to include major version upgrades. Major versions are skipped by default to prevent breaking changes.
Use fern replay resolve to work through patch conflicts that Fern Replay couldn’t merge cleanly during fern generate. The command runs in two phases: the first run applies unresolved patches to your working tree with standard merge markers (<<<<<<< / ======= / >>>>>>>) for you to edit; the second run verifies no markers remain and commits the resolved patches.
Path to the SDK directory containing .fern/replay.lock. Defaults to the current directory.
Skip the conflict-marker check before committing. Use with caution — committing files that still contain merge markers will break the next regeneration.
Use fern replay forget to remove tracked customization patches from .fern/replay.lock. Useful when the generator now supports a customization natively, or when you want to stop replaying a specific edit on future regenerations.
The command accepts three modes:
By patch ID. Pass one or more patch IDs to remove specific patches.
By search pattern. Pass a pattern to find matching patches. The command shows the matches with diff stats and prompts for confirmation before removing.
All patches. Pass --all to remove every tracked patch.
Show what would be removed without actually removing.
Skip confirmation prompts. Required in non-interactive or CI environments.
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.
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.
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.
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.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.*.exampleresponse.body → responses.<status>.content.*.exampleUse fern docs theme export to extract the theme-eligible fields from your docs.yml into a standalone directory. The exported theme.yml and its assets can then be uploaded with fern docs theme upload.
By default, files are written to ./fern/theme/.
Use --output to specify a custom directory for the exported theme.
Use fern docs theme upload to upload a theme to Fern’s registry. The command reads theme.yml from ./fern/theme/ and uploads it along with any referenced file assets.
Use --name to set the theme name. Defaults to default.
Use --org to override the organization ID from fern.config.json.
Use fern docs theme list to list all themes uploaded for your organization.
By default, outputs one theme name per line.
Use --json to output the full list as a JSON array, including updatedAt timestamps.
Use --org to override the organization ID from fern.config.json.