# 30-Jan-2026 — NGX Ramblers CLI Reference Guide

The NGX Ramblers CLI provides a unified command-line interface for managing environments, deployments, and local development. This guide covers all available commands with examples and comparisons to the Admin UI where applicable.

## Prerequisites

Before using the CLI, ensure you have:

- Node.js v22.19.0 or later
- Access to the NGX-Ramblers repository
- Secrets files in `non-vcs/secrets/` directory (contain AWS credentials, fly.io tokens, MongoDB URIs, etc.)
- AWS admin credentials in environment variables (only needed for `aws create-resources` command)

## Running the CLI

From the project root directory:

```bash
npm run cli -- <command> [options]
```

The CLI will automatically install dependencies if needed (when `package-lock.json` changes).

### Global Installation (Optional)

To use `ngx-cli` from any directory, run once in the project root:

```bash
npm link
```

Then you can use:

```bash
ngx-cli <command> [options]
```

---

## Command Overview

```
Usage: ngx-cli [options] [command]

NGX-Ramblers environment management CLI

Commands:
  environment|env               Environment management commands
  fly|f                         fly.io deployment commands
  database|db                   Database management commands
  aws|a                         AWS resource management commands
  validate|val                  Validation commands for credentials and connections
  destroy|des <name>            Destroy an environment completely
  local|l                       Run the app locally in dev or production mode
  backup|bak                    Backup and restore commands
```

### Command Aliases

All commands support short aliases for faster typing:

| Full Command | Alias | Example |
|--------------|-------|---------|
| `environment` | `env` | `ngx-cli env list` |
| `database` | `db` | `ngx-cli db seed dev-group` |
| `validate` | `val` | `ngx-cli val aws-admin` |
| `destroy` | `des` | `ngx-cli des test-env` |
| `local` | `l` | `ngx-cli l dev my-group` |
| `fly` | `f` | `ngx-cli f deploy new-group` |
| `aws` | `a` | `ngx-cli a create-resources new-group` |
| `backup` | `bak` | `ngx-cli bak create my-group` |

---

## Interactive Mode

When you run commands without specifying required arguments, the CLI enters interactive mode with a clear screen and selection menu.

### Keyboard Navigation

| Key | Action |
|-----|--------|
| `Arrow keys` | Navigate options |
| `Enter` | Select option |
| `ESC` | Go back to previous step |
| `q` | Quit immediately |
| `Ctrl+C` | Quit immediately |

Navigation hints are displayed at the bottom of selection menus:

```
? Select an environment: (Use arrow keys)
> my-group (ngx-ramblers-my-group)
  dev-group (ngx-ramblers)
  another-group (ngx-ramblers-another-group)
  ──────────────
  [q/Ctrl+C: quit]
```

---

## Local Development Commands

The `local` (or `l`) command replaces shell scripts for running the application locally.

### List Available Environments

```bash
ngx-cli l list
```

**Output:**

```
Available environments:

  my-group - ngx-ramblers-my-group (ready)
  dev-group - ngx-ramblers (ready)
  another-group - ngx-ramblers-another-group (ready)
  third-group - ngx-ramblers-third-group (ready)
  new-group - ngx-ramblers-new-group (ready)
```

The status shows:
- **ready**: Secrets file exists and environment is configured
- **missing secrets**: No secrets file found for this environment

### Development Mode (Hot Reload)

Start the application with hot module reloading for both frontend and backend:

```bash
ngx-cli l dev [environment] [options]
```

**Options:**

| Option | Description | Default |
|--------|-------------|---------|
| `-p, --port <port>` | Backend port | 5001 |

**Examples:**

```bash
# Direct - specify environment
ngx-cli l dev my-group

# With custom port
ngx-cli l dev my-group -p 3000

# Interactive - select from menu
ngx-cli l dev
```

**Output:**

```
========================================
Starting in DEVELOPMENT mode
========================================
Environment: my-group
App Name: ngx-ramblers-my-group
Port: 5001
Frontend: http://localhost:4200
Backend: http://localhost:5001
========================================

Starting Backend (tsx watch)...
Starting Frontend (ng serve)...
```

This runs:
- **Frontend**: `ng serve` with hot reload on http://localhost:4200
- **Backend**: `tsx watch` with hot reload on http://localhost:5001

**Port Checking:** The CLI checks if ports are available before starting and will display an error if they're in use.

### Production Mode

Build and run a production build locally:

```bash
ngx-cli l prod [environment] [options]
```

**Options:**

| Option | Description | Default |
|--------|-------------|---------|
| `-p, --port <port>` | Server port | 5001 |

**Examples:**

```bash
ngx-cli l prod dev-group
ngx-cli l prod dev-group -p 8080
```

