API Guardian

Your AI SDK changed. API Guardian helps you find what may break before you migrate it.

API Guardian is a safety-first CLI for detecting, reviewing, validating, applying, testing, and rolling back supported AI API/SDK migrations across JavaScript, TypeScript, and Python projects.

AI SDKs evolve quickly. A migration can touch imports, client construction, request shapes, response handling, and tests. API Guardian is built around a conservative workflow:

Scan -> Detect candidates -> Generate proposal -> Show diff -> Validate
     -> Backup -> Apply -> Validate again -> Test -> Keep or roll back

Unsupported providers are detected but never automatically rewritten just because they were found.

xAI detection covers the official Python xai-sdk, OpenAI-compatible xAI endpoints, and common JavaScript usage such as @ai-sdk/xai. Mistral detection covers the official @mistralai/mistralai and mistralai SDKs.

The current npm package is openai-api-guardian.

npm install -g openai-api-guardian
api-guardian <target-directory>

Or run it without installing globally:

npx openai-api-guardian@latest <target-directory>

The repository's main branch may contain provider support that is newer than the current npm release.

Clone the repository and run a fully local, API-key-free demo:

npm ci
npm run demo:scan

The demo scans a small fixture containing OpenAI, Anthropic Claude, Google Gemini, xAI/Grok, and Mistral usage. It shows human-readable scan output, JSON output, doctor output, supported OpenAI/Gemini migration candidates, and a retired-model warning. It never applies changes.

API Guardian includes an API-key-free scan mode:

api-guardian . --scan

It reports detected providers, languages, API usage locations, migration candidates, and known retired/deprecated model references, then exits without generating proposals or modifying files.

Example output:

API Guardian started.
Mode: SCAN
Providers detected: openai (4), anthropic (2), xai (3), mistral (2)
Languages detected: typescript (7), python (4)
API usage locations: 11
Files containing supported API usage: 5
Migration candidates: 2
Affected files: 2
Model lifecycle warnings: 1
- [retired] anthropic: claude-opus-4-1-20250805 -> claude-opus-4-8

Scan finished.
No files were changed.

For coding agents and CI:

api-guardian . --scan --json

The JSON report contains aggregate provider/language counts, migration-candidate counts, and model lifecycle warnings with official source URLs. It does not include API keys or source-code contents.

To make CI fail when supported migration candidates are found:

api-guardian . --scan --json --fail-on-candidates

To fail CI when known retired/deprecated model references are found:

api-guardian . --scan --json --fail-on-deprecations

Model lifecycle warnings are advisory. API Guardian does not automatically replace model IDs because replacement models can change behavior, reasoning settings, quality, or pricing.

Check local readiness without changing files:

api-guardian . --doctor

Doctor mode reports the API Guardian and Node versions, Python validation availability, whether an AI proposal key is configured, detected providers, and migration-candidate count. It never prints the key value.

Preview is the default migration behavior.

api-guardian .
# or
api-guardian . --preview

When migration candidates are found, AI-assisted proposal generation currently requires OPENAI_API_KEY.

API Guardian will:

1. scan the project;
2. find supported migration candidates;
3. generate proposed changes;
4. display diffs;
5. validate proposals;
6. leave original files unchanged.

api-guardian . --apply

Apply mode:

1. prepares and validates every proposal first;
2. creates backups;
3. applies validated changes;
4. validates changed files again;
5. runs project tests when a supported test signal is present;
6. rolls back all changed files if validation or tests fail.

--scan          Scan supported API/SDK usage without requiring an AI API key
--doctor        Check local readiness without modifying files
--json          Emit machine-readable JSON with --scan
--fail-on-candidates
                Exit non-zero when --scan finds migration candidates
--fail-on-deprecations
                Exit non-zero when --scan finds retired/deprecated models
--init-agent <name>
                Install codex, claude, cursor, or github-actions integration
--preview       Generate and validate proposals without changing originals
--apply         Apply validated proposals
--help, -h      Show help
--version, -v   Show API Guardian version

Use only one of --scan, --doctor, --init-agent, --preview, or --apply at a time. --json, --fail-on-candidates, and --fail-on-deprecations are scan-only options.

API Guardian scans:

.ts
.tsx
.mts
.cts
.js
.jsx
.mjs
.cjs
.py

Common generated and dependency directories such as node_modules, dist, build, .git, virtual environments, and API Guardian's own generated files are skipped.

API Guardian includes an advisory registry for model identifiers that providers officially document as retired or deprecated. The initial registry covers documented Anthropic Claude retirements and xAI/Grok retirements, including the announced November 2, 2026 retirement of grok-imagine-image-quality.

These findings are warnings only. They are not fed into automatic migration/apply logic.

API Guardian never applies an AI-generated migration immediately.

Before a source file is changed, the proposal is generated separately and validated. Apply mode creates a backup, re-validates the updated source, runs the project test command when available, and performs an atomic-style rollback of all files changed during that migration attempt when validation or tests fail.

The CLI does not include product telemetry that sends user source code, file paths, or API keys to the maintainer.

The maintainer usage report only reads aggregate npm download statistics and GitHub repository statistics.

• Node.js
• npm
• Python when validating Python migration proposals
• OPENAI_API_KEY only when AI-assisted proposal generation is needed

PowerShell:

$env:OPENAI_API_KEY="your-api-key"

macOS/Linux:

export OPENAI_API_KEY="your-api-key"

Do not commit API keys to source control.

npm ci
npm run build
npm test
npm pack --dry-run

Run scan mode from source:

node dist/index.js . --scan

Run preview mode:

node dist/index.js . --preview

Run apply mode:

node dist/index.js . --apply

Repository templates are available for Codex, Claude Code, Cursor, and GitHub Actions. See docs/AI_AGENT_INTEGRATIONS.md.

The integrations are intentionally scan-first: they do not give an agent blanket permission to rewrite detected providers.

To install one template into a target project without overwriting an existing destination:

api-guardian . --init-agent codex
api-guardian . --init-agent claude
api-guardian . --init-agent cursor
api-guardian . --init-agent github-actions

Each command installs exactly one integration file and refuses to overwrite an existing file.

Near-term priorities:

• strengthen Anthropic migration rules;
• strengthen Gemini migration coverage;
• add safe xAI/Grok migration rules where deterministic rules are possible;
• add Mistral migration rules;
• integrate with coding-agent workflows and CI;
• publish anonymous, opt-in usage metrics only if they can be collected without source code or secrets.

node scripts/usage-report.cjs

The report reads aggregate npm and GitHub statistics. GitHub clone/visitor metrics require a token with traffic access.

If API Guardian finds a provider but misses a migration pattern, open a GitHub issue with a minimal sanitized code example. Never include API keys or private source code.

ISC