OpenAPI extensions

The CLI generator reads several Fern OpenAPI extensions to shape the generated CLI. You can add these extensions directly in your spec or apply them through overlays.

Command structure

x-fern-sdk-group-name

Determines the subcommand group hierarchy. Each list element becomes a nested subcommand, with names converted from camelCase to kebab-case.

paths:
  /scheduled-events/{uuid}/invitees:
    get:
      x-fern-sdk-group-name:
        - scheduledEvents
        - invitees
      x-fern-sdk-method-name: list-event-invitees

Produces: cli scheduled-events invitees list-event-invitees

x-fern-sdk-method-name

Sets the leaf command name (used as-is).

paths:
  /users/me:
    get:
      x-fern-sdk-method-name: get-current-user

Produces: cli get-current-user (or nested under a group if x-fern-sdk-group-name is also set).

See SDK method names for more details.

Command group help

A command group’s help text comes from the root-level tags[] entry attributed to it: the first sentence of the tag description becomes the short line in the parent command’s table, and the full description becomes the group’s --help body.

tags:
  - name: plants
    description: Browse and water the plants in your greenhouse. Water schedules are timezone-aware.
paths:
  /plants/{plantId}:
    get:
      tags:
        - plants

Produces plants Browse and water the plants in your greenhouse. in the top-level command table.

A tag is attributed to a group when its name matches the group name, or when it’s exclusive to the group and covers at least half of the group’s operations. Colon-scoped tag names (access:all) and tags shared across groups are ignored, leaving the fallback Operations on '<name>'.

x-fern-groups

Overrides the derived help for a group. summary sets the short line, which is capped at 80 characters; description sets the long help and also supplies the short line when summary is absent or only restates the command name (Plants for plants).

x-fern-groups:
  plants:
    summary: Manage your greenhouse
    description: Browse, water, and repot plants. Watering respects each plant's schedule.

Filtering

x-fern-ignore

Excludes operations or parameters from the generated CLI. An ignored operation produces no command; an ignored parameter produces no flag.

paths:
  /internal/debug:
    get:
      x-fern-ignore: true

At the parameter level:

paths:
  /users:
    get:
      parameters:
        - name: internalParam
          in: query
          x-fern-ignore: true
          schema:
            type: string

See Ignoring elements for more details.

Availability badges

x-fern-availability

Adds a status badge next to the command in --help output.

paths:
  /v2/reports:
    get:
      x-fern-availability: beta

OpenAPI’s standard deprecated: true is also honored and maps to [Deprecated] when x-fern-availability isn’t set.

See Availability for more details.

Parameter naming

x-fern-parameter-name

Overrides the CLI flag name derived from a parameter. By default, parameter names are converted to kebab-case for use as flags.

paths:
  /users:
    get:
      parameters:
        - name: X-API-Version
          in: header
          schema:
            type: string
          x-fern-parameter-name: api-version

Produces --api-version instead of --x-api-version.

See Customize parameter names for more details.

Global parameters

x-fern-global-parameters

Registers a value that’s configured once and injected into every applicable command, rather than passed on each invocation. Each declared parameter becomes a top-level --<flag-name> flag with its environment-variable fallback and client-side default, injected at the declared location (body, query, header, or path).

x-fern-global-parameters:
  - name: currency
    in: body
    target: config.currency
    env: ACME_CURRENCY
    default: USD
    apply: auto

The value resolves from the first available source: the CLI flag, then the environment variable, then the default. A per-operation parameter with the same target overrides the global.

# CLI flag takes priority
acme products search --currency EUR
# Otherwise falls back to the environment variable
export ACME_CURRENCY=EUR
acme products search
# Otherwise sends the default (USD)
acme products search

An apply: auto parameter applies to every command whose request contains the target; an apply: explicit parameter applies only to operations that opt in with x-fern-global-parameter.

Headers declared API-wide with x-fern-global-headers are sent on every request the same way, and an x-fern-global-parameters entry targeting the same header overrides them.

See Global parameters for the full field reference and resolution order.

Pagination

x-fern-pagination

Enables auto-pagination for an endpoint. The --page-all, --page-limit, --page-delay, and --no-pager flags are registered only on commands whose operation carries this extension.

paths:
  /plants:
    get:
      operationId: list_plants
      x-fern-pagination:
        cursor: $request.cursor
        next_cursor: $response.next
        results: $response.results

See Pagination for all supported pagination schemes (offset, cursor, URI, and path).