• CLI Reference
  • Installation
  • Configuration
    • Environment Variables
    • Config File
  • Authentication
    • NIP-07 (Browser Extension)
    • NIP-46 (Remote Signer)
    • Verify Auth
  • Nostr-native transport
  • Commands
    • Services
    • Environments
    • Deployments
    • State
    • Direct Runtime Actions
    • Artifacts
    • Builds
    • Workers
    • Policies
    • LLM Routes
    • Souls
    • Notifications
    • Adoption
    • Payments
  • Output Formats
  • Global Flags
  • Related

§CLI Reference

The bahia CLI provides command-line access to all Bahia operations.

§Installation

# From source
go install github.com/openagentsinc/bahia/cmd/cli@latest

# Or build locally
cd bahia
make build
./bin/bahia --help

§Configuration

§Environment Variables

§Config File

# ~/.bahia/config.yaml
api_url: "https://bahia.example.com"
relays:
  - "wss://relay.example.com"
auth:
  enabled: true

§Authentication

§NIP-07 (Browser Extension)

# Authenticate with browser extension
bahia auth login --nip07

§NIP-46 (Remote Signer)

# Connect to bunker
bahia auth login --nip46 "bunker://pubkey@relay?secret=..."

§Verify Auth

bahia auth status

§Nostr-native transport

The CLI uses ContextVM JSON-RPC methods over Nostr kind 25910, normally wrapped with CEP-4/NIP-59 gift-wrap (1059 or 21059) when encrypted transport is available. Reads consume canonical observable/state kinds (30900, 4903, 30315, 11316-11320, 30002, 30078) and standard NIPs. Legacy Bahia request kinds are not production CLI transport; they are retained only as startup migration/test fixtures.

Operator relay resolution is deterministic and ordered: explicit --relay values are final and highest priority, BAHIA_NOSTR_RELAYS is second, and trusted bootstrap discovery is used only when both final relay sources are absent. Discovery requires at least one bootstrap relay (--bootstrap-relay or BAHIA_NOSTR_BOOTSTRAP_RELAYS) and at least one trusted service pubkey (--trusted-service-pubkey, BAHIA_NOSTR_TRUSTED_SERVICE_PUBKEYS, or single-service --service-pubkey / BAHIA_NOSTR_SERVICE_PUBKEY). The CLI queries trusted service-authored NIP-51 30002 relay sets until EOSE; the bounded discovery wait is a fail-closed transport guard, not a completion signal, so relay sets are never selected before EOSE. Selection prefers d=bahia-contextvm-v1 across trusted services, falls back to d=bahia-browser-v1 only when no usable ContextVM relay set is present, and resolves multiple trusted service pubkeys by configured order with latest-wins only within the same service pubkey and d tag. If relay OK, CLOSED, or AUTH outcomes leave no usable relay after a signed ContextVM event is accepted, the CLI reports the relay failure rather than falling back to REST unless the explicit HTTP fallback is still in a pre-acceptance failure path.

§Commands

§Services

# List services
bahia services list
bahia services list -o json

# Get service
bahia services get payment-api
bahia services get svc-123 -o yaml

# Create service
bahia services create \
  --name "payment-api" \
  --repository "https://github.com/company/payment-api"

# Update service
bahia services update payment-api \
  --description "Updated description"

# Delete service
bahia services delete payment-api

§Environments

# List environments
bahia environments list

# Get environment
bahia environments get production

# Create environment
bahia environments create \
  --name "Production" \
  --slug "production"

# Update environment
bahia environments update production \
  --requires-approval true

# Delete environment
bahia environments delete staging

§Deployments

Deployment intent creation and rollback publish signed ContextVM JSON-RPC events (service/deploy, service/rollback) with the configured operator signer and relay set. Relay OK acceptance is required before the command reports success. Legacy REST-backed mutation paths and legacy request-kind publication are not production runtime behavior.

# Submit deployment intent (signer-first)
bahia --privkey $BAHIA_NOSTR_PRIVATE_KEY --relay wss://relay.example \
  deployments deploy --service svc-123 --environment env-456 --artifact art-789

# Submit rollback intent (signer-first)
bahia --privkey $BAHIA_NOSTR_PRIVATE_KEY --relay wss://relay.example \
  deployments rollback --service svc-123 --environment env-456

# List intents
bahia deployments list
bahia deployments list --service payment-api

# Get intent
bahia deployments get intent-123

# List runs
bahia deployments runs list
bahia deployments runs get run-456

