CLI Commands

All typed-fetch CLI commands can be run with npx typed-fetch <command>.

init

Initialize a new typed-fetch configuration in your project.

npx typed-fetch init

Creates typed-fetch.config.json with values tailored to your project. The command reads your tsconfig chain — handling references, extends, and tsconfig.app.json — and auto-detects the correct generatedPath so generated types land where TypeScript is already looking.

Example output:

Initialized typed-fetch.config.json
Detected tsconfig.app.json → generatedPath: src/generated/typed-fetch.d.ts

If no tsconfig is found it falls back to src/generated/typed-fetch.d.ts and warns you to verify the path is within your tsconfig include.

Also adds .typed-fetch/ to .gitignore automatically.

Options:

• --config <path>: Write config to a custom path
• --force: Overwrite an existing config file

generate

Generate TypeScript type definitions from the registry.

npx typed-fetch generate

Reads the registry (.typed-fetch/registry.json) and emits TypeScript declarations to the path specified in config (src/generated/typed-fetch.d.ts by default).

This command:

• Analyzes all observed response shapes
• Generates discriminated union types per endpoint
• Creates TypeScript module augmentation for TypedFetchGeneratedResponses
• Produces human-readable, formatted output

Options:

• --config <path>: Use a custom config file path

Example output (src/generated/typed-fetch.d.ts):

declare module '@phumudzo/typed-fetch' {
  interface TypedFetchGeneratedResponses {
    'GET /user/:id': {
      200: {
        id: number;
        name: string;
        email: string;
      };
      404: null;
    };
    'POST /user': {
      201: {
        id: number;
        name: string;
      };
      400: {
        error: string;
      };
    };
  }
}

check

Validate the registry and configuration.

npx typed-fetch check

Performs validation checks:

• Ensures typed-fetch.config.json exists and is valid JSON
• Checks that registry file is readable and valid
• Reports on number of tracked endpoints
• Lists any configuration issues

Useful for CI/CD pipelines to ensure configuration integrity.

Options:

• --config <path>: Use a custom config file path

clean

Remove generated artifacts and optionally the registry.

npx typed-fetch clean

Removes:

• Generated TypeScript declaration file
• .typed-fetch/ directory (if --registry flag is used)

Options:

• --registry: Also remove the registry file (.typed-fetch/registry.json)
• --generated: Remove the generated declaration file only
• --config <path>: Use a custom config file path

Example: Clean everything including observations

npx typed-fetch clean --registry

watch

Watch for registry changes and automatically regenerate types. Also starts a local HTTP server that receives observations from browser runtimes.

npx typed-fetch watch

When running, watch does two things simultaneously:

1. File watcher — monitors the registry file and regenerates typed-fetch.d.ts whenever it changes
2. HTTP observer server — listens on http://localhost:7779 (configurable via observerPort) and accepts POST /__typed-fetch/observe requests from browser runtimes

This means a single typed-fetch watch process handles type generation for both Node.js and browser API calls — no separate setup needed for any framework (Vite, CRA, Next.js, etc.).

Example output:

Watching .typed-fetch/registry.json
Observer listening on http://localhost:7779
  Press Ctrl+C to stop.
Generated src/generated/typed-fetch.d.ts

Press Ctrl+C to stop.

Options:

• --config <path>: Use a custom config file path

export

Export the registry as JSON.

npx typed-fetch export
npx typed-fetch export --output registry-backup.json

Outputs the registry to stdout or a file. Useful for sharing observed shapes across environments.

Options:

• --output <path>: Write to a file instead of stdout
• --config <path>: Use a custom config file path

import

Merge a registry JSON file into the local registry.

npx typed-fetch import registry-backup.json

Merges shapes from an external registry file into your local registry without overwriting existing observations.

Options:

• --config <path>: Use a custom config file path

Global Options

All commands accept:

• --config <path>: Path to custom config file (default: typed-fetch.config.json)
• --help: Show command help
• --version: Show typed-fetch version

Example with custom config:

npx typed-fetch generate --config ./config/api-types.json
npx typed-fetch watch --config ./monorepo/config.json

Typical Development Workflow

# 1. Initialize project (auto-detects generatedPath from tsconfig)
npx typed-fetch init

# 2. Start watch — handles both file and browser observations (keep running)
npx typed-fetch watch

# 3. Run your app in another terminal
npm run dev

# 4. Use your app / click buttons / make API calls
# Types are regenerated automatically as observations come in

# 5. (Optional) Generate manually when needed
npx typed-fetch generate

CI/CD Integration

# Validate configuration
npx typed-fetch check

# Clean old artifacts
npx typed-fetch clean

# Generate types from committed registry
npx typed-fetch generate

# Run your build
npm run build

Next: Privacy & Data Handling

Learn about Privacy & Data Handling.