watch

The watch command runs a continuous loop that polls your OpenAPI endpoint and regenerates types whenever the spec changes.

Usage

chowbea-axios watch [flags]

What It Does

1. Polls your API endpoint at regular intervals
2. Compares spec hash with cached version
3. Regenerates types and operations when changes detected
4. Preserves cache on graceful shutdown (Ctrl+C)

Flags

Examples

Start Watch Mode

chowbea-axios watch

Custom Polling Interval

# Poll every 5 seconds
chowbea-axios watch --interval 5000

Debug Mode

# See every check cycle
chowbea-axios watch --debug

Output

Normal mode shows only changes:

╭────────────────────────────────────────
│ chowbea-axios watch
├────────────────────────────────────────
│
│ ✓ Starting watch mode - press Ctrl+C to stop (endpoint=http://localhost:3000/docs/swagger/json, intervalMs=10000)
│
│ ✓ New spec detected, regenerating... (cycleId=3, bytes=45231)
│ ✓ Generation completed (cycleId=3, operations=42, duration=1.2s)

Debug mode shows every cycle:

╭────────────────────────────────────────
│ Cycle 1
├────────────────────────────────────────
│   Checking for API changes... (cycleId=1, endpoint=http://localhost:3000/docs/swagger/json)
│   No changes detected, skipping generation (cycleId=1, durationMs=150ms)

Graceful Shutdown

Press Ctrl+C to stop watch mode:

│ ⚠ Shutting down watch mode... (signal=SIGINT)
│ ✓ Cache preserved for next run

The cache is preserved, so your next fetch or watch will continue from where you left off.

Failure Handling

The watch loop is designed to keep going through transient failures without spamming logs when something is permanently broken:

1. A single failed cycle is logged at warn level and the loop continues.
2. Consecutive failures trigger exponential backoff — the wait between cycles is intervalMs × 2^(failures - 1), capped at 5 minutes. A successful cycle resets the counter.
3. After 10 consecutive failures, the loop exits with a clear error so a permanently broken setup (deleted spec file, 401 forever, malformed cached spec) doesn't keep retrying silently.
4. The cache is preserved on shutdown — your next fetch or watch continues from the last known good state.

│ ⚠ Cycle failed, backing off (cycleId=5, failures=3, backoffMs=40000, error=ECONNREFUSED)

Long-running cycles also emit periodic heartbeats so the CLI doesn't appear stalled while a slow fetch is in flight.

Setting Up Concurrent Watch

Run watch mode alongside your dev server with the concurrent script set up by init:

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

Then:

npm run dev:all

This shows both outputs with labels:

[api] │ ✓ Starting watch mode...
[dev] Starting development server...
[dev] Server running at http://localhost:5173
[api] │ ✓ New spec detected, regenerating...

Configuration

You can configure watch behavior in api.config.toml:

# Polling interval (overridden by --interval flag)
poll_interval_ms = 10000

[watch]
# Enable debug logging by default
debug = false

Best Practices

1. Use reasonable intervals - 5-10 seconds is usually enough
2. Enable debug only when troubleshooting
3. Set up concurrent script for seamless development
4. Don't run in production - use fetch in CI/CD instead

Next Steps