Skip to navigation

Configuration reference

View as Markdown

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
groups:
cli:
generators:
- name: fern-cli-generator
version: 0.61.1
config:
binaryName: my-cli
customCommands: true
github:
repository: my-org/my-cli
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
config:
binaryName: contoso

The binary name contoso produces:

  • Executable: contoso
  • Env-var prefix: CONTOSO (e.g. CONTOSO_CA_BUNDLE, CONTOSO_LOG)
displayName
string

API name used in the generated README and reference.md titles (# <displayName> CLI) and in the crate’s default description. A name that already ends in “CLI” isn’t doubled: displayName: Acme CLI gives “Acme CLI”.

When omitted, a single-spec workspace uses the spec’s info.title. A multi-spec workspace uses a readable form of binaryName: twilio-cli gives “Twilio CLI”.

generators.yml
config:
displayName: Contoso
rootGroup
string

Mounts every spec-derived command under one top-level command, leaving the top level free for custom commands. Without it, generated commands are top-level (my-cli users list); with rootGroup: api, they become my-cli api users list.

generators.yml
config:
rootGroup: api
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
config:
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
config:
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
generateWireTests
booleanDefaults to false

Generates a wiremock-based integration test suite alongside the CLI. When enabled, generation emits a wire_test.rs harness and a wire-test-cases.json manifest with one case per endpoint example. Each test starts an in-process mock server, drives the compiled binary, and asserts the command hit the expected method and path and rendered the mocked response. The generated CI runs the suite with cargo test.

Only commands derived from the API spec are covered; custom commands aren’t.

generators.yml
config:
generateWireTests: true
splitTypeCrates
booleanDefaults to false

Splits the generated types into one crate per API, plus a shared core crate for types that more than one API references, nested inside <binaryName>-types/crates/. By default, every generated model lands in a single <binaryName>-types crate.

Enable it for workspaces with many specs, where that single crate is one rustc compilation unit large enough to exhaust the memory of a standard CI runner and get cargo build killed. Splitting also shortens builds, because the per-API crates compile in parallel and cache independently. <binaryName>-types remains as a facade that re-exports everything, so imports such as use plant_types::Plant; keep resolving and custom command handlers need no changes. The shipped artifact is the same either way: one binary with every spec embedded.

generators.yml
config:
binaryName: plant
splitTypeCrates: true
string | object

Prints a logo or wordmark above the root --help output. The banner is plain text, so any text art or Unicode block art works, including a logo converted from an image into block characters.

Store the art as an asset in your Fern config repository and reference it with file. Put brand colours in colors:

generators.yml
config:
binaryName: acme
banner:
file: ./assets/cli-banner.txt
colors: ["#2929CC", "#4949F2", "#30F2B1"]

For short text, set banner to a string (banner: "Acme CLI") or use text instead of file.

The banner shows only on root --help in an interactive terminal. It’s printed without colour when NO_COLOR is set or TERM=dumb, and omitted when output is piped. Subcommand help never shows it.

banner.file
string

Path to a text file containing the banner, relative to generators.yml (for example, fern/assets/cli-banner.txt next to fern/generators.yml). Fern reads the file at generation time and bakes its contents into the CLI, so edit the asset and regenerate to change the banner. Can’t be combined with text.

banner.text
string

The banner inline, typically as a YAML block scalar (text: |). Can’t be combined with file.

banner.colors
string[]

Six-digit hex colours such as "#4949F2". One colour renders the banner solid; two or more render a gradient through each colour in order, along direction. Ignored when the art already contains terminal colour escape codes, which are printed as given, so you can colour a logo character by character.

banner.direction
stringDefaults to horizontal

Axis the colors gradient runs along: horizontal (left to right), vertical (top to bottom), or diagonal (top-left to bottom-right).

banner.lineColors
string[]

One solid hex colour per line of the banner, in order. Lines past the end of the list reuse its last colour. Use this for striped or two-tone wordmarks instead of a gradient. Can’t be combined with colors.

generators.yml
config:
banner:
file: ./assets/cli-banner.txt
lineColors: ["#2929CC", "#2929CC", "#4949F2", "#4949F2", "#30F2B1", "#30F2B1"]
banner.animate
booleanDefaults to false

When true, root --help in an interactive terminal plays a short shimmer across the banner, then prints it statically. Pipes, captured output, NO_COLOR, TERM=dumb, and terminals too small for the banner skip the animation.

profiles
object

Adds named profiles to the generated CLI: a top-level profiles subcommand group, a global --profile / -p flag, and a <binaryName>_PROFILE environment variable. A profile stores a tenant’s credential, parameter defaults, server URL variables, base URL, retry limit, and default output format once, so users of multi-tenant APIs don’t pass an account identifier on every command.

Off by default. A CLI generated without this block is byte-identical to one generated before the option existed, and a profiles block with enabled unset or false is a no-op.

generators.yml
config:
binaryName: acme
profiles:
enabled: true
profiles.enabled
booleanDefaults to false

Emits the profiles surface. Enabling it adds a top-level subcommand group and a global flag to an existing CLI, which is a surface change for its users.

profiles.commandName
stringDefaults to profiles

Name of the top-level subcommand group. Must start with a lowercase letter and contain only [a-z0-9-], and can’t be one of the built-in groups (auth, completion, man, errors, generate-skills, help). Rename it (for example, to tenants or accounts) when that reads better for your API. If your spec already declares a profiles resource, the built-in subcommands are folded into that group rather than colliding with it, so renaming is optional.

profiles.revokeOperation
string

Dotted command path of an operation that revokes a profile’s remote credential, such as iam.keys.remove. When set, profiles remove gains a --revoke flag that calls the operation before deleting the profile locally. The operation is invoked with the profile’s stored parameters as its arguments, so any parameter it requires must be set on the profile. When omitted, the flag isn’t registered.

profiles.provisionOperation
object

An operation that mints a profile’s remote credential (an API key), and how its response maps onto that credential. When set, profiles create gains a --provision flag that calls the operation with the credentials already in the caller’s environment and stores the mapped response fields in the OS keychain without printing the secret. In an interactive terminal, it also turns on the guided API-key flow for auth login and profiles create. Paired with revokeOperation, a profile owns its API key end to end: minted by profiles create --provision or the guided flow, revoked by profiles remove --revoke. When omitted, the flag isn’t registered and the guided flow is off.

generators.yml
config:
binaryName: acme
profiles:
enabled: true
revokeOperation: iam.keys.remove
provisionOperation:
operation: iam.keys.create
credential:
username: sid
password: secret
revokeParameters:
Sid: sid
flag: api-key
parameters:
FriendlyName: "{cli} for {user} on {host}"
profileParameters:
AccountSid: username
profiles.provisionOperation.operation
stringRequired

Dotted command path of the operation that creates the credential, in the form <resource>.<method> (for example, iam.keys.create). Like revokeOperation, it’s invoked with the profile’s stored parameters as its arguments.

profiles.provisionOperation.credential
map<string, string>Required

Maps each credential field to the top-level response field that supplies it. The keys are the halves the auth scheme stores: username and password for basic auth, client_id and client_secret for OAuth2 client credentials, and token for a single-value scheme. At least one field must be mapped, and keys and values may contain only [A-Za-z0-9_.-].

profiles.provisionOperation.revokeParameters
map<string, string>

Maps each parameter the revokeOperation takes to the response field it’s read from, such as Sid: sid to record the new key’s ID. The values are stored on the profile as credential_parameters and used only by profiles remove --revoke, never as request defaults. They’re kept in plaintext profile metadata and shown by profiles show, so map identifiers here, never secrets. Without revokeParameters, the profile has no record of which key it owns, and --revoke can only pass the profile’s own parameters.

profiles.provisionOperation.flag
stringDefaults to provision

Long name of the profiles create flag that mints a key, without the leading dashes. Must start with a lowercase letter and contain only [a-z0-9-]. Set api-key to expose --api-key; --provision stays accepted as a hidden alias, so existing scripts keep working.

profiles.provisionOperation.parameters
map<string, string>

Extra request values sent with the provisioning operation, such as a label for the new key. Values may contain these placeholders, substituted at request time:

  • {cli}: the CLI’s binary name
  • {profile}: the name of the profile being created
  • {user}: the local username (USER, or USERNAME on Windows)
  • {host}: the machine’s short hostname

A parameter the profile already sets takes precedence over the configured value. Values can’t contain quotes, backslashes, or control characters.

profiles.provisionOperation.profileParameters
map<string, string>

Maps each profile parameter to the credential field it’s copied from when the credential is typed in the guided flow, such as AccountSid: username to save the account ID the user entered. Requests keep targeting that account after the typed credential is replaced by the provisioned key. A value passed with --set takes precedence. Keys and values may contain only [A-Za-z0-9_.-].

packageIdentity
object

Sets the Cargo [package] metadata of the generated crate. cargo-dist names the GitHub Release archives and the shell and PowerShell installers after name, and the installers download archives from the releases of repository. When the generator delivers to a GitHub repository through the github block, unset name, repository, and homepage default from that repository, so the installers work without any packageIdentity config. Without the github block, the crate keeps Fern’s template identity (fern-cli-sdk, https://github.com/fern-api/cli-sdk), and authors and keywords keep Fern’s values in every mode. Explicit values always take precedence over these defaults.

generators.yml
config:
binaryName: plant
packageIdentity:
name: plant-cli
description: Command-line interface for the Plant API.
license: MIT
repository: https://github.com/garden/plant-cli
homepage: https://example.com
authors: ["Plants <support@garden-plants.com>"]
keywords: ["plants", "cli"]
packageIdentity.name
string

Crate name. Must be a valid cargo crate name: it starts with a letter and contains only letters, digits, -, and _. Invalid values fail at generation time with a config error instead of surfacing later as a manifest error during cargo build. The generator renames the matching Cargo.lock entry in the same pass, so cargo build --locked still resolves the workspace member.

For GitHub output, defaults to binaryName when that’s a valid crate name of at most 64 characters and doesn’t collide with a crate already in the generated Cargo.lock; otherwise defaults to fern-cli-sdk. Release assets and installers are named after it, such as <binaryName>-installer.sh. Set name: fern-cli-sdk to keep the fern-cli-sdk-* asset names.

packageIdentity.description
string

Short crate description shown on crates.io. When distribution.homebrew is configured, defaults to a description derived from the API’s display name, which also becomes the formula’s desc.

packageIdentity.license
string

SPDX license expression, such as Apache-2.0.

packageIdentity.repository
string

URL of the crate’s source repository. For GitHub output, defaults to the URL of the github repository. The installers and Homebrew formula download release archives from this repository.

packageIdentity.homepage
string

URL of the project homepage. For GitHub output, defaults to the URL of the github repository.

packageIdentity.authors
array of strings

Crate authors, in Cargo’s Name <email> form.

packageIdentity.keywords
array of strings

Keywords for crates.io search.

extraDependencies
object

Adds crates to the [dependencies] table of the generated root Cargo.toml. Use it when code you keep in .fernignore, such as custom command handlers or custom authentication, imports crates the generated CLI doesn’t already depend on. Each value is a version requirement string or a dependency table with any of version, features, optional, defaultFeatures, package, path, git, branch, rev, and registry. Crates the generated CLI already depends on can’t be redeclared.

generators.yml
config:
binaryName: plant
extraDependencies:
google-cloud-auth: "1.16"
google-cloud-iam-credentials-v1:
version: "1.12"
defaultFeatures: false

Generation writes the dependencies to Cargo.toml only. The first cargo build after generation resolves them into Cargo.lock.

extraDevDependencies
object

Same as extraDependencies, for the [dev-dependencies] table.

generators.yml
config:
extraDevDependencies:
mockall: "0.11"
distribution
object

Configures the release workflow that builds the GitHub Release archives every generated CLI ships, and adds opt-in Homebrew and Scoop publishing on top of them. The release workflow runs from a tagged release, so distribution is honored only when the generator delivers to a GitHub repository through the github block. Enabling a channel adds a publish job to the release workflow and the matching install command to the generated README. Each job pushes to a public tap or bucket repository you create, authenticating with either a personal access token per channel or a GitHub App whose credentials you store as repository secrets.

generators.yml
config:
binaryName: plant
distribution:
homebrew:
tap: garden/homebrew-tap
formula: plant
scoop:
bucket: garden/scoop-bucket
distribution.githubApp
object

GitHub App that the Homebrew and Scoop publish jobs use to mint a short-lived installation token at release time, instead of reading a long-lived personal access token. Declared once for both channels; a tap and a bucket under different accounts each need the App installed on their own account, since every job requests a token for the owner of the repository it pushes to. A channel’s tokenEnvironmentVariable takes precedence over githubApp.

distribution.githubApp.appIdSecret
stringRequired

Name of the GitHub Actions secret holding the App’s App ID or Client ID.

distribution.githubApp.privateKeySecret
stringRequired

Name of the GitHub Actions secret holding the entire contents of the App’s private key .pem file, line breaks included.

distribution.githubAttestations
"auto" | booleanDefaults to auto

Whether the release workflow signs the GitHub Release build artifacts with GitHub artifact attestations. GitHub supports attestations on private repositories only with GitHub Enterprise Cloud; on any other private repository the attest step fails every build and no release is cut.

  • "auto": attests on public repositories and skips the step on private ones.
  • true: always attests. Set this for a private repository on GitHub Enterprise Cloud, where "auto" would skip attestations that work.
  • false: never attests. Removes the attest step and its attestations: write permission from the release workflow and sets github-attestations = false in dist-workspace.toml.
generators.yml
config:
distribution:
githubAttestations: false
distribution.homebrew.tap
stringRequired

Tap repository as <owner>/<repo>, such as garden/homebrew-tap. The repository must already exist and be public.

distribution.homebrew.formula
string

Formula name, which is also the .rb filename brew install <tap>/<formula> resolves against. Must start with a lowercase letter and contain only [a-z0-9-]. Defaults to binaryName.

distribution.homebrew.tokenEnvironmentVariable
stringDefaults to HOMEBREW_TAP_TOKEN

Name of the GitHub Actions secret holding a token with write access to the tap repository. The workflow’s built-in GITHUB_TOKEN is scoped to the CLI repository and is rejected here.

distribution.scoop.bucket
stringRequired

Bucket repository as <owner>/<repo>, such as garden/scoop-bucket. The repository must already exist and be public. The generated manifest declares a 64bit architecture only.

distribution.scoop.tokenEnvironmentVariable
stringDefaults to SCOOP_BUCKET_TOKEN

Name of the GitHub Actions secret holding a token with write access to the bucket repository.

Publishing & delivery

output

Configures where to publish the generated CLI. The CLI generator supports npm and local-file-system output locations; binaries also reach users through the GitHub Release that each tag produces, plus the opt-in Homebrew and Scoop channels configured under distribution. The publishing workflow covers OIDC auth, CI builds, and tap and bucket setup, and self-hosted generation covers Docker-based generation on your own machine.

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

generators.yml
groups:
cli:
generators:
- name: fern-cli-generator
version: 0.61.1
output:
location: npm
package-name: "@myorg/my-cli"
token: "${NPM_TOKEN}"
config:
binaryName: my-cli

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

generators.yml
groups:
cli:
generators:
- name: fern-cli-generator
version: 0.61.1
output:
location: local-file-system
path: ../my-cli
config:
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
groups:
cli:
generators:
- name: fern-cli-generator
version: 0.61.1
config:
binaryName: my-cli
github:
repository: my-org/my-cli
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
groups:
cli:
audiences: ["external"]
generators:
- name: fern-cli-generator
version: 0.61.1
config:
binaryName: my-cli

smart-casing

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

generators.yml
groups:
cli:
generators:
- name: fern-cli-generator
version: 0.61.1
smart-casing: true
config:
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
groups:
cli:
generators:
- name: fern-cli-generator
version: 0.61.1
api:
auth: BearerAuth
config:
binaryName: my-cli

metadata

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

generators.yml
groups:
cli:
generators:
- name: fern-cli-generator
version: 0.61.1
metadata:
package-description: "CLI for the Contoso API"
author: "Contoso Inc."
reference-url: "https://docs.contoso.com/cli"
config:
binaryName: contoso