Getting started

Baseline runs local, stateful copies of the third-party APIs your app depends on: Stripe, GitHub, Slack, Google, HubSpot, Salesforce, and 22 more. Each emulator keeps real state, runs the vendor’s OAuth flows, signs its webhooks, and is tested with the vendor’s official SDK. It is built for CI and no-network sandboxes. Not mocks.

Quick start

Requires Node 24 or later.

npx @deploybaseline/cli

With no config file, the eleven default providers start on fixed ports. They keep these ports in every release:

Port	Provider	Port	Provider
`4001`	GitHub	`4008`	Resend
`4002`	Google	`4009`	Stripe
`4003`	Slack	`4010`	Clerk
`4004`	Apple	`4011`	Linear
`4005`	Microsoft	`4012`	Twilio
`4006`	Okta	`3999`	API reference and control API

Start any of the other seventeen by name, alone or next to the defaults. A service started alone listens on 4000:

npx @deploybaseline/cli start --service hubspot
npx @deploybaseline/cli start --service stripe,paypal,square

Every listener binds to IPv4 loopback (127.0.0.1). Start prints each service URL, the API reference at http://localhost:3999/docs, a control token, and an inspector link. The Providers page lists all 28 by category, and each provider’s page shows how to point its SDK at the emulator.

CLI

# Start the eleven default services (no config needed)
npx @deploybaseline/cli

# Start specific services, including ones outside the default set
npx @deploybaseline/cli --service github,jira,salesforce

# Custom port
npx @deploybaseline/cli --port 3000

# Use a seed config file
npx @deploybaseline/cli --seed config.json

# Generate omitted service secrets into a private file
npx @deploybaseline/cli start --seed config.json --generated-secrets-file .baseline-secrets.json

# Keep data, tokens, and webhooks across restarts
npx @deploybaseline/cli --state .baseline/state.json

# Generate a starter config
npx @deploybaseline/cli init

# Generate config for a specific service
npx @deploybaseline/cli init --service github

# Check a config: each problem with its line, the setting, and the fix
npx @deploybaseline/cli validate

# List available services
npx @deploybaseline/cli list

Options

Flag	Default	Description
`-p, —port`	`4000`	Base port (auto-increments per service)
`—host`	`127.0.0.1`	Listening address; use `0.0.0.0` to allow network access
`—single-port`	off	Not supported: each service listens on its own port. See Configuration
`—console-port`	base port − 1	Port for the API reference at `/docs` and the control API
`—no-console`	off	Do not open the console port
`-s, —service`	the 11 defaults	Comma-separated services to enable
`—seed`	auto-detect	Path to seed config (JSON or YAML)
`—base-url`	none	Override the advertised base URL (supports template)
`—generated-secrets-file`	none	Generate omitted service secrets and write them to a new owner-only JSON file
`—state`	none (in memory)	Save state to a JSON file, `sqlite:<path>`, or `libsql://` database and restore it on the next start. See Saved state
`—reset-state`	off	Ignore saved state, reseed from config, and overwrite it
`—watch`	off	Reload on changes to imports and fixtures

The generated-secrets destination must not exist. Baseline removes inherited ACLs, verifies effective owner-only access, and publishes the complete file before startup. Handled startup failures remove the invocation-owned artifact. A hard termination can leave a complete artifact that requires manual recovery. Linux requires setfacl and getfacl from the acl package. The flag fails closed when access controls cannot be verified and is not supported on Windows. The port can also be set via BASELINE_PORT or PORT environment variables. For access from a container or another machine, use npx @deploybaseline/cli start --host 0.0.0.0. Set --base-url to a URL reachable by those clients when using OAuth redirects or other advertised URLs.

Local HTTPS

Baseline serves plain HTTP. For HTTPS URLs, put any reverse proxy in front of it and pass the public URL with --base-url (or BASELINE_BASE_URL). The {service} placeholder is replaced with each service name, so OAuth redirects and webhook URLs use the proxy address. With Caddy and locally trusted certificates:

{
  local_certs
}

github.localhost {
  reverse_proxy 127.0.0.1:4001
}

google.localhost {
  reverse_proxy 127.0.0.1:4002
}

caddy trust     # install Caddy's local CA once
caddy run       # in the directory with the Caddyfile
npx @deploybaseline/cli start --base-url "https://{service}.localhost"

Add one site block per service you use. *.localhost resolves to the loopback address, so no hosts file entry is needed. mkcert with any other reverse proxy works the same way. For any other proxy or domain:

npx @deploybaseline/cli start --base-url "https://{service}.myproxy.test"

Per-service overrides are also supported in the seed config. They take priority over every other base URL source:

{
  "github": {
    "baseUrl": "https://github.localhost"
  }
}

Programmatic API

You can also use Baseline as a library in your tests. See the Programmatic API page for createEmulator, Vitest/Jest setup, and instance methods.

Where to go next

Providers

All 28 emulators by category, with behavior, seed config, and limits.

API reference

Every route each emulator serves, at /docs on your machine while it runs.

Configuration

Seed data, tokens, ports, and per-service options in baseline.config.json, and validate to check it.

Contributing

Run Baseline from source, add a provider, and how the checks work.

Configuration

Custom emulators

Reference

Getting started

Quick start

CLI

Options

Local HTTPS

Programmatic API

Where to go next

Providers

API reference

Configuration

Contributing

​Quick start

​CLI

​Options

​Local HTTPS

​Programmatic API

​Where to go next

Providers

API reference

Configuration

Contributing

Quick start

CLI

Options

Local HTTPS

Programmatic API

Where to go next