Configuration reference
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.
config options
binaryName
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.
The binary name contoso produces:
- Executable:
contoso - Env-var prefix:
CONTOSO(e.g.CONTOSO_CA_BUNDLE,CONTOSO_LOG)
displayName
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”.
rootGroup
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.
customCommands
Controls whether the generator produces the custom command infrastructure alongside the CLI binary. When enabled, the output includes:
- A
<binaryName>-typeslibrary crate (typed serde structs) - A
<binaryName>-sdklibrary crate (HTTP client accessible viactx.client()) - Scaffolding files for user-authored command handlers
Set to false to produce a spec-only CLI with no custom command support.
userAgentSuffixFlag
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):
A consumer of the generated contoso CLI then appends its product token with the renamed flag:
generateWireTests
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.
splitTypeCrates
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.
banner
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:
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.
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.
The banner inline, typically as a YAML block scalar (text: |). Can’t be combined with file.
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.
Axis the colors gradient runs along: horizontal (left to right), vertical (top to bottom), or diagonal (top-left to bottom-right).
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.
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
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.
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.
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.
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.
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.
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.
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_.-].
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.
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.
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, orUSERNAMEon 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.
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
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.
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.
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.
SPDX license expression, such as Apache-2.0.
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.
URL of the project homepage. For GitHub output, defaults to the URL of the github repository.
Crate authors, in Cargo’s Name <email> form.
Keywords for crates.io search.
extraDependencies
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.
Generation writes the dependencies to Cargo.toml only. The first cargo build after generation resolves them into Cargo.lock.
Same as extraDependencies, for the [dev-dependencies] table.
distribution
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.
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.
Name of the GitHub Actions secret holding the App’s App ID or Client ID.
Name of the GitHub Actions secret holding the entire contents of the App’s private key .pem file, line breaks included.
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 itsattestations: writepermission from the release workflow and setsgithub-attestations = falseindist-workspace.toml.
Tap repository as <owner>/<repo>, such as garden/homebrew-tap. The repository must already exist and be public.
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.
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.
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.
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.
npm
Publish the CLI as an npm package. Users install with npm install -g @myorg/my-cli or npx @myorg/my-cli.
Local file system
Write the generated Rust project to a local directory for manual building and distribution.
github
Specifies how generated CLI code is delivered to your repository. Supports the same modes as SDKs: release, pull-request, and push.
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.
smart-casing
Enables intelligent case conversion that preserves numbers and common programming patterns in generated command and flag names.
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.
metadata
Attach package metadata to the generated CLI for use in published artifacts.