API Spector

Local-first API testing tool. Inspect, test and mock APIs. Secrets stay on your machine.

• GUI built with Electron + React
• CLI for running tests and mock servers in CI/CD pipelines
• Robot Framework & Playwright code generation
• AES-256-GCM encrypted secrets, never stored in plain text

Install

npm install -g @testsmith/api-spector

UI not starting after install (common on corporate machines: proxies, antivirus)? See Troubleshooting: the UI won't start.

Usage

GUI

api-spector ui

Opens the desktop app. On first launch you'll be prompted to open or create a workspace.

Run tests

api-spector run --workspace ./my-workspace.spector [options]

Option	Description
--workspace <path>	Path to .spector workspace file (required)
--env <name>	Environment name to activate
--collection <name>	Limit to a specific collection
--tags <a,b>	Comma-separated tag filter
--output <path>	Write results to file (.json or .xml)
--format json|junit	Output format (inferred from --output extension)
--verbose	Print per-request console output and test details
--bail	Stop after first failure

Exit code 0 = all passed, 1 = failures/errors.

Start mock servers

api-spector mock --workspace ./my-workspace.spector [options]

Option	Description
--workspace <path>	Path to .spector workspace file (required)
--name <name>	Start only the named server (repeat for multiple)

Keeps running until Ctrl+C.

Workspaces

A workspace is a .spector file that references your collections, environments and mock servers. Safe to commit to Git. Secrets are encrypted, not stored in plain text.

my-project/
├── my-workspace.spector
├── collections/
│   └── my-api.spector
└── environments/
    ├── dev.env.json
    └── prod.env.json

Encrypted secrets

Secret variables are encrypted with AES-256-GCM using a master password. Set API_SPECTOR_MASTER_KEY in your shell profile to avoid being prompted each session:

macOS / Linux (~/.zshrc or ~/.bashrc):

export API_SPECTOR_MASTER_KEY="your-password"

Windows (PowerShell profile):

$env:API_SPECTOR_MASTER_KEY = "your-password"

Windows (Command Prompt, permanent):

setx API_SPECTOR_MASTER_KEY "your-password"

CI/CD

Set API_SPECTOR_MASTER_KEY as a secret in your pipeline:

# GitHub Actions
env:
  API_SPECTOR_MASTER_KEY: ${{ secrets.API_SPECTOR_MASTER_KEY }}

If the key is not set, encrypted secrets will not be resolved and a warning will appear in the console output.

External secret managers

Instead of storing a secret, reference one in your secret manager and resolve it at run time — nothing is written to the workspace, results, or console. Put a reference in an environment variable (secretRef), an auth field, or inline as {{vault:...}} anywhere in a request (URL, header, body, or script). Built-in backends:

Provider	Reference
HashiCorp Vault	vault:secret/data/app#api_key
AWS Secrets Manager	aws:prod/db#password
Azure Key Vault	azure:acme-kv/db-password
1Password	op://Prod/Database/password

Credentials come from the environment (the same conventions each tool already uses), so the same workspace runs unchanged on a laptop and in CI:

vault login -method=oidc                 # or AWS/Azure/1Password env
api-spector run --workspace ./ws.spector --env prod

The design is pluggable — more backends drop in as providers. See Secret Managers.

Development

# Install dependencies
npm install

# Start in dev mode (hot reload)
npm run dev

# Build
npm run build

# Package as native app (macOS / Windows / Linux)
npm run package

License

API Spector is released under the MIT License: free to use, modify, and distribute, including for commercial purposes.

Copyright (c) 2024-2026 Testsmith.io