Quant Cloud CLI

Command-line interface for Quant Cloud Platform integration and management.

Features

• Multi-Platform Authentication - Support for multiple Quant Cloud environments with platform switching
• Project Configuration - Automatic context detection with .quant.yml files for seamless project workflows
• Organization Management - List and switch between organizations
• Application Management - Create, list, and manage applications with environment auto-selection
• Environment Operations - Create, select, monitor, and manage cloud environments
• Live Metrics Dashboard - Real-time performance monitoring with in-place updates
• Log Streaming - Live log tailing with follow mode
• SSH Access - Direct terminal access to cloud environments via AWS ECS Exec with interactive shells and one-shot commands
• Backup Management - Create, list, download, and delete environment backups
• Visual Regression Testing - Automated visual comparison between Quant projects and remote URLs with Playwright
• Secure OAuth Authentication - Browser-based login flow with PKCE security
• Non-Interactive Mode - All commands support context overrides via CLI flags for automation

Installation

npm install -g @quantcdn/quant-cloud-cli

Or run directly with npx:

npx @quantcdn/quant-cloud-cli

Quick Start

1. Login to Quant Cloud:

   qc login

   Select your platform (QuantGov Cloud or Quant Cloud), authenticate via browser.

2. Check authentication status:

   qc whoami

3. Set up your context:

   qc org select          # Choose organization
   qc app select          # Choose application (auto-prompts for environment)

4. Start monitoring:

   qc env metrics         # Live dashboard
   qc env logs --follow   # Stream logs
   qc ssh                 # Interactive bash shell
   qc backup list         # View backups

Project Configuration

For project-specific workflows, create a .quant.yml file at your project root:

# .quant.yml - Project configuration
platform: quantcdn      # or quantgov
org: my-organization
app: my-application
env: development        # default environment

The CLI automatically detects this file when run from anywhere in your project directory tree, eliminating the need to specify context repeatedly.

Context Priority

The CLI resolves context in this priority order:

1. CLI flags (highest) - --org, --app, --env, --platform
2. Project config (.quant.yml)
3. Stored config (lowest) - from qc org select, qc app select, etc.

Examples

# In a project with .quant.yml
cd /path/to/my-project
qc env logs -f              # Uses project config automatically
qc ssh                      # Connects to project's default environment
qc backup create            # Creates backup for project environment

# Override project config with CLI flags
qc env metrics --env=production  # Override environment
qc ssh --org=other-org          # Override organization

# Works from any subdirectory
cd /path/to/my-project/src/components
qc env list                     # Still finds .quant.yml at project root

Commands

Authentication

• qc login - Authenticate with Quant Cloud Platform (supports multiple platforms)
• qc logout - Sign out and clear stored credentials
• qc whoami - Display current user and authentication status

Platform Management

• qc platform list - List all authenticated platforms
• qc platform switch - Switch between authenticated platforms
• qc platform current - Show currently active platform
• qc platform remove - Remove platform authentication

Organizations

• qc org list - List available organizations
• qc org select [orgId] - Switch to a different organization
• qc org current - Show current organization

Applications

• qc app list - List applications in current organization
• qc app select [appId] - Switch to application (auto-prompts for environment)
• qc app current - Show current application context

Projects

• qc project list - List Quant projects in current organization

Environments

• qc env list - List environments in current application
• qc env select [envId] - Switch to environment with searchable selection
• qc env current - Show current environment
• qc env create [envName] - Create new environment with capacity settings
• qc env state [envId] - Get environment deployment state
• qc env logs [envId] - Stream environment logs (supports --follow)
• qc env metrics [envId] - Live metrics dashboard with real-time updates

SSH Access

• qc ssh [--container=name] - SSH into cloud environment via AWS ECS Exec (defaults to interactive bash)
• qc ssh --command="shell_or_command" - Run specific shell or one-shot command (non-interactive by default)
• qc ssh --command="command" --interactive - Run command in interactive mode

Context Overrides: All SSH commands support --org, --app, --env, --platform flags

Examples:

# Interactive bash shell (default)
qc ssh --container=php

# One-shot commands
qc ssh --container=php --command="php -v"
qc ssh --container=php --command="ls -la /var/www"

# Interactive with specific shell
qc ssh --container=php --command="/bin/sh" --interactive
qc ssh --container=php --command="/bin/zsh" --interactive

# Interactive command (like database console)
qc ssh --container=php --command="mysql -u root -p" --interactive

Backup Management

All backup commands support both database and filesystem backup types via the --type flag (defaults to database).

• qc backup list [--type=database|filesystem] - List available backups with status and details
• qc backup create [--type=database|filesystem] - Create new backup with interactive prompts
• qc backup download [backupId] [--type=database|filesystem] [--output=path] - Download backup files to local directory
  • Interactive mode: Shows list with descriptions, dates, and sizes
  • Direct mode: qc backup download <backupId> to download specific backup
• qc backup delete [--type=database|filesystem] - Delete backups with confirmation prompt

Context Overrides: All backup commands support --org, --app, --env, --platform flags

Examples:

# Database backups (default)
qc backup list
qc backup create --description="Pre-deployment backup"
qc backup download

# Filesystem backups
qc backup list --type=filesystem
qc backup create --type=filesystem --description="Files before migration"
qc backup download --type=filesystem