# View logs
bahia deployments logs run-456 --tail 100

§State

# List state
bahia state list
bahia state list --environment production
bahia state list --service payment-api

# Drifted services
bahia state drifted
bahia state drifted --environment production

§Direct Runtime Actions

Direct runtime deploy/restart/stop REST endpoints have been removed. The CLI surface is ContextVM methods service/deploy, service/restart, and service/stop; production CLI paths do not publish legacy runtime request kinds.

§Artifacts

Artifact registration is a ContextVM Nostr operation. Legacy REST-backed artifact registration command paths are not production CLI mutation transport.

# List artifacts
bahia artifacts list --service-id svc-123

# Get artifact
bahia artifacts get art-456

# SBOM
bahia artifacts sbom art-456
bahia artifacts sbom art-456 --packages

# Signatures
bahia artifacts signatures art-456
bahia artifacts verify art-456

§Builds

# List builds
bahia builds list --service-id svc-123

# Get build
bahia builds get build-123

# Register build
bahia builds register \
  --service-id svc-123 \
  --workflow-id "ci-run-456" \
  --commit-sha "abc123"

§Workers

# List workers
bahia workers list

# Get worker
bahia workers get npub1worker...

# Pricing
bahia workers pricing npub1worker...

§Policies

Policy mutations are signer-first public Nostr operations. bahia policies create publishes signed PolicyCreate (5986) with the configured operator signer, verifies relay OK acceptance, and prints the result/read-model kinds to follow. Policy reads (list, get) remain read-only and may use durable projections/server read models. Legacy REST-backed policy mutation command paths are not production CLI mutation transport.

# List policies (read-only)
bahia policies list

# Get policy (read-only)
bahia policies get require-sbom

# Create policy (signer-first 5986)
bahia --privkey $BAHIA_NOSTR_PRIVATE_KEY --relay wss://relay.example \
  policies create \
  --name require-sbom \
  --rules '[{"type":"require_sbom"}]' \
  --enforcement block \
  --idempotency-key policy-create-require-sbom

§LLM Routes

# List routes
bahia llm routes list

# Get route
bahia llm routes get gpt4-proxy

# Releases
bahia llm releases list --route-id route-123

# Deploy
bahia llm deploy \
  --route-id route-123 \
  --release-id release-456 \
  --environment production

# Approve
bahia llm approve intent-123

# Rollback
bahia llm rollback \
  --route-id route-123 \
  --environment production

# State
bahia llm state list
bahia llm state drifted

LLM route creation and release registration are ContextVM Nostr operations. Legacy request kinds such as 5971/5972 are startup migration inventory only and are not production CLI mutation transport.

§Souls

# List souls
bahia souls list
bahia souls list --status active

# Get soul
bahia souls get scout

# Provision
bahia souls provision scout \
  --template "31950:pubkey:research-agent" \
  --tier standard \
  --follow

bahia souls provision codebot \
  --brief "A code review specialist" \
  --tier heavy

# Lifecycle
bahia souls suspend scout --reason "Maintenance"
bahia souls resume scout
bahia souls revoke scout --reason "No longer needed"
bahia souls redeploy scout
bahia souls regenerate scout --brief "New purpose..."

# Templates
bahia souls templates list
bahia souls templates get research-agent

§Notifications

# List channels
bahia notifications channels list

# Get channel
bahia notifications channels get channel-123

# Create channel
bahia notifications channels create \
  --name "Deploy Alerts" \
  --type webhook \
  --config url="https://hooks.example.com/bahia"

# Update channel
bahia notifications channels update channel-123 \
  --events deployment.completed,deployment.failed

# Delete channel
bahia notifications channels delete channel-123

# Test channel
bahia notifications channels test channel-123

# Logs
bahia notifications log --limit 50

§Adoption

# Scan for containers
bahia adopt scan \
  --target name=prod,endpoint_ref=prod-docker

# Import discovered containers
bahia adopt import \
  --target name=prod,endpoint_ref=prod-docker \
  --all

§Payments

# Estimate cost
bahia payments estimate \
  --service-id svc-123 \
  --environment-id env-456

# Get run cost
bahia payments cost run-789

# Payment history
bahia payments history
bahia payments history --worker npub1worker...

§Output Formats

# Table (default)
bahia services list

# JSON
bahia services list -o json

# YAML
bahia services get payment-api -o yaml

§Global Flags

§Related

• Getting Started — Setup guide
• MCP Tools — Programmatic access
• Nostr Integration — Event model