# CLI configuration options

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

```yaml
cli:
  version: 0.1.0
  packageName: "github.com/my-company/my-api-cli"
  cliName: "my-api"
  envVarPrefix: "MY_API"
```

<Table
  data={[
    {
      name: "version",
      required: "true",
      default: "0.0.1",
      description:
        "The current version of the CLI. Injected into the binary via ldflags during GoReleaser builds.",
    },
    {
      name: "packageName",
      required: "true",
      default: "openapi",
      description:
        "The Go module path for the CLI project (e.g., `github.com/my-company/my-api-cli`). Used in `go.mod` and for `go install` commands.",
    },
    {
      name: "cliName",
      required: "true",
      default: "cli",
      description:
        "The binary name users type to run the CLI. Also determines the config directory path (`~/.config/<cliName>/config.yaml`), shell completion commands, and documentation references.",
    },
    {
      name: "envVarPrefix",
      required: "true",
      default: "CLI",
      description:
        "Prefix for environment variables the CLI reads. For example, with prefix `MY_API`, the CLI checks for `MY_API_API_KEY`, `MY_API_BEARER_TOKEN`, `MY_API_SERVER_URL`, etc.",
    },
  ]}
  columns={[
    { key: "name", header: "Name" },
    { key: "required", header: "Required" },
    { key: "default", header: "Default Value" },
    { key: "description", header: "Description" },
  ]}
/>

## Command behavior

```yaml
cli:
  removeStutter: true
```

## Release and distribution

```yaml
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"
```

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

```yaml
cli:
  enableCustomCodeRegions: true
```

## Additional dependencies

```yaml
cli:
  additionalDependencies:
    github.com/my-company/my-package: "v1.2.3"
```

## Error type naming

```yaml
cli:
  baseErrorName: "SDKError"
  defaultErrorName: "SDKDefaultError"
```