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:
For Fern Definition initialization (without OpenAPI), you’ll see this structure:
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 generate to run the Fern compiler and create SDKs for your API.
Use --preview to test SDK changes locally before publishing. This is especially useful during development:
.preview/ folderUse --group <group> to filter to a specific group within generators.yml. Required unless you have a default-group declared.
Use --api <api> to specify the API for SDK generation.
Use --version to specify a version for SDKs and documentation. Adherence to semantic versioning is advised.
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.
Use --api <api> to specify which API you’d like to check.
Use --warnings to log warnings in addition to errors.
Use --strict-broken-links to fail the command if any broken links are found in your API docs.
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 fern docs dev to run a local development server to preview your docs.
Use --port <port-number> to specify the port the docs preview will be run on.
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. Logging in allows you
join GitHub organizations, gain permissions, and contribute to projects.
Use --device-code to login via device code authorization.
To enable CI/CD, use 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.
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:
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.
When run, this command creates a new folder within fern/ called .definition/.
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:
.definition/ folder to definition/.openapi/ folder. For example, you can rename it to .openapi/.Use --api to specify the API to write the definition for if you have multiple defined in your fern/apis/ folder.
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 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.
This is different from fern upgrade which updates the Fern CLI version. Use both commands to keep your entire Fern toolchain up to date.