> ## Documentation Index
> Fetch the complete documentation index at: https://www.carrothub.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Configure the API key and base URL used by every command

The CLI needs one piece of information to talk to CarrotHub:

* An **API key** — obtain it from the
  [CarrotHub Console](https://www.carrothub.ai/app/api-keys).

The base URL defaults to `https://api.carrothub.ai`; you only need to set it
when you are pointing at a self-hosted gateway or proxy.

## Environment variables

The canonical way to configure the CLI. Drop these into your shell rc file
(`~/.zshrc`, `~/.bashrc`, ...) or your CI secret store.

```bash theme={null}
export CARROTHUB_API_KEY="sk-..."
```

| Variable | Required | Description |
| - | - | - |
| `CARROTHUB_API_KEY` | Yes | API key for authentication |
| `CARROTHUB_BASE_URL` | No | Custom API base URL — use this only for a private gateway or proxy |

## `.env` file

For project-scoped configuration, create a `.env` file in the directory you run
the CLI from. The CLI loads `CARROTHUB_*` variables automatically and **never**
overwrites variables already set in the process environment.

```ini .env theme={null}
CARROTHUB_API_KEY=sk-...
```

The file is read once per process. Quotes around values are stripped, lines
starting with `#` are treated as comments, and any variable that does not begin
with `CARROTHUB_` is ignored.

## Command-line overrides

Every command accepts ad-hoc overrides that take precedence over both the
environment and the `.env` file. Useful when juggling multiple accounts:

```bash theme={null}
carrothub run alibaba/wan2.6-t2v \
  --api-key "sk-test..." \
  --prompt "A drone shot above a canyon"
```

| Flag | Equivalent variable |
| - | - |
| `--api-key <key>` | `CARROTHUB_API_KEY` |
| `--base-url <url>` | `CARROTHUB_BASE_URL` |

## Resolution order

The configuration loader resolves values in this order, stopping at the first hit:

1. CLI flags (`--api-key`, `--base-url`)
2. Process environment variables (`CARROTHUB_*`)
3. `.env` file in the current working directory

## Inspect the active configuration

Run `carrothub config` at any time to see what the CLI thinks it is configured
with. The API key is masked.

```bash theme={null}
$ carrothub config
Current Configuration:
  API Key:    sk-1..fd
  Base URL:   https://api.carrothub.ai
  Timeout:    120000ms
  Max Retries: 3
```

If no key is found you will see a "No configuration found." notice followed by
the same setup help as the table above.

## Troubleshooting

**`API key not found.`**  Set `CARROTHUB_API_KEY` in the environment, write it
to `.env`, or pass `--api-key`.

**A `.env` value isn't taking effect.**  Existing environment variables are
never overwritten — `export` wins over `.env`. Check `printenv | grep CARROTHUB`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.