{"id":"697c6cc9090375fa10a22bfc","title":"2026 01 30 Ngx Ramblers Cli Reference","path":"how-to/technical-articles/2026-01-30-ngx-ramblers-cli-reference","contentMarkdown":"# 30-Jan-2026 — NGX Ramblers CLI Reference Guide\n\nThe 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.\n\n## Prerequisites\n\nBefore using the CLI, ensure you have:\n\n- Node.js v22.19.0 or later\n- Access to the NGX-Ramblers repository\n- Secrets files in `non-vcs/secrets/` directory (contain AWS credentials, fly.io tokens, MongoDB URIs, etc.)\n- AWS admin credentials in environment variables (only needed for `aws create-resources` command)\n\n## Running the CLI\n\nFrom the project root directory:\n\n```bash\nnpm run cli -- [options]\n```\n\nThe CLI will automatically install dependencies if needed (when `package-lock.json` changes).\n\n### Global Installation (Optional)\n\nTo use `ngx-cli` from any directory, run once in the project root:\n\n```bash\nnpm link\n```\n\nThen you can use:\n\n```bash\nngx-cli [options]\n```\n\n---\n\n## Command Overview\n\n```\nUsage: ngx-cli [options] [command]\n\nNGX-Ramblers environment management CLI\n\nCommands:\n environment|env Environment management commands\n fly|f fly.io deployment commands\n database|db Database management commands\n aws|a AWS resource management commands\n validate|val Validation commands for credentials and connections\n destroy|des Destroy an environment completely\n local|l Run the app locally in dev or production mode\n backup|bak Backup and restore commands\n```\n\n### Command Aliases\n\nAll commands support short aliases for faster typing:\n\n| Full Command | Alias | Example |\n|--------------|-------|---------|\n| `environment` | `env` | `ngx-cli env list` |\n| `database` | `db` | `ngx-cli db seed dev-group` |\n| `validate` | `val` | `ngx-cli val aws-admin` |\n| `destroy` | `des` | `ngx-cli des test-env` |\n| `local` | `l` | `ngx-cli l dev my-group` |\n| `fly` | `f` | `ngx-cli f deploy new-group` |\n| `aws` | `a` | `ngx-cli a create-resources new-group` |\n| `backup` | `bak` | `ngx-cli bak create my-group` |\n\n---\n\n## Interactive Mode\n\nWhen you run commands without specifying required arguments, the CLI enters interactive mode with a clear screen and selection menu.\n\n### Keyboard Navigation\n\n| Key | Action |\n|-----|--------|\n| `Arrow keys` | Navigate options |\n| `Enter` | Select option |\n| `ESC` | Go back to previous step |\n| `q` | Quit immediately |\n| `Ctrl+C` | Quit immediately |\n\nNavigation hints are displayed at the bottom of selection menus:\n\n```\n? Select an environment: (Use arrow keys)\n> my-group (ngx-ramblers-my-group)\n dev-group (ngx-ramblers)\n another-group (ngx-ramblers-another-group)\n ──────────────\n [q/Ctrl+C: quit]\n```\n\n---\n\n## Local Development Commands\n\nThe `local` (or `l`) command replaces shell scripts for running the application locally.\n\n### List Available Environments\n\n```bash\nngx-cli l list\n```\n\n**Output:**\n\n```\nAvailable environments:\n\n my-group - ngx-ramblers-my-group (ready)\n dev-group - ngx-ramblers (ready)\n another-group - ngx-ramblers-another-group (ready)\n third-group - ngx-ramblers-third-group (ready)\n new-group - ngx-ramblers-new-group (ready)\n```\n\nThe status shows:\n- **ready**: Secrets file exists and environment is configured\n- **missing secrets**: No secrets file found for this environment\n\n### Development Mode (Hot Reload)\n\nStart the application with hot module reloading for both frontend and backend:\n\n```bash\nngx-cli l dev [environment] [options]\n```\n\n**Options:**\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `-p, --port ` | Backend port | 5001 |\n\n**Examples:**\n\n```bash\n# Direct - specify environment\nngx-cli l dev my-group\n\n# With custom port\nngx-cli l dev my-group -p 3000\n\n# Interactive - select from menu\nngx-cli l dev\n```\n\n**Output:**\n\n```\n========================================\nStarting in DEVELOPMENT mode\n========================================\nEnvironment: my-group\nApp Name: ngx-ramblers-my-group\nPort: 5001\nFrontend: http://localhost:4200\nBackend: http://localhost:5001\n========================================\n\nStarting Backend (tsx watch)...\nStarting Frontend (ng serve)...\n```\n\nThis runs:\n- **Frontend**: `ng serve` with hot reload on http://localhost:4200\n- **Backend**: `tsx watch` with hot reload on http://localhost:5001\n\n**Port Checking:** The CLI checks if ports are available before starting and will display an error if they're in use.\n\n### Production Mode\n\nBuild and run a production build locally:\n\n```bash\nngx-cli l prod [environment] [options]\n```\n\n**Options:**\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `-p, --port ` | Server port | 5001 |\n\n**Examples:**\n\n```bash\nngx-cli l prod dev-group\nngx-cli l prod dev-group -p 8080\n```\n\nThis:\n1. Builds the Angular frontend with production optimisations\n2. Starts the Express server serving the bundled application\n\n---\n\n## Environment Management Commands\n\n### List Configured Environments\n\n```bash\nngx-cli env list\n```\n\n**Output:**\n\n```\nConfigured environments:\n\n my-group\n App: ngx-ramblers-my-group\n Memory: 1gb\n Scale: 1\n Organisation: personal\n API Key: Yes\n\n new-group\n App: ngx-ramblers-new-group\n Memory: 1024mb\n Scale: 1\n Organisation: personal\n API Key: Yes\n```\n\n**Admin UI Equivalent:** Navigate to *Admin > Backup & Restore > Settings* to view configured environments.\n\n### Show Environment Details\n\n```bash\nngx-cli env show \n```\n\n**Example:**\n\n```bash\nngx-cli env show my-group\n```\n\n### Resume Environment Setup\n\nResume a partially completed environment setup:\n\n```bash\nngx-cli env resume [options]\n```\n\n**Options:**\n\n| Option | Description |\n|--------|-------------|\n| `--db-init` | Run database initialisation |\n| `--fly-deploy` | Run fly.io deployment |\n\n**Examples:**\n\n```bash\n# Resume and deploy to fly.io\nngx-cli env resume new-group --fly-deploy\n\n# Resume and reinitialise database\nngx-cli env resume new-group --db-init\n\n# Both\nngx-cli env resume new-group --db-init --fly-deploy\n```\n\n**Admin UI Equivalent:** Navigate to *Admin > Environment Setup*, select \"Manage Existing Environment\", choose your environment, and click \"Resume Setup\".\n\n### Update Ramblers Info\n\nUpdate the Ramblers API information in an environment's secrets file:\n\n```bash\nngx-cli env update-ramblers --api-key --area-code --area-name --group-code --group-name \n```\n\n---\n\n## fly.io Deployment Commands\n\n### Deploy to fly.io\n\nDeploy an environment to fly.io:\n\n```bash\nngx-cli f deploy [options]\n```\n\n**Options:**\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `--app-name ` | fly.io app name | ngx-ramblers-{name} |\n| `--memory ` | Memory allocation | 512mb |\n| `--scale ` | Number of instances | 1 |\n| `--org ` | fly.io organization | personal |\n\n**Examples:**\n\n```bash\nngx-cli f deploy new-group\nngx-cli f deploy new-group --memory 1024mb --scale 1\n```\n\n**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.\n\n### Scale fly.io App\n\nAdjust resources for a running fly.io app:\n\n```bash\nngx-cli f scale [options]\n```\n\n**Options:**\n\n| Option | Description |\n|--------|-------------|\n| `--count ` | Number of instances |\n| `--memory ` | Memory allocation (e.g., 512mb, 1gb) |\n\n**Examples:**\n\n```bash\nngx-cli f scale ngx-ramblers-example --memory 1gb\nngx-cli f scale ngx-ramblers-example --count 2\n```\n\n### Generate Deploy Token\n\nGenerate a deploy token for an app:\n\n```bash\nngx-cli f token \n```\n\n**Example:**\n\n```bash\nngx-cli f token ngx-ramblers-new-group\n```\n\n---\n\n## AWS Resource Commands\n\n### Create AWS Resources\n\nCreate S3 bucket and IAM user for a new environment:\n\n```bash\nngx-cli a create-resources [options]\n```\n\n**Options:**\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `--region ` | AWS region | eu-west-1 |\n\n**Examples:**\n\n```bash\nngx-cli a create-resources new-group\nngx-cli a create-resources new-group --region eu-west-2\n```\n\nThis creates:\n- S3 bucket: `ngx-ramblers-new-group`\n- IAM user: `ngx-ramblers-new-group-user`\n- IAM policy with S3 permissions\n- Access key credentials (saved to secrets file)\n\n**Admin UI Equivalent:** This is performed automatically during environment creation in *Admin > Environment Setup*.\n\n### Copy Standard Assets\n\nCopy standard assets (logos, images) to an environment's S3 bucket:\n\n```bash\nngx-cli a copy-assets \n```\n\n**Example:**\n\n```bash\nngx-cli a copy-assets ngx-ramblers-new-group\n```\n\n---\n\n## Database Commands\n\n### Seed Database\n\nPopulate a database with sample data and run migrations:\n\n```bash\nngx-cli db seed [options]\n```\n\n**Or using connection details directly:**\n\n```bash\nngx-cli db seed --uri \"mongodb+srv://cluster.mongodb.net\" --database \"ngx-ramblers-new-group\" --group-name \"My Walking Group\"\n```\n\n**Options:**\n\n| Option | Description |\n|--------|-------------|\n| `--uri ` | MongoDB connection URI (alternative to name) |\n| `--database ` | Database name (required with --uri) |\n| `--group-name ` | Group name for sample data (required with --uri) |\n| `--fresh` | Clear changelog and page content before seeding (runs all migrations fresh) |\n| `--sync` | Run full data sync from Ramblers API after seeding |\n\n**Examples:**\n\n```bash\n# Basic seed - creates sample pages and runs pending migrations\nngx-cli db seed dev-group\n\n# Fresh seed - clears existing data and runs all migrations from scratch\nngx-cli db seed new-group --fresh\n\n# Seed with data sync - also pulls walks from Ramblers API\nngx-cli db seed new-group --sync\n\n# Full fresh setup with data sync\nngx-cli db seed new-group --fresh --sync\n```\n\n**What happens during seeding:**\n1. Sample page content is created (home, walks, about-us, contact-us, admin)\n2. All pending database migrations run automatically\n3. Admin menu items are populated via migrations\n4. (With `--sync`) Walks are fetched from the Ramblers API\n\n**Admin UI Equivalent:** Database seeding happens automatically during environment creation. For existing environments, use the backup/restore functionality in *Admin > Backup & Restore*.\n\n### Run Database Migrations\n\nRun pending database migrations without seeding:\n\n```bash\nngx-cli db migrate \n```\n\n**Example:**\n\n```bash\nngx-cli db migrate dev-group\n```\n\n**Output:**\n\n```\nRunning pending migrations...\nStatus: 18 applied, 2 pending, 0 failed\n✓ Applied 2 migration(s)\n - 20260129000000-add-environment-setup-menu-item.js\n - 20260130000000-add-venue-settings-menu-item.js\n```\n\n### Validate Database Connection\n\nTest MongoDB connectivity:\n\n```bash\nngx-cli db validate \n```\n\n**Example:**\n\n```bash\nngx-cli db validate dev-group\n```\n\n---\n\n## Backup and Restore Commands\n\nThe `backup` (or `bak`) command provides database backup and restore functionality.\n\n### List Backup Environments\n\n```bash\nngx-cli bak list\n```\n\n**Output:**\n\n```\nConfigured backup environments:\n\n my-group\n Database: ngx-ramblers-my-group\n S3 Bucket: ngx-ramblers-my-group\n\n dev-group\n Database: ngx-ramblers\n S3 Bucket: ngx-ramblers\n```\n\n### Create a Backup\n\nCreate a backup of an environment's database:\n\n```bash\nngx-cli bak create [environment] [options]\n```\n\n**Options:**\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `--no-upload` | Don't upload to S3 (local only) | Upload enabled |\n| `--collections ` | Comma-separated list of collections | All collections |\n\n**Examples:**\n\n```bash\n# Backup with S3 upload (default)\nngx-cli bak create my-group\n\n# Backup without S3 upload (local only)\nngx-cli bak create my-group --no-upload\n\n# Backup specific collections only\nngx-cli bak create my-group --collections walks,members,pageContent\n\n# Interactive - select from menu\nngx-cli bak create\n```\n\n**What happens during backup:**\n1. Connects to the environment's MongoDB database\n2. Runs `mongodump` to export collections\n3. Uploads the dump to S3 (unless `--no-upload`)\n4. Records the backup session in the database\n\n**Admin UI Equivalent:** Navigate to *Admin > Backup & Restore*, select your environment, and click \"Backup\".\n\n### Restore a Backup\n\nRestore a backup to an environment:\n\n```bash\nngx-cli bak restore [environment] [path] [options]\n```\n\n**Options:**\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `--no-drop` | Don't drop existing collections before restore | Drop enabled |\n| `--dry-run` | Preview restore without making changes | Disabled |\n| `--collections ` | Comma-separated list of collections | All collections |\n\n**Examples:**\n\n```bash\n# Restore from S3\nngx-cli bak restore my-group s3://ngx-ramblers-my-group/backups/2026-01-30-backup\n\n# Restore from local directory\nngx-cli bak restore my-group 2026-01-30-backup\n\n# Restore specific collections\nngx-cli bak restore my-group s3://bucket/backup --collections walks,members\n\n# Dry run (preview only)\nngx-cli bak restore my-group s3://bucket/backup --dry-run\n\n# Interactive - select environment and enter path\nngx-cli bak restore\n```\n\n**Warning:** Restore operations will overwrite existing data. Use `--dry-run` first to preview changes.\n\n**Admin UI Equivalent:** Navigate to *Admin > Backup & Restore*, select your environment, choose a backup from the list, and click \"Restore\".\n\n---\n\n## Validation Commands\n\n### Validate MongoDB Connection\n\n```bash\nngx-cli val mongodb --cluster --username --password --database \n```\n\n**Example:**\n\n```bash\nngx-cli val mongodb --cluster cluster0.abc123 --username admin --password secret123 --database ngx-ramblers-dev-group\n```\n\n**Admin UI Equivalent:** In *Admin > Environment Setup > Services*, click \"Test Connection\" next to the MongoDB configuration.\n\n### Validate AWS Admin Credentials\n\nValidate AWS credentials from environment variables:\n\n```bash\nngx-cli val aws-admin\n```\n\nThis checks `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` from your environment.\n\n### Validate Ramblers API Key\n\n```bash\nngx-cli val ramblers-api --api-key \n```\n\n**Admin UI Equivalent:** In *Admin > Environment Setup > Group Selection*, enter your API key and click \"Validate API Key\".\n\n---\n\n## Destroy Command\n\n**Warning:** This command permanently destroys an environment and all its resources.\n\n```bash\nngx-cli des [options]\n```\n\n**Options:**\n\n| Option | Description |\n|--------|-------------|\n| `--skip-fly` | Skip fly.io app deletion |\n| `--skip-s3` | Skip S3 bucket and IAM user deletion |\n| `--skip-database` | Skip database collection clearing |\n| `--skip-configs` | Skip configs.json and secrets file deletion |\n| `--yes` | Skip confirmation prompt |\n\n**Examples:**\n\n```bash\n# Full destruction with confirmation\nngx-cli des test-env\n\n# Full destruction without confirmation\nngx-cli des test-env --yes\n\n# Keep database, destroy infrastructure\nngx-cli des test-env --skip-database\n```\n\n**What gets destroyed:**\n1. fly.io app\n2. S3 bucket and all objects\n3. IAM user and access keys\n4. Database collections (data cleared, not dropped)\n5. Entry in configs.json\n6. Secrets file\n\n**Admin UI Equivalent:** Navigate to *Admin > Environment Setup*, select \"Manage Existing Environment\", choose your environment, select \"Destroy\", and confirm.\n\n---\n\n## Configuration Files\n\n### configs.json\n\nLocated at `non-vcs/configs.json`, this file contains environment configurations:\n\n```json\n{\n \"environments\": [\n {\n \"name\": \"my-group\",\n \"appName\": \"ngx-ramblers-my-group\",\n \"memory\": \"1gb\",\n \"scaleCount\": 1,\n \"organisation\": \"personal\"\n }\n ]\n}\n```\n\n### Secrets Files\n\nLocated at `non-vcs/secrets/secrets..env`:\n\n```\nMONGO_URI=mongodb+srv://...\nAWS_ACCESS_KEY_ID=AKIA...\nAWS_SECRET_ACCESS_KEY=...\nBREVO_API_KEY=...\n```\n\n---\n\n## CLI vs Admin UI Comparison\n\n| Task | CLI Command | Admin UI Location |\n|------|-------------|-------------------|\n| List environments | `env list` | Backup & Restore > Settings |\n| Create environment | `f deploy` + `db seed` | Environment Setup wizard |\n| Resume setup | `env resume` | Environment Setup > Manage > Resume |\n| Destroy environment | `des` | Environment Setup > Manage > Destroy |\n| Run locally (dev) | `l dev` | N/A (development only) |\n| Run locally (prod) | `l prod` | N/A (development only) |\n| Validate MongoDB | `val mongodb` | Environment Setup > Test Connection |\n| Validate API key | `val ramblers-api` | Environment Setup > Validate API Key |\n| Create AWS resources | `a create-resources` | Automatic during Environment Setup |\n| Scale fly.io app | `f scale` | N/A (use fly.io dashboard) |\n| Create backup | `bak create` | Backup & Restore > Backup |\n| Restore backup | `bak restore` | Backup & Restore > Restore |\n\n---\n\n## Quick Reference\n\n### Most Common Commands\n\n```bash\n# Start local development\nngx-cli l dev my-group\n\n# List environments\nngx-cli l list\n\n# Deploy to fly.io\nngx-cli f deploy new-group\n\n# Resume with deployment\nngx-cli env resume new-group --fly-deploy\n\n# Seed database\nngx-cli db seed dev-group\n\n# Destroy environment\nngx-cli des test-env --yes\n\n# Backup an environment\nngx-cli bak create my-group\n\n# Restore a backup\nngx-cli bak restore my-group s3://bucket/backup\n```\n\n### Help\n\nGet help on any command:\n\n```bash\nngx-cli --help\nngx-cli l --help\nngx-cli l dev --help\nngx-cli l dev -h\nngx-cli l dev --h\n```\n\n---\n\n## Tips and Best Practices\n\n1. **Use short aliases**: `l dev my-group` instead of `local dev my-group` for faster typing.\n\n2. **Use interactive mode for safety**: Omit the environment argument to see available options before selecting.\n\n3. **Check secrets before deployment**: Run `l list` to verify secrets files exist.\n\n4. **Use --skip flags with destroy**: When troubleshooting, selectively destroy components.\n\n5. **Environment variables for CI/CD**: Use environment variables instead of interactive prompts:\n ```bash\n export FLY_API_TOKEN=...\n export AWS_ACCESS_KEY_ID=...\n export AWS_SECRET_ACCESS_KEY=...\n ```\n\n---\n\n## Troubleshooting\n\n### \"No secrets file found\"\n\nEnsure the secrets file exists at `non-vcs/secrets/secrets..env`\n\n### \"Environment not found in configs.json\"\n\nCheck that the environment is configured in `non-vcs/configs.json`\n\n### \"Port already in use\"\n\nThe CLI checks ports before starting. Stop the process using the port or specify a different port with `-p`.\n\n### AWS permission errors\n\nVerify your AWS credentials have sufficient permissions for S3 and IAM operations.\n\n### fly.io authentication errors\n\nEnsure `FLY_API_TOKEN` is set or you're logged in via `fly auth login`.\n","contentHtml":"

30-Jan-2026 — NGX Ramblers CLI Reference Guide

\n

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.

\n

Prerequisites

\n

Before using the CLI, ensure you have:

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

Running the CLI

\n

From the project root directory:

\n
npm run cli -- <command> [options]\n
\n

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

\n

Global Installation (Optional)

\n

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

\n
npm link\n
\n

Then you can use:

\n
ngx-cli <command> [options]\n
\n
\n

Command Overview

\n
Usage: ngx-cli [options] [command]\n\nNGX-Ramblers environment management CLI\n\nCommands:\n  environment|env               Environment management commands\n  fly|f                         fly.io deployment commands\n  database|db                   Database management commands\n  aws|a                         AWS resource management commands\n  validate|val                  Validation commands for credentials and connections\n  destroy|des <name>            Destroy an environment completely\n  local|l                       Run the app locally in dev or production mode\n  backup|bak                    Backup and restore commands\n
\n

Command Aliases

\n

All commands support short aliases for faster typing:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Full CommandAliasExample
environmentenvngx-cli env list
databasedbngx-cli db seed dev-group
validatevalngx-cli val aws-admin
destroydesngx-cli des test-env
locallngx-cli l dev my-group
flyfngx-cli f deploy new-group
awsangx-cli a create-resources new-group
backupbakngx-cli bak create my-group
\n
\n

Interactive Mode

\n

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

\n

Keyboard Navigation

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
KeyAction
Arrow keysNavigate options
EnterSelect option
ESCGo back to previous step
qQuit immediately
Ctrl+CQuit immediately
\n

Navigation hints are displayed at the bottom of selection menus:

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

Local Development Commands

\n

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

\n

List Available Environments

\n
ngx-cli l list\n
\n

Output:

\n
Available environments:\n\n  my-group - ngx-ramblers-my-group (ready)\n  dev-group - ngx-ramblers (ready)\n  another-group - ngx-ramblers-another-group (ready)\n  third-group - ngx-ramblers-third-group (ready)\n  new-group - ngx-ramblers-new-group (ready)\n
\n

The status shows:

\n
    \n
  • ready: Secrets file exists and environment is configured
    • \n
  • missing secrets: No secrets file found for this environment
    • \n
\n

Development Mode (Hot Reload)

\n

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

\n
ngx-cli l dev [environment] [options]\n
\n

Options:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n
OptionDescriptionDefault
-p, --port <port>Backend port5001
\n

Examples:

\n
# Direct - specify environment\nngx-cli l dev my-group\n\n# With custom port\nngx-cli l dev my-group -p 3000\n\n# Interactive - select from menu\nngx-cli l dev\n
\n

Output:

\n
========================================\nStarting in DEVELOPMENT mode\n========================================\nEnvironment: my-group\nApp Name: ngx-ramblers-my-group\nPort: 5001\nFrontend: http://localhost:4200\nBackend: http://localhost:5001\n========================================\n\nStarting Backend (tsx watch)...\nStarting Frontend (ng serve)...\n
\n

This runs:

\n\n

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

\n

Production Mode

\n

Build and run a production build locally:

\n
ngx-cli l prod [environment] [options]\n
\n

Options:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n
OptionDescriptionDefault
-p, --port <port>Server port5001
\n

Examples:

\n
ngx-cli l prod dev-group\nngx-cli l prod dev-group -p 8080\n
\n

This:

\n
    \n
  1. Builds the Angular frontend with production optimisations
    2. \n
  2. Starts the Express server serving the bundled application
    3. \n
\n
\n

Environment Management Commands

\n

List Configured Environments

\n
ngx-cli env list\n
\n

Output:

\n
Configured environments:\n\n  my-group\n    App: ngx-ramblers-my-group\n    Memory: 1gb\n    Scale: 1\n    Organisation: personal\n    API Key: Yes\n\n  new-group\n    App: ngx-ramblers-new-group\n    Memory: 1024mb\n    Scale: 1\n    Organisation: personal\n    API Key: Yes\n
\n

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

\n

Show Environment Details

\n
ngx-cli env show <name>\n
\n

Example:

\n
ngx-cli env show my-group\n
\n

Resume Environment Setup

\n

Resume a partially completed environment setup:

\n
ngx-cli env resume <name> [options]\n
\n

Options:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
OptionDescription
--db-initRun database initialisation
--fly-deployRun fly.io deployment
\n

Examples:

\n
# Resume and deploy to fly.io\nngx-cli env resume new-group --fly-deploy\n\n# Resume and reinitialise database\nngx-cli env resume new-group --db-init\n\n# Both\nngx-cli env resume new-group --db-init --fly-deploy\n
\n

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

\n

Update Ramblers Info

\n

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

\n
ngx-cli env update-ramblers <name> --api-key <key> --area-code <code> --area-name <name> --group-code <code> --group-name <name>\n
\n
\n

fly.io Deployment Commands

\n

Deploy to fly.io

\n

Deploy an environment to fly.io:

\n
ngx-cli f deploy <name> [options]\n
\n

Options:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
OptionDescriptionDefault
--app-name <appName>fly.io app namengx-ramblers-{name}
--memory <memory>Memory allocation512mb
--scale <count>Number of instances1
--org <organization>fly.io organizationpersonal
\n

Examples:

\n
ngx-cli f deploy new-group\nngx-cli f deploy new-group --memory 1024mb --scale 1\n
\n

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.

\n

Scale fly.io App

\n

Adjust resources for a running fly.io app:

\n
ngx-cli f scale <appName> [options]\n
\n

Options:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
OptionDescription
--count <count>Number of instances
--memory <memory>Memory allocation (e.g., 512mb, 1gb)
\n

Examples:

\n
ngx-cli f scale ngx-ramblers-example --memory 1gb\nngx-cli f scale ngx-ramblers-example --count 2\n
\n

Generate Deploy Token

\n

Generate a deploy token for an app:

\n
ngx-cli f token <appName>\n
\n

Example:

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

AWS Resource Commands

\n

Create AWS Resources

\n

Create S3 bucket and IAM user for a new environment:

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

Options:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n
OptionDescriptionDefault
--region <region>AWS regioneu-west-1
\n

Examples:

\n
ngx-cli a create-resources new-group\nngx-cli a create-resources new-group --region eu-west-2\n
\n

This creates:

\n
    \n
  • S3 bucket: ngx-ramblers-new-group
    • \n
  • IAM user: ngx-ramblers-new-group-user
    • \n
  • IAM policy with S3 permissions
    • \n
  • Access key credentials (saved to secrets file)
    • \n
\n

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

\n

Copy Standard Assets

\n

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

\n
ngx-cli a copy-assets <bucket>\n
\n

Example:

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

Database Commands

\n

Seed Database

\n

Populate a database with sample data and run migrations:

\n
ngx-cli db seed <name> [options]\n
\n

Or using connection details directly:

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

Options:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
OptionDescription
--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)
--freshClear changelog and page content before seeding (runs all migrations fresh)
--syncRun full data sync from Ramblers API after seeding
\n

