AHENA
Documentation menu

Guides

Switching providers

Uses the Ahena CLI (beta). Install it with npm install -g @ahena/cli, or prefix commands with npx @ahena/cli. See Installation. The dashboard covers projects, connections, Doctor, the Stack Graph, plans and approvals without it.

ahena switch ai ollama openai -e development
ahena switch ai openai anthropic -e production --dry-run
ahena switch email resend postmark

ahena switch <capability> <from> <to>:

  1. Finds where ahena.config.ts uses <from> for the capability (all environments, or -e).
  2. Scans your code for anything that bypasses the common interface (ahena.<capability>.raw, direct imports of the old provider's SDK) and reports it as file:line.
  3. Classifies the switch (below) and lists the data that stays with the old provider.
  4. Asks before changing anything (--dry-run stops here).
  5. Connects and verifies <to> where it isn't connected yet (credentials from you, as always).
  6. Updates ahena.config.ts, per environment if only some environments move. For AI it also sets the new provider's default model (--model to choose).
  7. Regenerates the adapter and the environment schema (.env.example, generated/env.ts).
  8. Runs Doctor against the new provider and, with --test, your project's test script.
  9. Writes a migration report to docs/ahena/switches/<date>-<capability>-<from>-to-<to>.md (what was done, what's left, data that didn't move, verification, rollback).

The old provider is never disconnected or deleted. Roll back with the reverse switch; disconnect it yourself when you're done.

Classifications

Class Meaning Today
compatible The app only uses the common interface; the new adapter is a drop-in. Still test behaviour, limits and cost. AI (OpenAI, Anthropic, Ollama)
partially compatible Adapter generated, but some code or setup is manual. AI with direct SDK use; email (new domain verification, webhooks, suppression lists)
manual migration Data lives at the old provider and must be moved. Ahena switches config and code, never the data. database, auth, storage, payments, push
unsupported Ahena can't connect the target provider yet. Nothing is changed. any provider Ahena doesn't ship

Ahena never claims a switch is effortless when data or application changes are required.