This:
1. Builds the Angular frontend with production optimisations
2. Starts the Express server serving the bundled application

---

## Environment Management Commands

### List Configured Environments

```bash
ngx-cli env list
```

**Output:**

```
Configured environments:

  my-group
    App: ngx-ramblers-my-group
    Memory: 1gb
    Scale: 1
    Organisation: personal
    API Key: Yes

  new-group
    App: ngx-ramblers-new-group
    Memory: 1024mb
    Scale: 1
    Organisation: personal
    API Key: Yes
```

**Admin UI Equivalent:** Navigate to *Admin > Backup & Restore > Settings* to view configured environments.

### Show Environment Details

```bash
ngx-cli env show <name>
```

**Example:**

```bash
ngx-cli env show my-group
```

### Resume Environment Setup

Resume a partially completed environment setup:

```bash
ngx-cli env resume <name> [options]
```

**Options:**

| Option | Description |
|--------|-------------|
| `--db-init` | Run database initialisation |
| `--fly-deploy` | Run fly.io deployment |

**Examples:**

```bash
# Resume and deploy to fly.io
ngx-cli env resume new-group --fly-deploy

# Resume and reinitialise database
ngx-cli env resume new-group --db-init

# Both
ngx-cli env resume new-group --db-init --fly-deploy
```

**Admin UI Equivalent:** Navigate to *Admin > Environment Setup*, select "Manage Existing Environment", choose your environment, and click "Resume Setup".

### Update Ramblers Info

Update the Ramblers API information in an environment's secrets file:

```bash
ngx-cli env update-ramblers <name> --api-key <key> --area-code <code> --area-name <name> --group-code <code> --group-name <name>
```

---

## fly.io Deployment Commands

### Deploy to fly.io

Deploy an environment to fly.io:

```bash
ngx-cli f deploy <name> [options]
```

**Options:**

| Option | Description | Default |
|--------|-------------|---------|
| `--app-name <appName>` | fly.io app name | ngx-ramblers-{name} |
| `--memory <memory>` | Memory allocation | 512mb |
| `--scale <count>` | Number of instances | 1 |
| `--org <organization>` | fly.io organization | personal |

**Examples:**

```bash
ngx-cli f deploy new-group
ngx-cli f deploy new-group --memory 1024mb --scale 1
```

**Admin UI Equivalent:** In *Admin > Environment Setup*, complete the wizard and click "Create Environment" or use "Resume Setup" with the "Deploy to fly.io" option checked.

### Scale fly.io App

Adjust resources for a running fly.io app:

```bash
ngx-cli f scale <appName> [options]
```

**Options:**

| Option | Description |
|--------|-------------|
| `--count <count>` | Number of instances |
| `--memory <memory>` | Memory allocation (e.g., 512mb, 1gb) |

**Examples:**

```bash
ngx-cli f scale ngx-ramblers-example --memory 1gb
ngx-cli f scale ngx-ramblers-example --count 2
```

### Generate Deploy Token

Generate a deploy token for an app:

```bash
ngx-cli f token <appName>
```

**Example:**

```bash
ngx-cli f token ngx-ramblers-new-group
```

---

## AWS Resource Commands

### Create AWS Resources

Create S3 bucket and IAM user for a new environment:

```bash
ngx-cli a create-resources <name> [options]
```

**Options:**

| Option | Description | Default |
|--------|-------------|---------|
| `--region <region>` | AWS region | eu-west-1 |

**Examples:**

```bash
ngx-cli a create-resources new-group
ngx-cli a create-resources new-group --region eu-west-2
```

This creates:
- S3 bucket: `ngx-ramblers-new-group`
- IAM user: `ngx-ramblers-new-group-user`
- IAM policy with S3 permissions
- Access key credentials (saved to secrets file)

**Admin UI Equivalent:** This is performed automatically during environment creation in *Admin > Environment Setup*.

### Copy Standard Assets

Copy standard assets (logos, images) to an environment's S3 bucket:

```bash
ngx-cli a copy-assets <bucket>
```

**Example:**

```bash
ngx-cli a copy-assets ngx-ramblers-new-group
```

---

## Database Commands

### Seed Database

Populate a database with sample data and run migrations:

```bash
ngx-cli db seed <name> [options]
```

**Or using connection details directly:**

```bash
ngx-cli db seed --uri "mongodb+srv://cluster.mongodb.net" --database "ngx-ramblers-new-group" --group-name "My Walking Group"
```

**Options:**

| Option | Description |
|--------|-------------|
| `--uri <uri>` | MongoDB connection URI (alternative to name) |
| `--database <database>` | Database name (required with --uri) |
| `--group-name <groupName>` | Group name for sample data (required with --uri) |
| `--fresh` | Clear changelog and page content before seeding (runs all migrations fresh) |
| `--sync` | Run full data sync from Ramblers API after seeding |