Examples:

\n
# Basic seed - creates sample pages and runs pending migrations\nngx-cli db seed dev-group\n\n# Fresh seed - clears existing data and runs all migrations from scratch\nngx-cli db seed new-group --fresh\n\n# Seed with data sync - also pulls walks from Ramblers API\nngx-cli db seed new-group --sync\n\n# Full fresh setup with data sync\nngx-cli db seed new-group --fresh --sync\n
\n

What happens during seeding:

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

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

\n

Run Database Migrations

\n

Run pending database migrations without seeding:

\n
ngx-cli db migrate <name>\n
\n

Example:

\n
ngx-cli db migrate dev-group\n
\n

Output:

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

Validate Database Connection

\n

Test MongoDB connectivity:

\n
ngx-cli db validate <name>\n
\n

Example:

\n
ngx-cli db validate dev-group\n
\n
\n

Backup and Restore Commands

\n

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

\n

List Backup Environments

\n
ngx-cli bak list\n
\n

Output:

\n
Configured backup environments:\n\n  my-group\n    Database: ngx-ramblers-my-group\n    S3 Bucket: ngx-ramblers-my-group\n\n  dev-group\n    Database: ngx-ramblers\n    S3 Bucket: ngx-ramblers\n
\n

Create a Backup

\n

Create a backup of an environment's database:

