aurora-catalyst-cli

A new CLI generated with oclif

• aurora-catalyst-cli
• Usage
• Commands
• Command Topics
• Sheets (Google Sheets Sync)
• List configured bounded contexts
• Validate connection to a spreadsheet
• Push YAML schemas to Google Sheets
• Pull from Google Sheets to YAML files
• Show differences between YAML and Sheets
• Deploy
• Deploy all environments
• Deploy only dev
• Dry run — show what would be pushed without executing
• Custom config path
• Provision Setup
• Global passwords (used as fallback for all environments)
• Per-environment passwords (take priority over global)
• DEV_FTP_PASSWORD=dev-ftp-pass
• PROD_FTP_PASSWORD=prod-ftp-pass
• DEV_DB_PASSWORD=dev-db-pass
• PROD_DB_PASSWORD=prod-db-pass
• 1. Generate key (one time per machine)
• 2. Copy to server (will ask for root password)
• 3. Verify
• Provision all environments (passwords from .env)
• Provision only dev
• Provision only prod backend
• Provision only frontend (all environments)
• Skip DNS and CI/CD (applies to all plans)
• Pass passwords inline (overrides .env)

Usage

$ npm install -g @aurorajs.dev/catalyst-cli
$ catalyst COMMAND
running command...
$ catalyst (--version)
@aurorajs.dev/catalyst-cli/2.0.0 darwin-arm64 node-v24.16.0
$ catalyst --help [COMMAND]
USAGE
  $ catalyst COMMAND
...

Commands

Command Topics

• catalyst add - Add an Aurora package to an existing project.
• catalyst ai - AI provider configuration sync (CLAUDE.md, AGENTS.md, skills symlinks)
• catalyst autocomplete - Display autocomplete installation instructions.
• catalyst deploy - Deploy Aurora projects
• catalyst env - Encrypt/decrypt environment files with SOPS
• catalyst generate - Generate a module's source code from its YAML definition.
• catalyst help - Display help for catalyst.
• catalyst keys - Generate RSA private key and public key (defaults to ./backend/.keys)
• catalyst new - Create a new Aurora monorepo project.
• catalyst origin - Manage .origin files emitted by catalyst generate
• catalyst pipeline - Generate a deploy workflow from templates (interactive).
• catalyst plugins - List installed plugins.
• catalyst provision - Provision Aurora project infrastructure (DNS + Hosting + CI/CD)
• catalyst sheets - Bidirectional sync between Aurora YAML schemas and Google Sheets

Sheets (Google Sheets Sync)

Bidirectional sync between Aurora YAML schemas and Google Sheets. Each bounded context maps to a spreadsheet where module schemas can be collaboratively edited.

Prerequisites

1. Google Service Account

Create a service account in Google Cloud Console with Google Sheets API enabled, then base64-encode the JSON key:

base64 -i service-account.json

Add it to your .env:

GOOGLE_SERVICE_ACCOUNT=eyJ0eXBlIjoic2VydmljZV9hY2NvdW50Ii...

Share each spreadsheet with the service account email (with Editor access).

2. Config

Add a sheets section to aurora.yaml:

sheets:
  bounded_contexts:
    iam:
      spreadsheet_id: 'YOUR_SPREADSHEET_ID'
      description: 'Identity and Access Management'
    common:
      spreadsheet_id: 'YOUR_SPREADSHEET_ID'
      description: 'Common module schemas'

YAML schemas are expected in ./cliter/{bounded_context}/*.aurora.yaml.

Usage

# List configured bounded contexts
catalyst sheets list

# Validate connection to a spreadsheet
catalyst sheets validate --bc iam

# Push YAML schemas to Google Sheets
catalyst sheets push --bc iam
catalyst sheets push --all
catalyst sheets push --all --dry-run

# Pull from Google Sheets to YAML files
catalyst sheets pull --bc iam
catalyst sheets pull --all
catalyst sheets pull --all --no-backup

# Show differences between YAML and Sheets
catalyst sheets diff --bc iam
catalyst sheets diff --all --summary

Without --bc or --all, commands prompt interactively for the bounded context.

Deploy

Trigger CI/CD pipelines by pushing source branches to environments/{env}. The GitHub Actions workflow is configured to run on push to environments/**.

Each environment in aurora.yaml has an optional source field (defaults to main) that specifies which branch to push:

environments:
  dev:
    source: main # pushes main → environments/dev
  prod:
    source: qa # promotes qa → environments/prod

Usage

# Deploy all environments
catalyst deploy

# Deploy only dev
catalyst deploy --env dev

# Dry run — show what would be pushed without executing
catalyst deploy --dry-run

# Custom config path
catalyst deploy --env prod -c ../aurora.yaml

Internally, the command runs git push origin {source}:environments/{env} for each resolved environment.

Provision Setup

Prerequisites

1. Environment variables

Create a .env file in your project root (next to aurora.yaml):

IONOS_API_KEY=prefix.secret
PLESK_API_KEY=your-plesk-api-key
PLESK_HOST=plesk.yourserver.com
PLESK_SSH_KEY=~/.ssh/plesk.yourserver.com
PLESK_SSH_USER=root

# Global passwords (used as fallback for all environments)
FTP_PASSWORD=your-ftp-password
DB_PASSWORD=your-db-password

# Per-environment passwords (take priority over global)
# DEV_FTP_PASSWORD=dev-ftp-pass
# PROD_FTP_PASSWORD=prod-ftp-pass
# DEV_DB_PASSWORD=dev-db-pass
# PROD_DB_PASSWORD=prod-db-pass

2. SSH access to Plesk server

The deploy key installation on the Plesk server requires SSH access. If SSH is not available, the CLI will show a warning with the public key to install manually — it does not block the deployment.

To set up SSH access, generate a key named after the server and copy it:

# 1. Generate key (one time per machine)
ssh-keygen -t ed25519 -C "aurora-cli@PLESK_HOST" -f ~/.ssh/PLESK_HOST -N ""

# 2. Copy to server (will ask for root password)
ssh-copy-id -i ~/.ssh/PLESK_HOST.pub root@PLESK_HOST

# 3. Verify
ssh -i ~/.ssh/PLESK_HOST root@PLESK_HOST "echo OK"

Replace PLESK_HOST with your actual server hostname (e.g., s14.beopen.cloud).

Then add the key path to your .env:

PLESK_SSH_KEY=~/.ssh/PLESK_HOST

3. Project config

Copy aurora.example.yaml to aurora.yaml in your project and fill in your values.

Usage

# Provision all environments (passwords from .env)
catalyst provision

# Provision only dev
catalyst provision --env dev

# Provision only prod backend
catalyst provision --env prod --target back

# Provision only frontend (all environments)
catalyst provision --target front

# Skip DNS and CI/CD (applies to all plans)
catalyst provision --skip-dns --skip-cicd

# Pass passwords inline (overrides .env)
catalyst provision --ftp-password s3cret --db-password dbpass

GitHub secrets and variables are prefixed with ENV_TARGET_ (e.g., DEV_BACK_SSH_PRIVATE_KEY, PROD_FRONT_SERVER_HOST).