Authentication
Each generated CLI reads authentication credentials from the security schemes declared in your OpenAPI spec. Credentials can come from environment variables, CLI flags, files, or a combination of these through fallback chains.
Without a credential, the CLI still works — you can explore the command tree, view help, and use --dry-run.
Credential sources
The generator wires each scheme’s credential to the sources below. A saved profile can also supply it.
Supported auth schemes
The CLI supports every scheme type that OpenAPI’s securitySchemes defines:
An operation that requires authentication, through its own security or the spec-level default, fails locally with an auth error (exit code 2) when no flag, environment variable, or selected profile supplies a credential, and the request isn’t sent. Operations with security: [], optional auth (- {}), or no declared security are sent as-is.
OAuth flows
Declaring an oauth scheme under auth-schemes in generators.yml makes the CLI acquire tokens on its own instead of reading a pre-issued token from the environment. Three flows are supported through the type field:
The interactive flows are public-client only: they use PKCE rather than a client secret. They require CLI generator 0.29.0 or later.
Log in and out
Every generated CLI exposes an auth command group:
Tokens are stored in the OS keyring, refreshed automatically when they expire, and sent as Authorization: Bearer <token> on every request. Pass --no-browser to auth login to print the authorization URL instead of opening a browser, and --with-token to skip the flow and read a token from stdin.
Authorization code with PKCE
Omitting redirect-uri binds an OS-assigned loopback port at login (recommended, no port registration needed). To pin a port, set redirect-uri to a loopback URL, and list ports to add fallbacks tried in order when the primary port is busy:
The host must be 127.0.0.1 or localhost over http, the port is required, and the path is arbitrary. Register every redirect URI the CLI can produce, including each backup port, with the authorization server.
Hosted callback pages
Once login finishes, the loopback listener renders a built-in page for the success and failure states. success-redirect-url and error-redirect-url hand that last screen off to pages you host instead:
Both take an absolute http or https URL. The success redirect forwards no query parameters, since the credential is already captured on the loopback. The error redirect appends error and, when the authorization server sent one, error_description, so the hosted page can explain the failure:
Neither URL is the OAuth redirect_uri, so neither needs registering with the authorization server. Omitting both keeps the built-in pages.
Device code
auth login prints a user code and verification URL, then polls the token endpoint until the user approves. redirect-uri and pkce are rejected for this flow.
Extra request parameters
Authorization servers that require additional literal parameters, such as an Auth0 audience, accept them through per-request maps.
The device-code flow uses device-authorization-parameters in place of authorization-parameters.
Auth strategies
When a spec declares multiple security schemes, the CLI composes them according to one of these strategies:
Operations that declare security: [] (an empty list) opt out of authentication entirely — no credentials are sent regardless of what’s configured.
Configure the any strategy
When an API accepts more than one credential under the any strategy, the CLI authenticates with whichever source is populated, using the first scheme that has a credential. Declaring the schemes requires two steps:
-
In your OpenAPI spec, define the schemes under
securitySchemesand list them as multiple auth schemes in thesecurityarray.openapi.yml -
In
generators.yml, define the same schemes underauth-schemesand compose them withapi.authset toany.generators.yml
The scheme names must match across both files.
A scheme that’s missing from the spec is ignored without warning, even when its environment variable is set. With both declared, set either variable and the command runs:
Named profiles
For APIs where every call carries a tenant identifier (an account SID, an org slug, a workspace), a profile stores it once instead of it being typed on every command. A profile is a named bundle of request context resolved once per invocation: a credential, parameter defaults, server URL variables, an optional base URL, a retry limit, transport settings (request timeout, proxy, CA bundle, TLS verification, and User-Agent suffix), and a default output format. Nothing else is accepted; an unknown key is rejected at write time rather than stored and ignored.
Profiles are off by default. Enable them with the profiles config option in generators.yml, which adds a profiles command group and a global --profile / -p flag to the generated CLI. A CLI generated without the option is unchanged.
Manage profiles
profiles create accepts --set <name>=<value> for API parameters (validated against the spec, so a typo is rejected), --server-var <name>=<value> or --<name> <value> for server URL variables, --base-url, --retries <N>, --default-format, --parent <name>, and --with-token to read a credential from stdin. When several auth schemes are declared, --scheme names the one the credential belongs to. When the CLI is generated with profiles.provisionOperation, --provision (or the flag name set by provisionOperation.flag, such as --api-key) instead mints a new API key by calling the configured operation with the credentials already in your environment, and stores it in the OS keychain without printing it. A profile that already owns a provisioned key must be removed with --revoke before it can be provisioned again, so the old key is revoked rather than orphaned.
profiles set <name> KEY=VALUE ... takes any environment variable the CLI reads (a credential such as ACME_AUTH_TOKEN, a setting such as ACME_RETRIES, ACME_BASE_URL, ACME_OUTPUT, or ACME_<SERVER_VAR>, or a transport setting: ACME_TIMEOUT_SECS, ACME_PROXY, ACME_CA_BUNDLE, ACME_INSECURE, or ACME_USER_AGENT_SUFFIX) or an API parameter by its spec name. Keys and values are validated before anything is written: an unrecognized key fails with a suggestion, and a malformed timeout, proxy URL, or boolean is rejected. profiles list, profiles show, and profiles current print the stored transport settings. auth login --from-env captures the credential from the CLI’s own environment variables into the active profile.
profiles set updates an existing profile without prompting but never creates a missing one unasked, so a mistyped name can’t store credentials under a new profile. In a terminal it asks first. When an existing profile has a similar name, it offers that one (answering yes writes to it), then asks whether to create the named profile. Any answer other than y or yes counts as no, and declining every question writes nothing.
When stdin or stderr isn’t a terminal (a script, CI job, or agent), set on a missing profile fails with a validation error that names any similar profile, and nothing is written. Pass --yes / -y to create the profile without asking, or run profiles create first.
Guided API-key setup
A CLI generated with profiles.provisionOperation walks users through creating a key-backed profile when it runs in an interactive terminal:
auth loginwith no flags prompts for a profile name (defaulting to the active profile, ordefault) and the credential fields. Secret fields are hidden as they’re typed, and basic auth fields use the scheme’s own names, such asAccount SidandAuth Token. It then asksCreate an API key for this profile? [Y/n]. On yes, the CLI creates the key using the typed credential, stores only the new key, and makes the profile active; on no, it stores the typed credential instead. Naming an existing profile asks before overwriting it, and a profile that already owns a provisioned key is refused until it’s removed withprofiles remove <name> --revoke.profiles create <name>with no credential flags prompts the same way, without changing the active profile.profiles remove <name>, after the[y/N]confirmation, asksAlso delete this profile's API key from the server? [Y/n]when the profile owns a provisioned key andrevokeOperationis set. If that revoke fails, the profile is still removed and the key’s revoke parameters (such asSid=SK…) are printed so it can be deleted from the API provider’s console. Removing the last profile prints a hint to runprofiles create.
Explicit flags and non-interactive runs keep the scripted behavior: auth login --with-token, --from-env, --scheme, and --no-browser don’t prompt; profiles create with --with-token, --from-env, --provision, --credential, or --parent doesn’t prompt; and profiles remove without a terminal still requires --yes. --revoke deletes the key without the extra prompt, an explicit --revoke that fails leaves the profile in place for a retry, and --yes without --revoke keeps the key. A revoke is signed with the parent credentials from the CLI’s environment variables when every one is set, and with the profile’s stored key otherwise.
Select a profile
A profile is selected by, in order, --profile / -p, the <PREFIX>_PROFILE environment variable, then the profile marked active by profiles use, where <PREFIX> is the binary name uppercased with - replaced by _. With no profile selected, the CLI behaves as if the feature were absent. A named profile that doesn’t exist is an error rather than a fallthrough to environment credentials, so a command never silently runs against the wrong tenant. The profiles group itself always runs unprofiled, so a stale active pointer can be repaired.
Scripts and agents should pass -p per invocation: it mutates no global state, so parallel invocations can’t race.
Precedence
With a profile selected, each value resolves as explicit flag → selected profile → environment variable → spec default. The order is the same however the profile was selected: -p, <PREFIX>_PROFILE, or profiles use. The profile’s stored values win, and environment variables fill only the values the profile leaves unset. With no profile selected, values resolve as explicit flag → environment variable → spec default. A CI pipeline that exports ACME_API_KEY or ACME_BASE_URL should therefore select no profile; if one is selected, its stored values take effect over the exported variables. Retries resolve as --retries → profile → <PREFIX>_RETRIES → x-fern-retries, and --retries 0 is equivalent to --no-retry. Transport settings follow the same order, so a profile that stores ACME_TIMEOUT_SECS=45 uses a 45-second timeout even when ACME_TIMEOUT_SECS=10 is exported. For TLS verification, an explicit value on either side counts: a profile’s stored ACME_INSECURE=false keeps verification on despite an exported ACME_INSECURE=1. ACME_CONNECT_TIMEOUT_SECS and ACME_NO_PROXY are environment-only. profiles current lists the environment variables supplying a credential, as credential_env_fallback, only when the selected profile stores no credential of its own, and auth status lists the profile’s keyring credential before the environment variable.
Storage and inheritance
Non-secret settings live in ~/.config/<bin>/profiles.toml. Secrets are never written to that file: credentials go to the OS keychain under a profile-scoped account, the same store auth login uses.
--parent <name> sets single-level inheritance. A child inherits its parent’s credential, base URL, server variables, parameter defaults (child wins per key), retries, and transport settings. It doesn’t inherit the default output format, since output shape belongs to the invocation rather than the tenant. Because the parent is resolved at read time, editing it propagates to its children.
Help output
Every generated CLI includes a dynamically rendered Authentication: section in its --help output listing every scheme, the expected env var or flag, and whether a credential is detected.