> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://fern.ferndocs.app/learn/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://fern.ferndocs.app/_mcp/server. # Commands > Complete reference for all Fern CLI commands for generating SDKs and developer documentation. | Command | Description | | ------------------------------- | ---------------------------------------------------- | | [`fern init`](#fern-init) | Create new Fern project from OpenAPI spec or scratch | | [`fern check`](#fern-check) | Validate API definition & configuration | | [`fern upgrade`](#fern-upgrade) | Update Fern CLI & generators to latest versions | ## Documentation Commands | Command | Description | | ----------------------------------------------- | -------------------------------------- | | [`fern docs dev`](#fern-docs-dev) | Run local documentation preview server | | [`fern generate --docs`](#fern-generate---docs) | Build & publish documentation updates | ## SDK Generation Commands | Command | Description | | --------------------------------------------------- | ---------------------------------------------------------------------------------------- | | [`fern generate`](#fern-generate) | Build & publish SDK updates | | [`fern write-definition`](#fern-write-definition) | Convert OpenAPI specifications to [Fern Definition](/learn/api-definition/fern/overview) | | [`fern write-overrides`](#fern-write-overrides) | Create OpenAPI customizations | | [`fern generator upgrade`](#fern-generator-upgrade) | Update SDK generators to latest versions | ## 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. #### terminal ```bash fern init [--docs] [--openapi ] ``` When initializing with OpenAPI, your project structure will look like this: ```bash 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: ```bash 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: ```bash # 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. ```bash fern init --docs ``` The file added will contain: ```yaml docs.yaml 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`](/learn/cli-api/cli-reference/commands#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. ```bash fern init --mintlify PATH_TO_MINT_CONFIG ``` The CLI will create a `fern/` folder with the following structure: ```bash fern/ ├─ fern.config.json # root-level configuration ├─ docs.yml # docs configuration └─ ... # any other files / pages needed in your docs ``` ### readme By adding `--readme URL_TO_README_DOCS_SITE`, the CLI will automatically convert the Readme generated docs site into a Fern docs site. ```bash fern init --readme URL_TO_README_DOCS_SITE ``` The CLI will create a `fern/` folder with the following structure: ```bash 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](/learn/docs/getting-started/quickstart) #### fern generate Use `fern generate` to run the Fern compiler and create SDKs for your API. #### terminal ```bash fern generate [--group ] [--api ] [--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 ```bash # Preview all SDKs fern generate --preview # Preview specific SDK group fern generate --group python-sdk --preview ``` ### group Use `--group ` to filter to a specific group within `generators.yml`. Required unless you have a `default-group` declared. ```bash fern generate --group internal ``` ### api Use `--api ` to specify the API for SDK generation. ```bash fern generate --api public-api ``` ### version Use `--version` to specify a version for SDKs and documentation. Adherence to [semantic versioning](https://semver.org/) is advised. ```bash 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. #### terminal ```bash fern check [--api ] [--warnings] ``` ### api Use `--api ` to specify which API you'd like to check. ```bash fern check --api public-api ``` ### warnings Use `--warnings` to log warnings in addition to errors. ```bash fern check --warnings ``` ### strict-broken-links Use `--strict-broken-links` to fail the command if any broken links are found in your API docs. ```bash fern check --strict-broken-links ``` ## Usage in a GitHub Action #### .github/workflows/fern-check.yml ```yml maxLines=14 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 ``` #### fern generate --docs Use `fern generate --docs` to create a documentation site for your API. #### terminal ```bash fern generate --docs [instance ] [--preview] ``` ### instance Use `--instance` to specify which instance URL in your `docs.yml` to generate documentation for. ```bash 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. ```bash fern generate --docs --preview ``` #### fern docs dev Use `fern docs dev` to run a local development server to preview your docs. #### terminal ```bash fern docs dev [--port ] ``` ### port Use `--port ` to specify the port the docs preview will be run on. ```bash 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. #### terminal ```bash fern upgrade ``` #### 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. #### terminal ```bash fern login [--device code] ``` ### device-code Use `--device-code` to login via device code authorization. ```bash fern login --device-code ``` To enable CI/CD, use [`fern token`](/learn/cli-api/cli-reference/commands#fern-token). #### 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. #### terminal ```bash fern token ``` ## GitHub Actions If using GitHub Actions as your CI, add the `FERN_TOKEN` as a [GitHub Action secret](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository) in your Fern configuration repo. You can then reference the secret in your CI: ```yaml - name: Generate and Publish Documentation with Fern env: FERN_TOKEN: ${{ secrets.FERN_TOKEN }} run: fern generate --docs ``` See [the full example on GitHub](https://github.com/fern-api/fern/blob/main/.github/workflows/publish-docs.yml). #### 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. #### terminal ```bash fern write-definition [--api ] ``` When run, this command creates a new folder within `fern/` called `.definition/`. ```bash {6-8} fern/ ├─ fern.config.json ├─ generators.yml └─ openapi/ └─ openapi.json └─ .definition/ # <--- your Fern Definition └─ api.yml └─ __package__.yml ``` If you do not see the `.definition/` folder, use the appropriate command or configuration to view hidden folders (`ls -a` in `bash` and `zsh`). 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. ```bash 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. #### terminal ```bash fern write-overrides [--api ] [--exclude-models] ``` When run, this command creates a new file within `fern/openapi/` called `openapi-overrides.yml`. ```bash {5} 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. ```bash 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). ```bash fern write-overrides --exclude-models ``` #### fern generator upgrade Use `fern generator upgrade` to update all generators in your `generators.yml` to their latest versions. #### terminal ```bash fern generator upgrade [--list] [--generator ] [--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: ```plaintext ┌───────────────────────────────────────────────────────────────────────────────────┐ │ │ │ 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. ```bash fern generator upgrade --list ``` ### generator Use `--generator` to specify a particular generator type to upgrade. ```bash 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. ```bash fern generator upgrade --group public ``` This is different from `fern upgrade` which updates the Fern CLI version. Use both commands to keep your entire Fern toolchain up to date.