init

The init command provides interactive project setup. It creates your configuration, installs dependencies, generates client files, and optionally fetches your first spec.

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)

Interactive Prompts

When you run init, you'll be asked:

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)

   • Combines api:watch with your existing dev scripts

Flags

Examples

Basic Setup

chowbea-axios init

Non-Interactive Setup (CI / project starters)

--non-interactive skips every prompt. You must 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

# Overwrite existing files without prompting
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

# Only create config and scripts, no client files
chowbea-axios init --skip-client

With Vite Plugins

# Scaffold surfaces & side-panels registries and add plugins to vite.config.ts
chowbea-axios init --with-vite-plugins

Generated Files

After running init, your project will have:

The output folder is configurable via --output-folder or the interactive prompt — src/api is the default. The api.contracts.ts, api.types.ts, and api.operations.ts files inside _generated/ are written on the first fetch, not by init.

CI Workflow Template

By default, init scaffolds .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 (with 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

If you already have chowbea-axios set up, init will detect existing files and ask before overwriting:

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 this check.

Concurrent Dev Script

The init command can set up a script that runs api:watch alongside your dev server using concurrently:

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

Next Steps

After init completes:

1. Start your API server (if using localhost endpoint)
2. Run chowbea-axios fetch to generate types
3. Import api from your client file and start making typed requests