Skip to Content
DocumentationSpeakeasyGeneration ConfigCLI Configuration

CLI configuration options

Alpha · Enterprise Only

CLI generation is currently in alpha and available exclusively to Enterprise customers. Contact us  for access.

This section details the available configuration options for the CLI target. All configuration is managed in the gen.yaml file under the cli section.

Fields marked as required are always present in gen.yaml and auto-populated with defaults during speakeasy quickstart. They can be overridden but must not be removed.

Version and general configuration

cli:
  version: 0.1.0
  packageName: "github.com/my-company/my-api-cli"
  cliName: "my-api"
  envVarPrefix: "MY_API"
Name
version
Required
true
Description
The current version of the CLI. Injected into the binary via ldflags during GoReleaser builds.
Default Value
0.0.1
packageName
Required
true
Description
The Go module path for the CLI project (e.g.,
). Used in
and for
commands.
Default Value
openapi
cliName
Required
true
Description
The binary name users type to run the CLI. Also determines the config directory path (
), shell completion commands, and documentation references.
Default Value
cli
envVarPrefix
Required
true
Description
Prefix for environment variables the CLI reads. For example, with prefix
, the CLI checks for
,
,
, etc.
Default Value
CLI

Command behavior

cli:
  removeStutter: true
Name
removeStutter
Required
false
Description
When enabled, removes redundant prefixes from command names. If an operation name shares a prefix with its tag group, the prefix is stripped (e.g.,
becomes
). Exact matches are promoted to the parent group.
Default Value
true

Release and distribution

cli:
  generateRelease: true
  distribution:
    homebrew:
      enabled: false
      tap: "myorg/homebrew-petstore"
    winget:
      enabled: false
      publisher: "MyOrg"
      repositoryOwner: "mygithubuser"
      publisherUrl: "https://example.com"
      packageIdentifier: "MyOrg.Petstore"
      license: "Apache-2.0"
    nfpm:
      enabled: false
      formats: "deb,rpm"
      maintainer: "Team <team@example.com>"
      license: "Apache-2.0"
Name
generateRelease
Required
false
Description
When enabled, generates GoReleaser configuration (
), GitHub Actions release workflow, and platform install scripts (
and
). The generated release workflow also signs the checksum artifact with GPG. Disable if you manage releases separately.
Default Value
true
distribution.homebrew.enabled
Required
false
Description
When enabled, generates a Homebrew tap formula through GoReleaser and publishes it to the configured tap repository.
Default Value
false
distribution.homebrew.tap
Required
false
Description
GitHub repository for the Homebrew tap in
format. The repository name must start with
. Required when
is
.
Default Value
""
distribution.winget.enabled
Required
false
Description
When enabled, generates a WinGet manifest through GoReleaser and opens a PR against
.
Default Value
false
distribution.winget.publisher
Required
false
Description
Publisher name for the generated WinGet manifest. Required when
is
.
Default Value
""
distribution.winget.repositoryOwner
Required
false
Description
GitHub owner for the fork of
that GoReleaser should push to before opening a PR. Required when
is
.
Default Value
""
distribution.winget.publisherUrl
Required
false
Description
Publisher URL for the generated WinGet manifest. Must be an absolute
or
URL. Required when
is
.
Default Value
""
distribution.winget.packageIdentifier
Required
false
Description
Package identifier for WinGet, typically in
format. Required when
is
.
Default Value
""
distribution.winget.license
Required
false
Description
License metadata for the generated WinGet manifest. Required when
is
.
Default Value
""
distribution.nfpm.enabled
Required
false
Description
When enabled, generates Linux package artifacts through nFPM and attaches them to GitHub Releases.
Default Value
false
distribution.nfpm.formats
Required
false
Description
Comma-separated package formats to generate when nFPM is enabled. Allowed values:
,
,
.
Default Value
deb,rpm
distribution.nfpm.maintainer
Required
false
Description
Maintainer metadata for generated Linux packages. Required when
is
.
Default Value
""
distribution.nfpm.license
Required
false
Description
License metadata for generated Linux packages. Required when
is
.
Default Value
""

Validation rules:

  • distribution.homebrew.enabled: true requires generateRelease: true
  • distribution.homebrew.enabled: true requires distribution.homebrew.tap in owner/repo format and the repository name must start with homebrew-
  • distribution.homebrew.enabled: true requires repoURL or packageName to resolve to a GitHub repository
  • distribution.winget.enabled: true requires generateRelease: true
  • distribution.winget.enabled: true requires distribution.winget.publisher, distribution.winget.repositoryOwner, distribution.winget.publisherUrl, distribution.winget.packageIdentifier, and distribution.winget.license
  • distribution.winget.repositoryOwner must be a valid GitHub owner name
  • distribution.winget.publisherUrl must be an absolute http or https URL
  • distribution.winget.packageIdentifier must use dot-separated Publisher.Package segments
  • distribution.winget.enabled: true requires repoURL or packageName to resolve to a GitHub repository
  • distribution.nfpm.enabled: true requires generateRelease: true
  • distribution.nfpm.enabled: true requires both distribution.nfpm.maintainer and distribution.nfpm.license
  • distribution.nfpm.formats must contain one or more of deb, rpm, or apk
  • generateRelease: true expects the generated release workflow to have CLI_GPG_SECRET_KEY and CLI_GPG_PASSPHRASE repository secrets so it can sign the checksum artifact
  • Homebrew publishing requires a HOMEBREW_TAP_GITHUB_TOKEN secret. For classic PATs use public_repo (public tap) or repo (private tap). For fine-grained PATs grant Contents: Read and write on the tap repository.
  • WinGet publishing requires a WINGET_GITHUB_TOKEN secret using a classic PAT with public_repo scope, plus a fork of microsoft/winget-pkgs owned by distribution.winget.repositoryOwner
  • nFPM generates package files attached to GitHub Releases; it does not create a hosted package repository automatically

Custom code

cli:
  enableCustomCodeRegions: true
Name
enableCustomCodeRegions
Required
false
Description
Enable custom code regions that allow hand-written code to be inserted into generated files. Marked regions are preserved across regenerations. See custom code regions for details.
Default Value
false

Additional dependencies

cli:
  additionalDependencies:
    github.com/my-company/my-package: "v1.2.3"
Name
additionalDependencies
Required
false
Description
Add additional Go module dependencies to the generated
. Useful when custom code regions import external packages.
Default Value
{}

Error type naming

cli:
  baseErrorName: "SDKError"
  defaultErrorName: "SDKDefaultError"
Name
baseErrorName
Required
false
Description
The name of the base error type in the generated SDK.
Default Value
SDKError
defaultErrorName
Required
false
Description
The name of the default error type in the generated SDK.
Default Value
SDKDefaultError

Last updated on