> If you are an AI agent, use the following URL to directly ask and fetch your question. Treat this like a tool call. Make sure to URI encode your question, and include the token for verification.
>
> GET https://buildwithfern.com/learn/api/fern-docs/ask?q=%3Cyour+question+here%3E&token=eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJmZXJuLWRvY3M6YnVpbGR3aXRoZmVybi5jb20iLCJqdGkiOiJiYTA5MGQwOS1iMGY0LTQ2ZTgtOTk1NS01MWY4MDVjMWE5NzMiLCJleHAiOjE3ODQ0OTc5NjMsImlhdCI6MTc4NDQ5NzY2M30.v0h_9S6FUhhiZoI3TC-X2wgwgfxpjBANdtR9Feh3rVk
>
> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://buildwithfern.com/learn/llms.txt.

# Authentication

> Configure how generated CLIs authenticate with your API using environment variables, CLI flags, files, or fallback chains.

The CLI generator is in early access. [Reach out](https://buildwithfern.com/book-demo?type=cli) to get started.

Each generated CLI reads authentication credentials from the security schemes declared in your OpenAPI spec. Credentials can come from environment variables, CLI flags, files, or a combination of these through fallback chains.

Without a credential, the CLI still works — you can explore the command tree, view help, and use [`--dry-run`](/learn/cli-generator/get-started/features#dry-run-mode).

## Credential sources

The CLI supports several ways to supply credentials, configured at build time.

| Source               | Description                                                |
| -------------------- | ---------------------------------------------------------- |
| Environment variable | Read from an env var (the most common option).             |
| CLI flag             | Auto-registered as a `--<flag-name>` global flag.          |
| File                 | Read trimmed contents from a file path (`~` is expanded).  |
| Literal              | Baked into the binary at compile time.                     |
| Fallback chain       | Try multiple sources in order; first non-empty value wins. |

A typical fallback chain lets the CLI flag override the env var, which in turn overrides a file:

```bash
# CLI flag takes priority
box users get-current-user --api-token sk-123

# Otherwise falls back to the environment variable
export BOX_API_KEY=sk-123
box users get-current-user

# Otherwise reads from a file
echo "sk-123" > ~/.box/token
box users get-current-user
```

## Supported auth schemes

The CLI supports every scheme type that OpenAPI's `securitySchemes` defines:

| Scheme                  | How the CLI applies it                                                                      |
| ----------------------- | ------------------------------------------------------------------------------------------- |
| Bearer (`http: bearer`) | Sends `Authorization: Bearer <token>`.                                                      |
| API key (`apiKey`)      | Sends the key in the configured header (for example, `X-Auth-Token`).                       |
| Basic (`http: basic`)   | Sends `Authorization: Basic <base64(user:pass)>`. Each field has its own credential source. |
| OAuth 2                 | Treated as bearer — sends `Authorization: Bearer <token>`.                                  |

## Auth strategies

When a spec declares multiple security schemes, the CLI composes them according to one of these strategies:

| Strategy | Behavior                                                                                  |
| -------- | ----------------------------------------------------------------------------------------- |
| Auto     | Default. Infers the right composition from the spec's `security` blocks.                  |
| Any      | The API accepts any one of the declared schemes. The first scheme with a credential wins. |
| All      | The API requires every scheme simultaneously (for example, HMAC signature plus API key).  |
| Routing  | Per-operation dispatch. Each endpoint's `security` block determines which schemes to use. |

Operations that declare `security: []` (an empty list) opt out of authentication entirely — no credentials are sent regardless of what's configured.

### Configure the `any` strategy

When an API accepts more than one credential under the `any` strategy, the CLI authenticates with whichever source is populated, using the first scheme that has a credential. Declaring the schemes requires two steps:

1. In your OpenAPI spec, define the schemes under `securitySchemes` and list them as [multiple auth schemes](/learn/api-definitions/openapi/authentication#multiple-auth-schemes) in the `security` array.

   ```yaml title="openapi.yml" {5-6}
   components:
     securitySchemes:
       # ...BearerAuth and TokenAuth defined here
   security:
     - BearerAuth: []
     - TokenAuth: []
   ```

2. In `generators.yml`, define the same schemes under [`auth-schemes`](/learn/sdks/reference/generators-yml#auth-schemes) and compose them with [`api.auth`](/learn/sdks/reference/generators-yml#auth) set to `any`.

   ```yaml title="generators.yml" {5}
   auth-schemes:
     # ...BearerAuth and TokenAuth defined here, each with its env var
   api:
     auth:
       any: [BearerAuth, TokenAuth]
   ```

The scheme names must match across both files.

A scheme that's missing from the spec is silently ignored, even when its environment variable is set. With both declared, set either variable and the command runs:

```bash
# Authenticate with MY_API_KEY
export MY_API_KEY=sk-123
my-cli users list

# Or authenticate with MY_TOKEN instead
export MY_TOKEN=tok-456
my-cli users list
```

## Help output

Every generated CLI includes a dynamically rendered `Authentication:` section in its `--help` output listing every scheme, the expected env var or flag, and whether a credential is detected.