\n
ngx-cli bak create [environment] [options]\n
\n

Options:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
OptionDescriptionDefault
--no-uploadDon't upload to S3 (local only)Upload enabled
--collections <collections>Comma-separated list of collectionsAll collections
\n

Examples:

\n
# Backup with S3 upload (default)\nngx-cli bak create my-group\n\n# Backup without S3 upload (local only)\nngx-cli bak create my-group --no-upload\n\n# Backup specific collections only\nngx-cli bak create my-group --collections walks,members,pageContent\n\n# Interactive - select from menu\nngx-cli bak create\n
\n

What happens during backup:

\n
    \n
  1. Connects to the environment's MongoDB database
    2. \n
  2. Runs mongodump to export collections
    3. \n
  3. Uploads the dump to S3 (unless --no-upload)
    4. \n
  4. Records the backup session in the database
    5. \n
\n

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

\n

Restore a Backup

\n

Restore a backup to an environment:

\n
ngx-cli bak restore [environment] [path] [options]\n
\n

Options:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
OptionDescriptionDefault
--no-dropDon't drop existing collections before restoreDrop enabled
--dry-runPreview restore without making changesDisabled
--collections <collections>Comma-separated list of collectionsAll collections
\n

Examples:

\n
# Restore from S3\nngx-cli bak restore my-group s3://ngx-ramblers-my-group/backups/2026-01-30-backup\n\n# Restore from local directory\nngx-cli bak restore my-group 2026-01-30-backup\n\n# Restore specific collections\nngx-cli bak restore my-group s3://bucket/backup --collections walks,members\n\n# Dry run (preview only)\nngx-cli bak restore my-group s3://bucket/backup --dry-run\n\n# Interactive - select environment and enter path\nngx-cli bak restore\n
\n

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