# Download specific backup by ID
qc backup download backup-2024-01-15-abc123
qc backup download backup-2024-01-15-abc123 --type=filesystem

# Download to specific directory
qc backup download --output=./my-backups
qc backup download backup-2024-01-15-abc123 --output=./my-backups --type=database

# Full automation with context overrides
qc backup create --org=my-org --app=my-app --env=production --type=database --description="Automated backup"
qc backup download backup-123 --org=my-org --app=my-app --env=production --type=filesystem

Visual Regression Testing (VRT)

Run automated visual regression testing to compare Quant projects against remote URLs using Playwright and Chromium.

• qc vrt - Run VRT for all configured projects
• qc vrt --project=project1,project2 - Run VRT for specific projects
• qc vrt --threshold=0.05 - Set pixel difference threshold (0-1, default: 0.01)
• qc vrt --max-pages=20 - Set maximum pages to crawl per project
• qc vrt --max-depth=5 - Set maximum crawl depth
• qc vrt --csv=report.csv - Generate CSV report
• qc vrt --output-dir=./screenshots - Set screenshot output directory
• qc vrt --quant-auth=user:pass - Basic auth for Quant URLs
• qc vrt --remote-auth=user:pass - Basic auth for remote URLs

Configuration: Create ~/.quant/vrt-config.json with project mappings:

{
  "projects": {
    "simple-project": "https://example.com",
    "project-with-auth": {
      "url": "https://example2.com",
      "remoteAuth": "user:pass",
      "quantAuth": "user:pass"
    }
  },
  "threshold": 0.01,
  "maxPages": 10,
  "maxDepth": 3,
  "quantAuth": "default-user:default-pass",
  "remoteAuth": "default-user:default-pass"
}

Note:

• Projects can be defined as simple URLs (strings) or objects with per-project auth
• Global quantAuth/remoteAuth apply to all projects unless overridden at project level
• CLI flags (--quant-auth, --remote-auth) override all config values

Examples:

# Run VRT for all configured projects
qc vrt

# Run for specific projects
qc vrt --project=my-project

# Run with custom threshold and generate CSV
qc vrt --threshold=0.02 --csv=vrt-report.csv

# Run with authentication
qc vrt --quant-auth=user:pass --remote-auth=user:pass

# Run with custom limits
qc vrt --max-pages=50 --max-depth=5 --output-dir=./my-screenshots

Output:

• Console summary with pass/fail status per page
• Screenshot diffs saved to ./vrt-results/{project}/{date}/
• Optional CSV report with detailed results
• Exit code 1 if any tests fail

Non-Interactive Mode

All commands support context override flags for automation and CI/CD:

# Override any context parameter
qc env logs --org=my-org --app=my-app --env=production --follow
qc ssh --org=my-org --app=my-app --env=staging --container=web
qc backup create --org=my-org --app=my-app --env=production --type=database
qc env metrics --platform=quantgov --org=gov-dept --app=portal --env=prod

Configuration

User Configuration

The CLI stores user configuration in ~/.quant/credentials. This includes:

• Multi-platform authentication tokens and refresh tokens
• Active platform, organization, application, and environment context
• Platform-specific settings and preferences

Configuration is automatically migrated from single-platform to multi-platform format when upgrading.

Project Configuration

Create a .quant.yml file at your project root for automatic context detection:

# .quant.yml
platform: quantcdn    # Platform: quantcdn or quantgov
org: my-org           # Organization machine name
app: my-application   # Application machine name  
env: development      # Default environment name

Directory Traversal: The CLI searches for .quant.yml starting from the current directory and walking up to the git repository root.

Context Resolution Priority:

1. CLI flags (--org, --app, --env, --platform)
2. Project config (.quant.yml)
3. Stored user config (~/.quant/credentials)

Development

# Clone the repository
git clone <repo-url>
cd quant-cloud-cli

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

# Link for global usage during development
npm link

Testing

The CLI includes comprehensive unit and integration tests. Integration tests use a mock API backend via Docker.

Running Tests

# Unit tests only (fast, no Docker required)
npm test
# or
make test

# Integration tests (requires Docker)
npm run test:integration
# or  
make test-integration

# All tests
npm run test:all
# or
make test-all

# With coverage
npm run test:coverage

Manual Testing with Mock API

Test CLI commands against the mock API backend:

# Start mock API
make mock-api-start

# Configure CLI to use mock API (in another terminal)
export QUANT_HOST=http://localhost:4010
export QUANT_TOKEN=mock-token-123

# Test commands
qc app list --org=test-org
qc env list --org=test-org --app=test-app

# Stop mock API
make mock-api-stop

Mock API

The mock API is built with Prism and automatically generates valid responses from the OpenAPI specification.

• Container: ghcr.io/quantcdn/quant-mock-api:4.0.0
• Endpoint: http://localhost:4010
• Auto-managed: Integration tests start/stop Docker automatically
• Public: No authentication required to pull the container

See __tests__/README.md for detailed testing documentation.

Environment Variables

• LOG_LEVEL - Set logging level (DEBUG, INFO, WARN, ERROR)
• QUANT_HOST - Override API host (useful for testing with mock API)
• QUANT_TOKEN - Override authentication token (for testing)

License

MIT