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:

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:

npm link

Then you can use:

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

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:

ngx-cli l dev [environment] [options]

Options:

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

Examples:

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

ngx-cli l prod [environment] [options]

Options:

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

Examples:

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

This:

Builds the Angular frontend with production optimisations
Starts the Express server serving the bundled application

Environment Management Commands

List Configured Environments

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

ngx-cli env show <name>

Example:

ngx-cli env show my-group

Resume Environment Setup

Resume a partially completed environment setup:

ngx-cli env resume <name> [options]

Options:

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

Examples:

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

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:

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:

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:

ngx-cli f scale <appName> [options]

Options:

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

Examples:

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:

ngx-cli f token <appName>

Example:

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

AWS Resource Commands

Create AWS Resources

Create S3 bucket and IAM user for a new environment:

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

Options:

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

Examples:

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:

ngx-cli a copy-assets <bucket>

Example:

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

Database Commands

Seed Database

Populate a database with sample data and run migrations:

ngx-cli db seed <name> [options]

Or using connection details directly:

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:

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

Sample page content is created (home, walks, about-us, contact-us, admin)
All pending database migrations run automatically
Admin menu items are populated via migrations
(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:

ngx-cli db migrate <name>

Example:

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:

ngx-cli db validate <name>

Example:

ngx-cli db validate dev-group

Backup and Restore Commands

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

List Backup Environments

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:

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:

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

Connects to the environment's MongoDB database
Runs mongodump to export collections
Uploads the dump to S3 (unless --no-upload)
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:

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:

# 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

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

Example:

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:

ngx-cli val aws-admin

This checks AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY from your environment.

Validate Ramblers API Key

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.

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:

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

fly.io app
S3 bucket and all objects
IAM user and access keys
Database collections (data cleared, not dropped)
Entry in configs.json
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:

{
  "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

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

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

Use short aliases: l dev my-group instead of local dev my-group for faster typing.
Use interactive mode for safety: Omit the environment argument to see available options before selecting.
Check secrets before deployment: Run l list to verify secrets files exist.
Use --skip flags with destroy: When troubleshooting, selectively destroy components.
Environment variables for CI/CD: Use environment variables instead of interactive prompts:
```
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.