# aurora-catalyst-cli

A new CLI generated with oclif

[![oclif](https://img.shields.io/badge/cli-oclif-brightgreen.svg)](https://oclif.io)
[![Version](https://img.shields.io/npm/v/aurora-catalyst-cli.svg)](https://npmjs.org/package/aurora-catalyst-cli)
[![Downloads/week](https://img.shields.io/npm/dw/aurora-catalyst-cli.svg)](https://npmjs.org/package/aurora-catalyst-cli)

<!-- toc -->
* [aurora-catalyst-cli](#aurora-catalyst-cli)
* [Usage](#usage)
* [Commands](#commands)
* [Command Topics](#command-topics)
* [Sheets (Google Sheets Sync)](#sheets-google-sheets-sync)
* [List configured bounded contexts](#list-configured-bounded-contexts)
* [Validate connection to a spreadsheet](#validate-connection-to-a-spreadsheet)
* [Push YAML schemas to Google Sheets](#push-yaml-schemas-to-google-sheets)
* [Pull from Google Sheets to YAML files](#pull-from-google-sheets-to-yaml-files)
* [Show differences between YAML and Sheets](#show-differences-between-yaml-and-sheets)
* [Deploy](#deploy)
* [Deploy all environments](#deploy-all-environments)
* [Deploy only dev](#deploy-only-dev)
* [Dry run — show what would be pushed without executing](#dry-run--show-what-would-be-pushed-without-executing)
* [Custom config path](#custom-config-path)
* [Provision Setup](#provision-setup)
* [Global passwords (used as fallback for all environments)](#global-passwords-used-as-fallback-for-all-environments)
* [Per-environment passwords (take priority over global)](#per-environment-passwords-take-priority-over-global)
* [DEV_FTP_PASSWORD=dev-ftp-pass](#dev_ftp_passworddev-ftp-pass)
* [PROD_FTP_PASSWORD=prod-ftp-pass](#prod_ftp_passwordprod-ftp-pass)
* [DEV_DB_PASSWORD=dev-db-pass](#dev_db_passworddev-db-pass)
* [PROD_DB_PASSWORD=prod-db-pass](#prod_db_passwordprod-db-pass)
* [1. Generate key (one time per machine)](#1-generate-key-one-time-per-machine)
* [2. Copy to server (will ask for root password)](#2-copy-to-server-will-ask-for-root-password)
* [3. Verify](#3-verify)
* [Provision all environments (passwords from .env)](#provision-all-environments-passwords-from-env)
* [Provision only dev](#provision-only-dev)
* [Provision only prod backend](#provision-only-prod-backend)
* [Provision only frontend (all environments)](#provision-only-frontend-all-environments)
* [Skip DNS and CI/CD (applies to all plans)](#skip-dns-and-cicd-applies-to-all-plans)
* [Pass passwords inline (overrides .env)](#pass-passwords-inline-overrides-env)
<!-- tocstop -->

# Usage

<!-- usage -->
```sh-session
$ npm install -g @aurorajs.dev/catalyst-cli
$ catalyst COMMAND
running command...
$ catalyst (--version)
@aurorajs.dev/catalyst-cli/1.0.1 darwin-arm64 node-v24.14.0
$ catalyst --help [COMMAND]
USAGE
  $ catalyst COMMAND
...
```
<!-- usagestop -->

# Commands

<!-- commands -->
# Command Topics

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

<!-- commandsstop -->

# 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:

```bash
base64 -i service-account.json
```

Add it to your `.env`:

```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`:

```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

```bash
# 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:

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

## Usage

```bash
# 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`):

```env
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:

```bash
# 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`:

```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

```bash
# 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`).
