Skip to navigation

Customization

View as Markdown

A generated CLI can be customized at three levels: the OpenAPI spec it’s built from, the configuration that combines multiple specs into a single command tree, and code that adds custom commands alongside the spec-derived ones. OpenAPI extensions control how spec elements map to commands and flags.

Overrides and overlays

The CLI generator supports both overrides and overlays for customizing the OpenAPI spec before the CLI is built. This lets you add Fern extensions, rename parameters, or remove internal endpoints without modifying your original spec.

Overlays follow the OpenAPI Overlay Specification and use JSONPath to target elements:

overlay.yaml
overlay: 1.0.0
info:
title: CLI customizations
version: 1.0.0
actions:
- target: $.paths['/plants'].get
update:
x-fern-sdk-group-name: plants
x-fern-sdk-method-name: list
- target: $.paths['/internal/debug']
remove: true

When both are present, overrides are applied first, then overlays.

Multi-spec merging

A single CLI can combine multiple OpenAPI specs into one command tree. This is useful for APIs that split their spec across domains or versions.

List each spec under api.specs in generators.yml. A spec without a namespace merges flat at the top level; a spec with a namespace gets its own subcommand:

generators.yml
api:
specs:
- openapi: core.yaml
- openapi: billing.yaml
namespace: billing

This produces a CLI where core commands live at the top level and billing commands live under a billing subcommand:

my-api users list # from core.yaml
my-api billing invoices list # from billing.yaml

When a namespace matches a top-level resource in the incoming spec, the CLI hoists that resource’s methods into the namespace to avoid repetition (for example, billing billing invoices list becomes billing invoices list). A slash in a namespace nests it: namespace: messaging/bulk-messages produces my-api messaging bulk-messages create.

Specs under the same namespace that define a resource with the same name merge that resource’s commands and sub-resources. The CLI fails at startup only when two specs define the same command, and the error names the full command path.

Custom commands

Generated CLIs can include custom commands, written in Rust, alongside the spec-derived ones. Custom commands call your API through a co-generated SDK client that shares the CLI’s auth and retries, so they can chain multiple API calls into a single workflow. See Custom commands.