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.

1
paths:
2
  /scheduled-events/{uuid}/invitees:
3
    get:
4
      x-fern-sdk-group-name:
5
        - scheduledEvents
6
        - invitees
7
      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).

1
paths:
2
  /users/me:
3
    get:
4
      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.

Filtering

x-fern-ignore

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

1
paths:
2
  /internal/debug:
3
    get:
4
      x-fern-ignore: true

At the parameter level:

1
paths:
2
  /users:
3
    get:
4
      parameters:
5
        - name: internalParam
6
          in: query
7
          x-fern-ignore: true
8
          schema:
9
            type: string

See Ignoring elements for more details.

Availability badges

x-fern-availability

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

1
paths:
2
  /v2/reports:
3
    get:
4
      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.

1
paths:
2
  /users:
3
    get:
4
      parameters:
5
        - name: X-API-Version
6
          in: header
7
          schema:
8
            type: string
9
          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).

1
x-fern-global-parameters:
2
  - name: currency
3
    in: body
4
    target: config.currency
5
    env: ACME_CURRENCY
6
    default: USD
7
    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.

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

Pagination

x-fern-pagination

Enables auto-pagination for an endpoint. When present, the CLI recognizes --page-all, --page-limit, and --page-delay flags for that command.

1
paths:
2
  /plants:
3
    get:
4
      operationId: list_plants
5
      x-fern-pagination:
6
        cursor: $request.cursor
7
        next_cursor: $response.next
8
        results: $response.results

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