Customize a CLI

The generated CLI can be customized through gen.yaml, shared OpenAPI-driven generation settings, and a small set of CLI-specific runtime defaults. This page focuses on the options that most directly affect generated CLI behavior. For the full set of target options, see the CLI configuration reference.

CLI-specific generator settings

The CLI target exposes a focused set of generator settings that control naming, runtime UX, and release artifacts.

Example gen.yaml

cli:
  cliName: petstore
  envVarPrefix: PETSTORE
  removeStutter: true
  generateRelease: true
  interactiveMode: true
  interactiveAuth: true
  interactiveTheme:
    accentColor: "#38BDF8"
    dimmedColor: "#64748B"
    subtleColor: "#475569"
    errorColor: "#F87171"
    successColor: "#4ADE80"

Command naming and stutter removal

By default, the CLI applies stutter removal to keep command names readable. When an operation name overlaps with its tag group, the redundant part is removed.

Prefix stutter

An operation like users-list under a users tag becomes list:

# removeStutter: true
petstore users list
petstore users get
 
# removeStutter: false
petstore users users-list
petstore users users-get

Suffix stutter

An operation like list-users under a users tag also becomes list:

# removeStutter: true
petstore users list
petstore users create
 
# removeStutter: false
petstore users list-users
petstore users create-user

Singular/plural variants are also handled, so create-user under users can become create.

Environment variable prefix

The envVarPrefix setting controls the prefix for environment variables consumed by the generated CLI. This affects authentication, server overrides, and global parameters.

cli:
  envVarPrefix: PETSTORE

With this configuration, the CLI will look for values such as:

• PETSTORE_API_KEY
• PETSTORE_BEARER_TOKEN
• PETSTORE_SERVER_URL
• PETSTORE_TIMEOUT

The exact auth-related variable names depend on the security schemes in the OpenAPI document.

Interactive mode

interactiveMode controls whether the generated CLI includes richer terminal UX for human users.

cli:
  interactiveMode: true

When enabled, the generator adds:

• an explore command for browsing and launching commands from a TUI
• auto-prompting for unresolved required fields on eligible operation commands
• auto-launch of the explorer when the CLI is invoked with no subcommand from a real TTY
• the global --no-interactive flag to disable prompting/TUI behavior at runtime

petstore explore
petstore users create --no-interactive

When disabled, the CLI remains fully functional as a flag-driven command-line tool; it simply omits these interactive surfaces.

Interactive auth flows

interactiveAuth controls richer auth-specific flows layered on top of the standard config/auth behavior.

cli:
  interactiveAuth: true

When enabled, and when the API defines global security, the generated CLI can add:

• auth login
• auth whoami
• auth logout
• richer configure flows using terminal forms rather than plain prompts

These flows automatically degrade when interactivity is unavailable and are suppressed in agent mode.

Interactive theme

Tune the generated form and TUI palette with interactiveTheme:

cli:
  interactiveTheme:
    accentColor: "#2563EB"
    dimmedColor: "#64748B"
    subtleColor: "#475569"
    errorColor: "#DC2626"
    successColor: "#16A34A"

The theme values are hex colors used for:

• accents and borders
• secondary/dimmed text
• subtle placeholders and muted elements
• validation errors
• success indicators and confirmations

Release artifact generation

By default, the CLI target generates release infrastructure for distributing binaries:

cli:
  generateRelease: true

When enabled, the generator produces:

• .goreleaser.yaml
• .github/workflows/release.yaml
• scripts/install.sh
• scripts/install.ps1

Set generateRelease: false to manage packaging and binary distribution separately.

CLI name and binary identity

The cliName setting affects more than just the executable:

• binary name
• config directory path (~/.config/<cliName>/config.yaml)
• shell completion command name
• generated install and usage examples
• user-facing documentation and generated README snippets

cli:
  cliName: petstore

Custom code regions

Enable custom code regions to preserve hand-written code inside supported files across regenerations.

cli:
  enableCustomCodeRegions: true

Example:

// #region custom-imports
import "my-custom-package"
// #endregion custom-imports

For more details, see the custom code regions documentation.

OpenAPI-driven behavior that also affects the CLI

Many CLI features are driven by the OpenAPI document or shared generation/runtime settings rather than a CLI-only flag. Examples include:

• authentication schemes and credential flags
• server definitions and server variable flags
• pagination support
• retries configuration
• response/header behavior
• request body structure and generated flag shape
• streaming endpoints (SSE / JSONL)
• binary responses and bytes request fields

The CLI target wraps a generated Go SDK, so many shared SDK/runtime customizations also influence CLI behavior.

Underlying Go SDK behavior

The CLI target generates and embeds a Go SDK under the hood. Many shared SDK/runtime concepts still apply, including:

• Server configuration
• Authentication and security
• Retries
• Pagination
• Error handling
• Global parameters

For Go-specific SDK configuration, see the Go configuration reference.

Next step

For release packaging and installation workflows, see Distribute a CLI.