Configuration
Complete reference for api.config.toml configuration options.
chowbea-axios uses a TOML configuration file (api.config.toml) in your project root.
Full Configuration Reference
# Remote OpenAPI spec endpoint URL
# Optional when spec_file is set
api_endpoint = "http://localhost:3000/openapi.json"
# Local spec file path (use instead of api_endpoint for spec-file-only setups)
# spec_file = "./openapi.json"
# Polling interval in milliseconds for watch mode
poll_interval_ms = 10000
[output]
# Folder where all generated files are written
folder = "src/api"
[instance]
# Environment variable name for base URL
base_url_env = "API_BASE_URL"
# How to access env vars in the generated client
# "process.env" for Node/Next.js, "import.meta.env" for Vite
env_accessor = "process.env"
# localStorage key for auth token (used when auth_mode is "bearer-localstorage")
token_key = "auth-token"
# Auth mode for the generated Axios instance
# "bearer-localstorage" | "custom" | "none"
auth_mode = "custom"
# Whether to include credentials (cookies) in requests
with_credentials = true
# Request timeout in milliseconds
timeout = 30000
# Optional: HTTP Basic Auth for fetching a protected OpenAPI spec
# [fetch.auth]
# type = "basic"
# username = "$SWAGGER_USER"
# password = "$SWAGGER_PASS"
[watch]
# Enable debug logging in watch mode (shows cycle-by-cycle logs)
debug = falseConfiguration Options
Root Options
| Option | Type | Default | Description |
|---|---|---|---|
api_endpoint | string | - | Remote OpenAPI spec endpoint URL. Optional when spec_file is set. |
spec_file | string | - | Local spec file path. Use this for spec-file-only setups (no endpoint required). |
poll_interval_ms | number | 10000 | Watch mode polling interval (ms) |
You must set either api_endpoint or spec_file. If both are present, the CLI uses spec_file.
Output Section
| Option | Type | Default | Description |
|---|---|---|---|
folder | string | "src/api" | Output folder for generated files |
Instance Section
These options configure the generated Axios instance:
| Option | Type | Default | Description |
|---|---|---|---|
base_url_env | string | "API_BASE_URL" | Environment variable name for the base URL |
env_accessor | string | "process.env" | How env vars are read in the generated client. Use "import.meta.env" for Vite. |
auth_mode | string | "custom" | Auth interceptor mode: "bearer-localstorage", "custom", or "none". See authentication. |
token_key | string | "auth-token" | localStorage key (only used when auth_mode = "bearer-localstorage") |
with_credentials | boolean | true | Include credentials (cookies) in requests |
timeout | number | 30000 | Request timeout in milliseconds |
Fetch Auth Section
Optional. Use this to attach HTTP Basic Auth when fetching a protected OpenAPI spec (e.g. a private staging endpoint).
| Option | Type | Description |
|---|---|---|
type | string | Must be "basic" (only Basic Auth is supported today) |
username | string | Username. Supports $VAR / ${VAR} env interpolation. |
password | string | Password. Supports $VAR / ${VAR} env interpolation. |
[fetch.auth]
type = "basic"
username = "$SWAGGER_USER"
password = "$SWAGGER_PASS"When the env vars aren't set, the CLI prompts for them interactively. In CI, export them in the environment.
Watch Section
| Option | Type | Default | Description |
|---|---|---|---|
debug | boolean | false | Enable verbose cycle-by-cycle logging |
Environment Variable Interpolation
The username and password under [fetch.auth] support env var interpolation:
[fetch.auth]
type = "basic"
username = "$SWAGGER_USER"
password = "${SWAGGER_PASS}"Both $VAR_NAME and ${VAR_NAME} syntax are supported.
If an env var is referenced but not set, the CLI prompts interactively (TTY) or fails with a clear error (CI).
Framework-Specific Examples
Vite / React
api_endpoint = "http://localhost:3000/api-docs/json"
[output]
folder = "src/api"
[instance]
base_url_env = "VITE_API_URL"
env_accessor = "import.meta.env"Next.js
api_endpoint = "http://localhost:3000/api-docs/json"
[output]
folder = "lib/api"
[instance]
base_url_env = "NEXT_PUBLIC_API_URL"
env_accessor = "process.env"Vue / Nuxt
api_endpoint = "http://localhost:3000/api-docs/json"
[output]
folder = "src/services/api"
[instance]
base_url_env = "VITE_API_BASE_URL"
env_accessor = "import.meta.env"Using a Local Spec File
Instead of fetching from a remote endpoint, you can use a local OpenAPI file. api_endpoint is fully optional in this mode:
# spec_file replaces api_endpoint — no remote URL needed
spec_file = "./openapi.json"
[output]
folder = "src/api"The CLI will use this file for all generation operations (fetch, generate, watch, diff, validate).
Multiple Configurations
If you need different configurations (e.g., for different API services), you can:
-
Create multiple config files:
api.config.toml(default)api.config.auth.tomlapi.config.payments.toml
-
Specify which config to use:
chowbea-axios fetch --config api.config.auth.toml