CLI commands

Your coding agent normally runs these commands for you. This reference is here when you want to inspect the exact interface or understand a command shown in a plan.

Every command supports --json. Run bahama <command> --help for the options available in the installed version.

Project discovery

bahama inspect

Reports non-secret facts about the current workspace:

bahama inspect --json

The report includes framework evidence, package manager and lockfile, scripts, environment-variable names referenced by source, migration-directory presence, and Bahama manifest and lock status. It never reads environment-variable values and never changes the project.

bahama providers [provider-id]

Lists the provider capabilities bundled with the installed CLI:

bahama providers --format agent
bahama providers neon --format agent
bahama providers --format json

The compact list helps an agent shortlist compatible providers. Passing an ID returns that provider’s complete use, avoid, setup, framework or engine, and capability guidance.

bahama doctor

Checks the local runtime and project setup:

bahama doctor --json

Without a manifest, doctor checks Node.js and the basic installation. With a valid bahama.yaml, it also checks the selected providers’ tools and sessions. Requirements are returned as installation_required or auth_required with a specific next action.

Project setup

bahama init

Writes a starter bahama.yaml and ensures .bahama/ is gitignored:

bahama init \
  --name community-notes \
  --application vercel \
  --framework nextjs \
  --database neon

--name, --application, and --framework are required. --database is optional. init validates the generated manifest but never contacts a provider or creates bahama.lock. It refuses to overwrite an existing manifest.

For an established project or a more deliberate setup, your agent may write the manifest directly.

bahama setup

Verifies that the CLI is executable and reports how the selected coding-agent host should receive the Bahama skill:

bahama setup
bahama setup --host codex

Supported host values are auto, codex, claude-code, cursor, and none. Setup does not edit your agent configuration or register an MCP server.

Planning and execution

bahama plan

Validates intent, performs read-only provider probes, and writes an immutable plan under .bahama/plans/:

bahama plan

Planning never creates resources or deploys code. It may stop earlier for a missing tool, authentication, or account decision.

If any step is consequential, the result is approval_required. If every step is routine, the plan returns succeeded; it is still shown for review and is not automatically applied.

bahama apply <plan-id>

Executes one compiled plan:

bahama apply plan_7f4c9b21a3d0
bahama apply plan_7f4c9b21a3d0 --approved

Routine-only plans do not need --approved. A plan with any consequential step does. The flag means a person reviewed that exact plan; an agent must not add it before showing you the important steps and accounts.

Apply validates the saved plan and current manifest, lock, account, and protected configuration. If they no longer match, it refuses the stale plan and the agent creates a new one.

bahama deploy [environment]

Publishes application source to a hosted environment:

bahama deploy production

The environment may be omitted when the manifest contains exactly one hosted environment. A local environment is never deployable.

Deploy compiles a deployment plan and auto-applies it only when every step is routine. The first deployment or any infrastructure-changing deployment stops with approval_required. There is no approval-bypass flag; the agent applies the returned plan ID after your review.

Status and identity

bahama status

Compares the committed identities with live provider state:

bahama status --json

Each resource reports ready, not_ready, unhealthy, or unknown, with a reason when available. Material drift returns decision_required rather than silently repairing or replacing anything.

bahama detach

Forgets the complete resolved stack in this repository without deleting any remote resource:

bahama detach --approved

Without --approved, the command stops and explains the consequences. Detach is intended for a deliberate fork or template copy. It is not a repair command for one missing resource.

Authentication

bahama auth login|status|logout <provider>

bahama auth status bahama-cloud
bahama auth login vercel
bahama auth logout neon
bahama auth login bahama-cloud --no-browser

For Vercel and Neon, Bahama launches the official provider CLI and verifies the resulting session. Their credentials remain in provider-owned stores.

Bahama Cloud uses its own browser consent flow and protected CLI credential store. --no-browser keeps the login headless and prints instructions you can finish in another browser.

Global preferences

bahama config path|get|set

Reads or writes non-secret global CLI preferences:

bahama config path
bahama config get example-key
bahama config set example-key example-value

The config file uses the operating system’s normal application-config directory and restrictive permissions. Credentials and secret values never belong in it.

Result envelope

With --json, a command emits one object to stdout:

{
  "protocolVersion": 1,
  "command": "plan",
  "status": "approval_required",
  "message": "Plan plan_7f4c9b21a3d0 needs approval.",
  "data": {},
  "requirements": [],
  "decisions": [],
  "warnings": []
}

The data shape depends on the command. Requirements carry installation or login guidance. Decisions carry choices and, when appropriate, an exact writeBack path in bahama.yaml.

Exit codes

Always read the envelope status. Exit code 0 does not necessarily mean the requested outcome is finished.