**Examples:**

```bash
# Basic seed - creates sample pages and runs pending migrations
ngx-cli db seed dev-group

# Fresh seed - clears existing data and runs all migrations from scratch
ngx-cli db seed new-group --fresh

# Seed with data sync - also pulls walks from Ramblers API
ngx-cli db seed new-group --sync

# Full fresh setup with data sync
ngx-cli db seed new-group --fresh --sync
```

**What happens during seeding:**
1. Sample page content is created (home, walks, about-us, contact-us, admin)
2. All pending database migrations run automatically
3. Admin menu items are populated via migrations
4. (With `--sync`) Walks are fetched from the Ramblers API

**Admin UI Equivalent:** Database seeding happens automatically during environment creation. For existing environments, use the backup/restore functionality in *Admin > Backup & Restore*.

### Run Database Migrations

Run pending database migrations without seeding:

```bash
ngx-cli db migrate <name>
```

**Example:**

```bash
ngx-cli db migrate dev-group
```

**Output:**

```
Running pending migrations...
Status: 18 applied, 2 pending, 0 failed
✓ Applied 2 migration(s)
  - 20260129000000-add-environment-setup-menu-item.js
  - 20260130000000-add-venue-settings-menu-item.js
```

### Validate Database Connection

Test MongoDB connectivity:

```bash
ngx-cli db validate <name>
```

**Example:**

```bash
ngx-cli db validate dev-group
```

---

## Backup and Restore Commands

The `backup` (or `bak`) command provides database backup and restore functionality.

### List Backup Environments

```bash
ngx-cli bak list
```

**Output:**

```
Configured backup environments:

  my-group
    Database: ngx-ramblers-my-group
    S3 Bucket: ngx-ramblers-my-group

  dev-group
    Database: ngx-ramblers
    S3 Bucket: ngx-ramblers
```

### Create a Backup

Create a backup of an environment's database:

```bash
ngx-cli bak create [environment] [options]
```

**Options:**

| Option | Description | Default |
|--------|-------------|---------|
| `--no-upload` | Don't upload to S3 (local only) | Upload enabled |
| `--collections <collections>` | Comma-separated list of collections | All collections |

**Examples:**

```bash
# Backup with S3 upload (default)
ngx-cli bak create my-group

# Backup without S3 upload (local only)
ngx-cli bak create my-group --no-upload

# Backup specific collections only
ngx-cli bak create my-group --collections walks,members,pageContent

# Interactive - select from menu
ngx-cli bak create
```

**What happens during backup:**
1. Connects to the environment's MongoDB database
2. Runs `mongodump` to export collections
3. Uploads the dump to S3 (unless `--no-upload`)
4. Records the backup session in the database

**Admin UI Equivalent:** Navigate to *Admin > Backup & Restore*, select your environment, and click "Backup".

### Restore a Backup

Restore a backup to an environment:

```bash
ngx-cli bak restore [environment] [path] [options]
```

**Options:**

| Option | Description | Default |
|--------|-------------|---------|
| `--no-drop` | Don't drop existing collections before restore | Drop enabled |
| `--dry-run` | Preview restore without making changes | Disabled |
| `--collections <collections>` | Comma-separated list of collections | All collections |

**Examples:**

```bash
# Restore from S3
ngx-cli bak restore my-group s3://ngx-ramblers-my-group/backups/2026-01-30-backup

# Restore from local directory
ngx-cli bak restore my-group 2026-01-30-backup

# Restore specific collections
ngx-cli bak restore my-group s3://bucket/backup --collections walks,members

# Dry run (preview only)
ngx-cli bak restore my-group s3://bucket/backup --dry-run

# Interactive - select environment and enter path
ngx-cli bak restore
```

**Warning:** Restore operations will overwrite existing data. Use `--dry-run` first to preview changes.

**Admin UI Equivalent:** Navigate to *Admin > Backup & Restore*, select your environment, choose a backup from the list, and click "Restore".

---

## Validation Commands

### Validate MongoDB Connection

```bash
ngx-cli val mongodb --cluster <cluster> --username <username> --password <password> --database <database>
```

**Example:**

```bash
ngx-cli val mongodb --cluster cluster0.abc123 --username admin --password secret123 --database ngx-ramblers-dev-group
```

**Admin UI Equivalent:** In *Admin > Environment Setup > Services*, click "Test Connection" next to the MongoDB configuration.

### Validate AWS Admin Credentials

Validate AWS credentials from environment variables:

```bash
ngx-cli val aws-admin
```

This checks `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` from your environment.

