Publishing | Fern Documentation

Early access

The CLI generator is in early access. Reach out to get started.

Publish your generated CLI to npm. After following the steps on this page, each tagged release builds cross-platform binaries and publishes them automatically. Homebrew and GitHub Releases distribution are coming soon. To keep generation on your own infrastructure, you can self-host the generator instead of using Fern’s cloud.

This page assumes that you have:

An initialized fern folder with generators.yml configured for the CLI generator. See Quickstart.
An existing GitHub repository for the generated CLI source, with the Fern GitHub App installed on it.

Configure output location

Set the output location to npm

In the group for your CLI, set the output location to npm:

generators.yml

1 groups:
2   cli:
3     generators:
4       - name: fern-cli-generator
5         version: 0.23.4
6         output:
7           location: npm
8         config:
9           binaryName: my-cli

Add a unique package name

The package name must be unique in the npm registry.

generators.yml

1 groups:
2   cli:
3     generators:
4       - name: fern-cli-generator
5         version: 0.23.4
6         output:
7           location: npm
8           package-name: "@myorg/my-cli"
9         config:
10           binaryName: my-cli

Configure GitHub publishing

Fern publishes your CLI via GitHub Actions. Configure your GitHub repository and publishing mode:

generators.yml

1 groups:
2   cli:
3     generators:
4       - name: fern-cli-generator
5         version: 0.23.4
6         output:
7           location: npm
8           package-name: "@myorg/my-cli"
9         config:
10           binaryName: my-cli
11         github:
12           repository: my-org/my-cli
13           mode: release

The repository owner is independent of your Fern organization (the --organization value passed to fern init). Point it at the GitHub user or organization that owns the target repository.

Mode	Behavior
`release`	Commits to the default branch and tags a release. The CI workflow builds binaries and publishes automatically.
`pull-request`	Opens a PR with generated source for review. Merge the PR and create a GitHub release to trigger publishing.

Configure authentication

Choose how to authenticate with npm when publishing.

OIDC authentication (Recommended)

OIDC-based publishing (trusted publishing) is the most secure option. npm trusts your GitHub repository to publish directly — no tokens to manage.

Add OIDC to generators.yml

Set token: OIDC in the output section:

generators.yml

1 groups:
2   cli:
3     generators:
4       - name: fern-cli-generator
5         version: 0.23.4
6         output:
7           location: npm
8           package-name: "@myorg/my-cli"
9           token: OIDC
10         config:
11           binaryName: my-cli
12         github:
13           repository: my-org/my-cli
14           mode: release

Create the packages on npm

The CI workflow publishes one launcher package and one package per platform. For a package named @myorg/my-cli, that’s:

Package	Contents
`@myorg/my-cli`	Node.js launcher
`@myorg/my-cli-linux-x64`	Linux x86_64 binary
`@myorg/my-cli-linux-arm64`	Linux ARM64 binary
`@myorg/my-cli-darwin-x64`	macOS Intel binary
`@myorg/my-cli-darwin-arm64`	macOS Apple Silicon binary
`@myorg/my-cli-win32-x64`	Windows x86_64 binary

OIDC can’t perform a package’s first publish; npm requires a package to exist before you can add a trusted publisher. Run the following script to create and publish a placeholder for each package:

$ npm login
$ 
$ PACKAGE_NAME="@myorg/my-cli"
$ ACCESS="public" # or "restricted" for private packages
$ 
$ for pkg in \
>   "$PACKAGE_NAME" \
>   "$PACKAGE_NAME-linux-x64" \
>   "$PACKAGE_NAME-linux-arm64" \
>   "$PACKAGE_NAME-darwin-x64" \
>   "$PACKAGE_NAME-darwin-arm64" \
>   "$PACKAGE_NAME-win32-x64"
$ do
$   dir="$(mktemp -d)"
$   echo "{ \"name\": \"$pkg\", \"version\": \"0.0.0\" }" > "$dir/package.json"
$   npm publish "$dir" --access "$ACCESS"
$ done

Authorize your repository on npmjs.com

Configure trusted publishing on npmjs.com. Repeat this for every package listed above — an OIDC run fails on any package that has no trusted publisher.

Open the package page on npmjs.com and go to the Settings tab
Find the Trusted Publisher section and click Add trusted publisher
Select GitHub Actions as your provider
Fill in:
- Organization or user: Your GitHub username or organization
- Repository: Your CLI repository name (e.g. my-cli)
- Workflow filename: ci.yml
- Environment name: Leave blank
Under Allowed actions, select Allow npm publish

Generate the CLI

Generate the CLI to create the GitHub Actions workflow with OIDC configuration:

$ fern generate --group cli

This creates a .github/workflows/ci.yml file configured for OIDC npm publishing. In release mode, it also tags a release, which triggers the first publish run over the placeholder versions.

Token-based authentication

Generate an npm token

Log into npmjs.com
Click your profile picture and select Access Tokens
Click Generate New Token and create a granular access token
Give it Read and Write access to All packages
Save your token securely

Add token to generators.yml

Set token: ${NPM_TOKEN} in the output section:

generators.yml

1 groups:
2   cli:
3     generators:
4       - name: fern-cli-generator
5         version: 0.23.4
6         output:
7           location: npm
8           package-name: "@myorg/my-cli"
9           token: ${NPM_TOKEN}
10         config:
11           binaryName: my-cli
12         github:
13           repository: my-org/my-cli
14           mode: release

Add NPM_TOKEN as a GitHub Actions secret

Open your CLI repository on GitHub and go to Settings
Navigate to Secrets and variables > Actions
Click New repository secret
Name it NPM_TOKEN and paste your npm token
Click Add secret

Publish your CLI

How you trigger a publish depends on your mode:

In release mode, fern generate --group cli commits the updated source and tags a release. The tag triggers the CI workflow (no manual release step).
In pull-request mode, fern generate --group cli opens a PR. Merge it, then create a GitHub release with a version tag (e.g. v1.0.0) to trigger publishing.

The CI workflow then builds binaries for all platforms and publishes to npm.

Build targets

The CI workflow produces statically linked binaries for:

Target	OS	Architecture
`x86_64-unknown-linux-gnu`	Linux	x86_64
`aarch64-unknown-linux-gnu`	Linux	ARM64
`x86_64-apple-darwin`	macOS	Intel
`aarch64-apple-darwin`	macOS	Apple Silicon
`x86_64-pc-windows-msvc`	Windows	x86_64

The npm package wraps the native binary with a Node.js launcher. Platform-specific optional dependencies ensure only the correct binary downloads at install time.

Install instructions for users

After publishing, direct users to install with npm:

$ npm install -g @myorg/my-cli