\n

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

\n
\n

Validation Commands

\n

Validate MongoDB Connection

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

Example:

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

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

\n

Validate AWS Admin Credentials

\n

Validate AWS credentials from environment variables:

\n
ngx-cli val aws-admin\n
\n

This checks AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY from your environment.

\n

Validate Ramblers API Key

\n
ngx-cli val ramblers-api --api-key <key>\n
\n

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

\n
\n

Destroy Command

\n

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

\n
ngx-cli des <name> [options]\n
\n

Options:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
OptionDescription
--skip-flySkip fly.io app deletion
--skip-s3Skip S3 bucket and IAM user deletion
--skip-databaseSkip database collection clearing
--skip-configsSkip configs.json and secrets file deletion
--yesSkip confirmation prompt
\n

Examples:

\n
# Full destruction with confirmation\nngx-cli des test-env\n\n# Full destruction without confirmation\nngx-cli des test-env --yes\n\n# Keep database, destroy infrastructure\nngx-cli des test-env --skip-database\n
\n

What gets destroyed:

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

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

\n
\n

Configuration Files

\n

configs.json

\n

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

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

Secrets Files

\n

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

\n
MONGO_URI=mongodb+srv://...\nAWS_ACCESS_KEY_ID=AKIA...\nAWS_SECRET_ACCESS_KEY=...\nBREVO_API_KEY=...\n
\n
\n

