Get started

Configuration reference

Beta
View as Markdown
Early access

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

Configure the CLI generator in generators.yml. Options nested under config are specific to the CLI generator. The rest (output, github, audiences, smart-casing, metadata, api) behave the same way as for SDK generators.

generators.yml
1groups:
2  cli:
3    generators:
4      - name: fern-cli-generator
5        version: 0.28.0
6        config:
7          binaryName: my-cli
8          customCommands: true
9        github:
10          repository: my-org/my-cli
11          mode: pull-request

config options

binaryName
string

Name of the compiled binary. Determines the executable filename, the Cargo [[bin]] target name, and the environment-variable prefix used for TLS, proxy, and logging settings.

When omitted, the generator derives the name from the API definition’s display name (kebab-cased). Multi-spec workspaces must set this field explicitly — there is no sensible auto-derivation when multiple specs are present.

generators.yml
1config:
2  binaryName: contoso

The binary name contoso produces:

  • Executable: contoso
  • Env-var prefix: CONTOSO (e.g. CONTOSO_CA_BUNDLE, CONTOSO_LOG)
customCommands
booleanDefaults to true

Controls whether the generator produces the custom command infrastructure alongside the CLI binary. When enabled, the output includes:

  • A <binaryName>-types library crate (typed serde structs)
  • A <binaryName>-sdk library crate (HTTP client accessible via ctx.client())
  • Scaffolding files for user-authored command handlers

Set to false to produce a spec-only CLI with no custom command support.

generators.yml
1config:
2  customCommands: false
userAgentSuffixFlag
stringDefaults to user-agent-suffix

Renames the global flag (and its derived environment variable) that a downstream consumer uses to append a product token to the generated CLI’s User-Agent. Provide the flag’s long name without the leading --. It must be a kebab identifier matching ^[a-z][a-z0-9-]*$ and can’t collide with a built-in flag name.

Any kebab identifier is accepted except the CLI’s built-in flag names (params, output, json, format, dry-run, base-url, page-all, page-limit, page-delay, no-pager, no-extract, no-retry, no-stream, quiet, query, help, debug, schema). The default user-agent-suffix exposes --user-agent-suffix and <NAME>_USER_AGENT_SUFFIX. For example, setting via exposes --via and <NAME>_VIA instead (the environment variable is <NAME>_ followed by the flag uppercased with hyphens converted to underscores):

generators.yml
1config:
2  userAgentSuffixFlag: via

A consumer of the generated contoso CLI then appends its product token with the renamed flag:

$contoso plants list --via "partner-app/3.1"
$# sends User-Agent: contoso-cli/1.4.0 partner-app/3.1

Publishing & delivery

output

Configures where to publish the generated CLI. The CLI generator supports npm and local-file-system output locations. For the full publishing workflow (OIDC auth, CI builds, Homebrew tap), see Publishing. For Docker-based generation on your own machine, see Self-hosted generation.

Publish the CLI as an npm package. Users install with npm install -g @myorg/my-cli or npx @myorg/my-cli.

generators.yml
1groups:
2  cli:
3    generators:
4      - name: fern-cli-generator
5        version: 0.28.0
6        output:
7          location: npm
8          package-name: "@myorg/my-cli"
9          token: "${NPM_TOKEN}"
10        config:
11          binaryName: my-cli

Write the generated Rust project to a local directory for manual building and distribution.

generators.yml
1groups:
2  cli:
3    generators:
4      - name: fern-cli-generator
5        version: 0.28.0
6        output:
7          location: local-file-system
8          path: ../my-cli
9        config:
10          binaryName: my-cli

github

Specifies how generated CLI code is delivered to your repository. Supports the same modes as SDKs: release, pull-request, and push.

generators.yml
1groups:
2  cli:
3    generators:
4      - name: fern-cli-generator
5        version: 0.28.0
6        config:
7          binaryName: my-cli
8        github:
9          repository: my-org/my-cli
10          mode: release
ModeBehavior
releaseCommits to the default branch and tags a new release. Triggers CI workflows that build and publish the binary.
pull-requestOpens a PR with the generated source for review before merging.
pushPushes directly to the specified branch. Requires branch field.

Command generation

audiences

Filter which API endpoints are included in the generated CLI based on audience tags. Only endpoints tagged with the specified audiences in your API spec (via x-fern-audiences) produce commands. Without this filter, all endpoints generate commands.

generators.yml
1groups:
2  cli:
3    audiences: ["external"]
4    generators:
5      - name: fern-cli-generator
6        version: 0.28.0
7        config:
8          binaryName: my-cli

smart-casing

Enables intelligent case conversion that preserves numbers and common programming patterns in generated command and flag names.

generators.yml
1groups:
2  cli:
3    generators:
4      - name: fern-cli-generator
5        version: 0.28.0
6        smart-casing: true
7        config:
8          binaryName: my-cli

api

Override authentication settings at the generator level. This uses the same schema as the SDK generator-level api.auth to control which auth schemes the CLI uses.

generators.yml
1groups:
2  cli:
3    generators:
4      - name: fern-cli-generator
5        version: 0.28.0
6        api:
7          auth: BearerAuth
8        config:
9          binaryName: my-cli

metadata

Attach package metadata to the generated CLI for use in published artifacts.

generators.yml
1groups:
2  cli:
3    generators:
4      - name: fern-cli-generator
5        version: 0.28.0
6        metadata:
7          package-description: "CLI for the Contoso API"
8          author: "Contoso Inc."
9          reference-url: "https://docs.contoso.com/cli"
10        config:
11          binaryName: contoso