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

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

Or run directly with npx:
`bash
npx @quantcdn/quant-cloud-cli
`

Quick Start

1. Login to Quant Cloud:
`bash
qc login
`
Select your platform (QuantGov Cloud or Quant Cloud), authenticate via browser.

2. Check authentication status:
`bash
qc whoami
`

3. Set up your context:
`bash
qc org select # Choose organization
qc app select # Choose application (auto-prompts for environment)
`

4. Start monitoring:
`bash
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:

`yaml


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

$3

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.

$3

`bash


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

$3

- 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

$3

- 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

$3

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

$3

- 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

$3

- qc project list - List Quant projects in current organization

$3

- 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

$3

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


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
`

$3

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


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
`

$3

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:

`json
{
"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:

`bash


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

$3

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

`bash


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

$3

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.

$3

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

`yaml


.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

`bash


Clone the repository

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

$3

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

#### Running Tests

`bash


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:

`bash


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