CLI vs Admin UI Comparison

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
TaskCLI CommandAdmin UI Location
List environmentsenv listBackup & Restore > Settings
Create environmentf deploy + db seedEnvironment Setup wizard
Resume setupenv resumeEnvironment Setup > Manage > Resume
Destroy environmentdesEnvironment Setup > Manage > Destroy
Run locally (dev)l devN/A (development only)
Run locally (prod)l prodN/A (development only)
Validate MongoDBval mongodbEnvironment Setup > Test Connection
Validate API keyval ramblers-apiEnvironment Setup > Validate API Key
Create AWS resourcesa create-resourcesAutomatic during Environment Setup
Scale fly.io appf scaleN/A (use fly.io dashboard)
Create backupbak createBackup & Restore > Backup
Restore backupbak restoreBackup & Restore > Restore
\n
\n

Quick Reference

\n

Most Common Commands

\n
# Start local development\nngx-cli l dev my-group\n\n# List environments\nngx-cli l list\n\n# Deploy to fly.io\nngx-cli f deploy new-group\n\n# Resume with deployment\nngx-cli env resume new-group --fly-deploy\n\n# Seed database\nngx-cli db seed dev-group\n\n# Destroy environment\nngx-cli des test-env --yes\n\n# Backup an environment\nngx-cli bak create my-group\n\n# Restore a backup\nngx-cli bak restore my-group s3://bucket/backup\n
\n

Help

\n

Get help on any command:

\n
ngx-cli --help\nngx-cli l --help\nngx-cli l dev --help\nngx-cli l dev -h\nngx-cli l dev --h\n
\n
\n

Tips and Best Practices

\n
    \n

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

    \n
    2. \n

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

    \n
    3. \n

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

    \n
    4. \n

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

    \n
    5. \n

  5. Environment variables for CI/CD: Use environment variables instead of interactive prompts:

    \n
    export FLY_API_TOKEN=...\nexport AWS_ACCESS_KEY_ID=...\nexport AWS_SECRET_ACCESS_KEY=...\n
    \n
    6. \n
\n
\n

Troubleshooting

\n

"No secrets file found"

\n

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

\n

"Environment not found in configs.json"

\n

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

\n

"Port already in use"

\n

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

\n

AWS permission errors

\n

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

\n

fly.io authentication errors

\n

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

\n"}