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.

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.

1
tags:
2
  - name: plants
3
    description: Browse and water the plants in your greenhouse. Water schedules are timezone-aware.
4
paths:
5
  /plants/{plantId}:
6
    get:
7
      tags:
8
        - 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).

1
x-fern-groups:
2
  plants:
3
    summary: Manage your greenhouse
4
    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.

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).