Reference
CLI reference
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.
Global options:
| Option | |
|---|---|
-v, --version |
output the version number |
--api-url <url> |
Ahena API URL (default: $AHENA_API_URL) |
Environment: AHENA_API_URL (API to use), AHENA_TOKEN (CI token or session token instead of ahena login), NO_COLOR.
Commands
ahena login
Sign in with your browser (device login)
| Option | |
|---|---|
--no-browser |
Don't open the browser automatically |
--force |
Sign in again even if already signed in |
ahena logout
Sign out and revoke this machine's session
ahena whoami
Show the signed-in user and organizations
| Option | |
|---|---|
--json |
Machine-readable output |
ahena init
Create or link an Ahena project in this directory
| Option | |
|---|---|
--org <slug> |
Organization slug |
--project <slug> |
Project slug |
--name <name> |
Project name |
-y, --yes |
Accept defaults without prompting |
--recipe <id> |
Start from a recommended stack (see ahena recipe) |
--import |
Declare the stack this repository already uses (detected from package.json and .env.example) |
--domain <domain> |
With --recipe: your app's production domain |
--app-name <name> |
With --recipe: name used in the email sender |
--bundle-id <id> |
With --recipe: iOS bundle ID |
--package-name <name> |
With --recipe: Android package name |
--with <capability> |
With --recipe: include an optional choice (repeatable) |
--without <capability> |
With --recipe: leave a choice out (repeatable) |
--use <capability=provider> |
With --recipe: use a different provider (repeatable) |
ahena recipe [id]
Recommended stacks for common apps (saas, marketplace, mobile, web-app, ecommerce, ai-app)
| Option | |
|---|---|
--apply |
Add the recipe's choices to ahena.config.ts (never overwrites what's there) |
--domain <domain> |
Your app's production domain, e.g. leo.app |
--app-name <name> |
Name used in the email sender |
--bundle-id <id> |
iOS bundle ID |
--package-name <name> |
Android package name |
--with <capability> |
Include an optional choice (repeatable) |
--without <capability> |
Leave a choice out (repeatable) |
--use <capability=provider> |
Use a different provider, e.g. ai=development:ollama,production:anthropic (repeatable) |
-y, --yes |
With --apply: write without asking |
--json |
Machine-readable output |
ahena status
The Stack Graph: what this app uses per environment, health, and what to do next
| Option | |
|---|---|
-e, --env <environment> |
Only this environment |
--json |
Machine-readable Stack Graph |
ahena env list
List environments
ahena env create <name>
Create an environment
| Option | |
|---|---|
--kind <kind> |
local |
ahena env secrets <environment>
List secrets in an environment (masked)
| Option | |
|---|---|
--json |
Machine-readable output |
ahena env set <environment> <name>
Set or rotate a secret (value from stdin or a hidden prompt)
| Option | |
|---|---|
-y, --yes |
Skip the production confirmation |
ahena env reveal <environment> <name>
Print a secret's value, e.g. a webhook signing secret Ahena created (audited; to a terminal unless --raw or --json)
| Option | |
|---|---|
--raw |
Print only the value, even to a pipe or file |
--json |
Machine-readable output, including the value |
-y, --yes |
Skip the production confirmation |
ahena env unset <environment> <name>
Delete a secret
| Option | |
|---|---|
-y, --yes |
Skip confirmation |
ahena connect <provider>
Connect a provider account to an environment
| Option | |
|---|---|
-e, --env <environment> |
Environment slug (default: development) |
--set <KEY=VALUE> |
Non-secret connection setting (repeatable) |
-y, --yes |
Skip confirmations |
ahena disconnect <provider>
Remove a provider connection (never deletes provider resources)
| Option | |
|---|---|
-e, --env <environment> |
Environment slug (default: development) |
-y, --yes |
Skip confirmation |
ahena inspect <provider>
Show what Ahena sees in a connected provider
| Option | |
|---|---|
-e, --env <environment> |
Environment slug (default: development) |
--json |
Machine-readable output |
ahena doctor
Check providers, configuration and repository security (exit code 1 on failures)
| Option | |
|---|---|
-e, --env <environment> |
Only this environment |
--skip-local |
Skip repository checks (.env, committed credentials) |
--fix |
Fix what can be fixed safely; ask before anything else |
-y, --yes |
With --fix: approve confirmation-required fixes |
--allow-billable |
With --fix --yes: also approve billable/destructive fixes |
--json |
Machine-readable output |
ahena configure <provider>
Show proposed changes, then apply them after approval
| Option | |
|---|---|
-e, --env <environment> |
Environment slug (default: development) |
--site-url <url> |
Auth site URL |
--add-redirect <url> |
Allow an auth redirect URL (repeatable) |
--remove-redirect <url> |
Remove an auth redirect URL (repeatable) |
--desired <file> |
JSON file with the desired provider configuration |
--records-from <provider> |
Add the DNS records another provider needs (e.g. resend) |
--with-dmarc |
With --records-from: also add a DMARC record (p=none) |
-y, --yes |
Apply without asking (changes that matter are still approved in the dashboard) |
--allow-billable |
With --yes: also apply changes that may be billed or can't be undone |
--no-wait |
Print the dashboard approval link and exit (code 4) instead of waiting |
--approval <id> |
Apply with a change approved in the dashboard (from --no-wait) |
ahena lock
Record the stack in ahena.lock (git-safe) for teammates and drift checks
| Option | |
|---|---|
-e, --env <environment> |
Only this environment |
--json |
Machine-readable output |
ahena sync
Check this repository's stack is connected; connect what's missing
| Option | |
|---|---|
-e, --env <environment> |
Only this environment |
--no-connect |
Only report; don't offer to connect |
-y, --yes |
Connect without asking first |
ahena plan
Ahena Plan: every change needed to match ahena.config.ts, across providers, plus steps only you can do
| Option | |
|---|---|
-e, --env <environment> |
Only this environment |
--json |
Machine-readable plans |
ahena apply [plan]
Approve and apply a plan (or plan now, then apply), then refresh ahena.lock
| Option | |
|---|---|
-e, --env <environment> |
Only this environment (when planning now) |
-y, --yes |
Don't prompt: apply safe and confirmation-required changes (changes that matter are still approved in the dashboard) |
--allow-billable |
With --yes: also apply billable/destructive changes |
--no-wait |
Print the dashboard approval link and exit (code 4) instead of waiting; run ahena apply <plan> once approved |
--json |
Machine-readable result |
ahena diff
Show the plan and apply it in one step (same as plan + apply, without a stored plan)
| Option | |
|---|---|
-e, --env <environment> |
Only this environment |
--apply |
Apply without the final Apply? prompt (billable changes still ask) |
-y, --yes |
Don't prompt: apply safe and confirmation-required changes |
--allow-billable |
With --yes: also apply billable/destructive changes |
--json |
Machine-readable plan (read-only unless --apply) |
ahena drift
Find provider changes made outside Ahena since ahena.lock was written
| Option | |
|---|---|
-e, --env <environment> |
Only this environment |
--accept |
Accept the current configuration (update ahena.lock) |
--fix |
Restore what ahena.config.ts declares |
-y, --yes |
With --fix: don't prompt |
--allow-billable |
With --fix --yes: also apply billable/destructive changes |
--json |
Machine-readable output; exit code 1 when drift is found |
ahena mcp
Run the Ahena MCP server on stdio for AI coding agents (read-only unless --allow-write)
| Option | |
|---|---|
--allow-write |
Enable write tools; any change that isn't classified SAFE still needs your approval |
ahena deploy-check
Fail CI when an environment isn't ready to deploy (secrets, credentials, drift, migrations, webhooks, callbacks)
| Option | |
|---|---|
-e, --environment <environment> |
Environment to check (default: production) |
--strict |
Treat warnings as failures |
--format <format> |
text |
--skip-local |
Skip repository checks and local providers |
--json |
Machine-readable output |
ahena ci init
Write a GitHub Actions workflow that runs ahena deploy-check
| Option | |
|---|---|
-e, --environment <environment> |
Environment to check (default: production) |
--force |
Replace an existing workflow file |
ahena ci token create
Create a token (shown once)
| Option | |
|---|---|
--label <label> |
What it's for (default: GitHub Actions) |
--days <days> |
Days until it expires (max 365) (default: 90) |
--raw |
Print only the token, for piping into a secret store |
ahena ci token list
List this project's CI tokens
| Option | |
|---|---|
--json |
Machine-readable output |
ahena ci token revoke <id>
Revoke a CI token
ahena add [items...]
Add a capability (database, auth, storage, email, payments, push, ai): declare → connect → plan → apply. Other names are feature packs (profiles, teams, subscriptions…)
| Option | |
|---|---|
-e, --env <environment> |
With capabilities: the environment to connect and apply (default: development) |
--domain <domain> |
With capabilities: your app's production domain |
--use <capability=provider> |
With capabilities: use a different provider (repeatable) |
--allow-billable |
With --yes: also apply billable/destructive changes |
--no-wait |
With capabilities: print the dashboard approval link and exit (code 4) instead of waiting |
--dry-run |
Feature packs: show what would be written |
--force |
Feature packs: replace generated files you edited (migrations are never rewritten) |
-y, --yes |
Don't ask for confirmation |
ahena switch <capability> <from> <to>
Switch a capability to another provider, e.g. ahena switch ai ollama openai -e production
| Option | |
|---|---|
-e, --env <environment> |
Only this environment (default: every environment using <from>) |
--model <model> |
With ai: the model to use with the new provider |
--dry-run |
Classify and report without changing anything |
--test |
Run your project's tests afterwards |
-y, --yes |
Don't ask for confirmation |
ahena generate [provider]
Generate the integration layer into src/ahena/ (all connected providers, or one)
| Option | |
|---|---|
-e, --env <environment> |
Environment slug (default: development) |
--framework <name> |
nextjs |
--force |
Replace files you edited since the last generate |
--dry-run |
Show what would be written |