### Validate Ramblers API Key

```bash
ngx-cli val ramblers-api --api-key <key>
```

**Admin UI Equivalent:** In *Admin > Environment Setup > Group Selection*, enter your API key and click "Validate API Key".

---

## Destroy Command

**Warning:** This command permanently destroys an environment and all its resources.

```bash
ngx-cli des <name> [options]
```

**Options:**

| Option | Description |
|--------|-------------|
| `--skip-fly` | Skip fly.io app deletion |
| `--skip-s3` | Skip S3 bucket and IAM user deletion |
| `--skip-database` | Skip database collection clearing |
| `--skip-configs` | Skip configs.json and secrets file deletion |
| `--yes` | Skip confirmation prompt |

**Examples:**

```bash
# Full destruction with confirmation
ngx-cli des test-env

# Full destruction without confirmation
ngx-cli des test-env --yes

# Keep database, destroy infrastructure
ngx-cli des test-env --skip-database
```

**What gets destroyed:**
1. fly.io app
2. S3 bucket and all objects
3. IAM user and access keys
4. Database collections (data cleared, not dropped)
5. Entry in configs.json
6. Secrets file

**Admin UI Equivalent:** Navigate to *Admin > Environment Setup*, select "Manage Existing Environment", choose your environment, select "Destroy", and confirm.

---

## Configuration Files

### configs.json

Located at `non-vcs/configs.json`, this file contains environment configurations:

```json
{
  "environments": [
    {
      "name": "my-group",
      "appName": "ngx-ramblers-my-group",
      "memory": "1gb",
      "scaleCount": 1,
      "organisation": "personal"
    }
  ]
}
```

### Secrets Files

Located at `non-vcs/secrets/secrets.<appName>.env`:

```
MONGO_URI=mongodb+srv://...
AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=...
BREVO_API_KEY=...
```

---

## CLI vs Admin UI Comparison

| Task | CLI Command | Admin UI Location |
|------|-------------|-------------------|
| List environments | `env list` | Backup & Restore > Settings |
| Create environment | `f deploy` + `db seed` | Environment Setup wizard |
| Resume setup | `env resume` | Environment Setup > Manage > Resume |
| Destroy environment | `des` | Environment Setup > Manage > Destroy |
| Run locally (dev) | `l dev` | N/A (development only) |
| Run locally (prod) | `l prod` | N/A (development only) |
| Validate MongoDB | `val mongodb` | Environment Setup > Test Connection |
| Validate API key | `val ramblers-api` | Environment Setup > Validate API Key |
| Create AWS resources | `a create-resources` | Automatic during Environment Setup |
| Scale fly.io app | `f scale` | N/A (use fly.io dashboard) |
| Create backup | `bak create` | Backup & Restore > Backup |
| Restore backup | `bak restore` | Backup & Restore > Restore |

---

## Quick Reference

### Most Common Commands

```bash
# Start local development
ngx-cli l dev my-group

# List environments
ngx-cli l list

# Deploy to fly.io
ngx-cli f deploy new-group

# Resume with deployment
ngx-cli env resume new-group --fly-deploy

# Seed database
ngx-cli db seed dev-group

# Destroy environment
ngx-cli des test-env --yes

# Backup an environment
ngx-cli bak create my-group

# Restore a backup
ngx-cli bak restore my-group s3://bucket/backup
```

### Help

Get help on any command:

```bash
ngx-cli --help
ngx-cli l --help
ngx-cli l dev --help
ngx-cli l dev -h
ngx-cli l dev --h
```

---

## Tips and Best Practices

1. **Use short aliases**: `l dev my-group` instead of `local dev my-group` for faster typing.

2. **Use interactive mode for safety**: Omit the environment argument to see available options before selecting.

3. **Check secrets before deployment**: Run `l list` to verify secrets files exist.

4. **Use --skip flags with destroy**: When troubleshooting, selectively destroy components.

5. **Environment variables for CI/CD**: Use environment variables instead of interactive prompts:
   ```bash
   export FLY_API_TOKEN=...
   export AWS_ACCESS_KEY_ID=...
   export AWS_SECRET_ACCESS_KEY=...
   ```

---

## Troubleshooting

### "No secrets file found"

Ensure the secrets file exists at `non-vcs/secrets/secrets.<appName>.env`

### "Environment not found in configs.json"

Check that the environment is configured in `non-vcs/configs.json`

### "Port already in use"

The CLI checks ports before starting. Stop the process using the port or specify a different port with `-p`.

### AWS permission errors

Verify your AWS credentials have sufficient permissions for S3 and IAM operations.

### fly.io authentication errors

Ensure `FLY_API_TOKEN` is set or you're logged in via `fly auth login`.