Quick Start

# Initialize and configure (interactive)
npx chowbea-axios init

# Fetch spec and generate client
npx chowbea-axios fetch

Or with your preferred package manager:

pnpm dlx chowbea-axios init
yarn dlx chowbea-axios init
bunx chowbea-axios init

Then import and use:

import { api } from "./src/api/api.client";

const { data, error } = await api.op.getUserById({ id: "123" });

if (error) return console.error(error.message);

console.log(data.name); // ✨ Fully typed

Why chowbea-axios?

• Zero manual types — Generated directly from your OpenAPI spec
• Full autocomplete — Every endpoint, parameter, and response
• Result-based errors — { data, error } instead of try/catch
• Watch mode — Auto-regenerate when your spec changes
• YAML or JSON — Both spec formats accepted at every entry point
• Interactive TUI — Run chowbea-axios (no args) for the dashboard
• CI-friendly — --non-interactive mode plus a hardened workflow template

What Gets Generated

The default output folder is src/api/. Override it via output.folder in api.config.toml.

src/api/
├── _internal/
│   ├── openapi.json         # Cached spec (always JSON)
│   └── .api-cache.json      # Cache metadata (hash, timestamp)
├── _generated/              # Always overwritten — do not edit
│   ├── api.types.ts         # OpenAPI-typed paths/components/operations
│   ├── api.operations.ts    # Typed apiClient.op.<id>(...) methods
│   └── api.contracts.ts     # Concrete interfaces (cmd+click navigation)
├── api.client.ts            # Typed HTTP client (editable, generated once)
├── api.instance.ts          # Axios instance + auth interceptor (editable, generated once)
├── api.error.ts             # Result-based error handling (editable, generated once)
└── api.helpers.ts           # Path-based type helpers (editable, generated once)

Commands

| Command | Description | | ------- | ----------- | | init | Interactive setup — creates config and base files | | fetch | Fetch spec from endpoint (or local file) and generate types | | generate | Generate from cached/local spec | | watch | Watch for spec changes and auto-regenerate (with backoff on failures) | | status | Show current config, cache, and generated-file status | | validate | Validate your OpenAPI spec — 7 categories, severity-classified | | diff | Compare cached vs new spec; flags schema/parameter/response changes | | plugins | Manage Vite codegen plugins (Surfaces, Side Panels) |

Run chowbea-axios <command> --help for command-specific flags.

Interactive Dashboard

Status: experimental. The TUI is functional but has no automated test coverage today. For CI pipelines, scripted workflows, and any production-adjacent use, prefer the headless commands (fetch, generate, watch, etc.). The dashboard is great for interactive exploration but the headless surface is what we guarantee.

Running chowbea-axios with no command launches an OpenTUI dashboard with screens for fetch, generate, diff, validate, watch, plugins, env management, and an endpoint inspector. Tabs survive screen navigation, and processes (e.g. npm run dev) can be run alongside in the process tab.

The dashboard requires Bun. When invoked under Node, the CLI re-launches itself under Bun automatically. If Bun isn't installed, the CLI falls back to headless mode and prints a hint.

Authentication

Configure how the generated client attaches auth tokens via the [instance] block in api.config.toml:

[instance]
auth_mode = "bearer-localstorage"   # SPA pattern — reads from localStorage
# auth_mode = "custom"              # TODO interceptor — implement your own
# auth_mode = "none"                # No interceptor
token_key = "auth-token"            # localStorage key (bearer-localstorage only)
with_credentials = false            # Send cookies cross-origin (default: false)
timeout = 30000
base_url_env = "API_BASE_URL"       # Env var holding the base URL
env_accessor = "process.env"        # or "import.meta.env" for Vite

For fetching the spec itself with HTTP Basic Auth (e.g. private staging endpoints), add a [fetch.auth] block:

[fetch.auth]
type = "basic"
username = "$SWAGGER_USER"          # $VAR or ${VAR} env interpolation
password = "$SWAGGER_PASS"

When the env vars aren't set, the CLI prompts interactively. In CI, set them in the environment.

CI Integration

The init wizard offers to scaffold .github/workflows/chowbea-axios-ci.yml — a hardened workflow that re-fetches your spec on every PR and fails when the generated client is out of date. The template includes:

• permissions: contents: read (default-deny)
• concurrency cancel-in-progress
• Node 22 + npm cache (works for every package manager — see comments for bun/pnpm/yarn variants)
• vars or secrets fallback for STAGING_API_ENDPOINT

For non-interactive bootstrapping (e.g. project starters):

chowbea-axios init --non-interactive \
  --endpoint https://staging.example.com/openapi.json \
  --output-folder src/api \
  --package-manager npm

Vite Plugins (optional)

chowbea-axios/vite exposes two codegen plugins for Vite projects:

• surfacesCodegen() — auto-discovers *.surface.tsx files and generates a typed barrel
• sidepanelsCodegen() — same for *.panel.tsx files

Scaffold them via chowbea-axios init --with-vite-plugins or chowbea-axios plugins --setup. See docs for the full registry pattern.

Compatibility

| | | |---|---| | Node | >=20 (declared in engines; tested in CI on 20 / 22 / 24 across Linux, macOS, Windows) | | Module format | ESM only. package.json declares "type": "module". Importing from a CommonJS file with require("chowbea-axios") will fail with ERR_REQUIRE_ESM. CJS consumers should either use a dynamic import() or migrate the importing file to ESM. The chowbea-axios CLI binary is unaffected — it works regardless of your project's module format. | | Vite | Optional peer dep, >=5.0.0. Only required if you use the chowbea-axios/vite codegen plugins. | | Bun | Required to launch the interactive TUI (the headless CLI works under Node alone). |

⭐ Support

If chowbea-axios helps you ship faster, consider giving it a star! It helps others discover the project and motivates continued development.

Changelog

Release history and per-version changes live in CHANGELOG.md.

Security

Found a security issue? Please follow our responsible disclosure policy — do not file a public GitHub issue.

License

MIT