init

init is the one-time (or "we're starting over") command. Interactive by default, scriptable when stdin isn't a TTY. It creates config, installs axios, scaffolds the editable client files, and optionally fetches your first spec.

What it does not do: fill _generated/ with contracts and operations. That's fetch's job unless your endpoint isn't localhost and init can reach it on first run.

Usage

chowbea-axios init [flags]

What it does

1. Creates api.config.toml with your settings
2. Installs axios as a project dependency
3. Adds npm scripts (api:fetch, api:watch, etc.)
4. Generates client files (api.client.ts, api.instance.ts, api.error.ts, api.helpers.ts)
5. Optionally sets up concurrent dev script (api:watch + your dev server)
6. Optionally scaffolds a hardened CI workflow at .github/workflows/chowbea-axios-ci.yml
7. Optionally scaffolds the Vite codegen plugins (--with-vite-plugins) for Surfaces and Side Panels
8. Runs initial fetch (if endpoint is not localhost)

The generated entrypoint is api.client.ts. Rename or re-export if your conventions demand it — just stay consistent.

Interactive prompts

1. OpenAPI spec endpoint URL — default http://localhost:3000/docs/swagger/json
2. Output folder location — default app/services/api
3. Package manager — auto-detected from lockfile, or choose manually
4. Concurrent dev script (optional) — api:watch alongside your dev server

Flags

Examples

Basic setup

chowbea-axios init

Non-interactive setup (CI / project starters)

--non-interactive skips every prompt. Supply a spec source via --endpoint or --spec-file:

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

Force overwrite

chowbea-axios init --force

Custom instance configuration

chowbea-axios init \
  --base-url-env "NEXT_PUBLIC_API_URL" \
  --env-accessor "process.env" \
  --auth-mode "bearer-localstorage" \
  --token-key "session-token" \
  --timeout 60000

Skip client generation

chowbea-axios init --skip-client

With Vite plugins

chowbea-axios plugins --setup
# or during init:
chowbea-axios init --with-vite-plugins

Generated files

Output folder is configurable — src/api is the default. api.contracts.ts, api.types.ts, and api.operations.ts land in _generated/ on first fetch, not during init.

After fetch, wire The Query Layer: contracts for types, api.op for calls.

CI workflow template

By default, init scaffolds .github/workflows/chowbea-axios-ci.yml — re-fetches on every PR and fails when generated output is stale.

• permissions: contents: read
• concurrency cancel-in-progress
• Node 22 + npm cache (commented variants for bun/pnpm/yarn)
• Pinned action SHAs
• vars or secrets fallback for STAGING_API_ENDPOINT

Pass --skip-workflow to opt out.

Existing setup detection

Already initialized? Init asks before clobbering:

Existing setup detected:
  - api.config.toml
  - api.instance.ts
  - api.client.ts
Continue with setup? (existing files may be modified) (Y/n)

Use --force to skip the guilt trip.

Concurrent dev script

Optional script running api:watch with your dev server via concurrently:

{
  "scripts": {
    "dev:all": "concurrently --names 'api,dev' \"npm run api:watch\" \"npm run dev\""
  }
}

Next steps

After init:

1. Start your API server (localhost endpoints)
2. Run chowbea-axios fetch to populate _generated/
3. Import api from api.client.ts and build the query layer