Pendulum CLI

Command-line interface for managing Pendulum BaaS projects - from local development to AWS production deployment.

The Pendulum CLI automates your entire development workflow, from zero to production. With just a few commands, you can initialize projects, develop locally with hot reload, and deploy complete AWS infrastructure.

Key Benefits:

• One-command setup - Get a full backend running locally in seconds
• Infrastructure automation - Deploy to AWS with zero configuration
• Development optimized - Hot reload and live logs during development
• Production ready - Auto-provisioned ECS, DocumentDB, and load balancers
• Clean teardown - Remove all AWS resources with a single command

Installation

Install globally via npm:

npm install -g @pendulum-baas/cli

Or use directly with npx:

npx @pendulum-baas/cli <command>

Commands

npx pendulum init # Initialize a new Pendulum project in the current directory.

This will:

• Install @pendulum-baas/core and @pendulum-baas/sdk
• Add npm scripts for backend management
• Set up project structure

npx pendulum dev # Start the Pendulum backend for local development.

Starts:

• MongoDB container
• App service (port 3000)
• Events service (port 8080)
• Admin dashboard at http://localhost:3000/admin

npx pendulum deploy # Deploy your application to AWS using CDK.

Interactive prompts for:

• AWS account ID and region
• Project name
• Frontend build path
• Deployment confirmation

Creates:

• ECS Fargate cluster
• DocumentDB database
• Application Load Balancer
• CloudFront distribution
• VPC with security groups

npx pendulum destroy # Remove all AWS infrastructure and resources.

⚠️ Warning: This permanently deletes all data and infrastructure.

Prerequisites

For Local Development

• Node.js 18+
• Docker and Docker Compose
• npm or yarn

For AWS Deployment

• AWS CLI configured (aws configure)
• Docker (for container building)
• Valid AWS credentials with appropriate permissions

AWS Permissions Setup

Important: You must configure AWS permissions before deploying. The CLI cannot automatically grant itself permissions.

Option 1: Administrator Access (Recommended)

aws configure
# Enter your admin credentials

Option 2: Limited IAM User

• AWSCloudFormationFullAccess - Stack management
• AmazonECS_FullAccess - Container orchestration
• AmazonDocDBFullAccess - Database hosting
• AmazonVPCFullAccess - Network infrastructure
• IAMFullAccess - Role creation
• AmazonS3FullAccess - CDK asset storage
• SecretsManagerReadWrite - Credential management

Verify Setup

aws sts get-caller-identity
# Should show your account ID and user/role

Environment Configuration

See the Pendulum Core README for environment variable details. The CLI handles configuration automatically.

Docker Management

The CLI adds these scripts to your package.json:

{
  "scripts": {
    "pendulum-backend:start": "cd node_modules/@pendulum-baas/core && docker compose start",
    "pendulum-backend:stop": "cd node_modules/@pendulum-baas/core && docker compose stop"
  }
}

Deployment Output

After successful AWS deployment, you'll receive:

• Frontend URL - CloudFront distribution
• API Endpoint - Load balancer DNS
• Admin Dashboard - Management interface
• Admin API Key - Dashboard access credentials

Troubleshooting

Docker not running:

# Linux
sudo systemctl start docker

# macOS/Windows  
# Start Docker Desktop application

AWS credentials not configured:

aws configure
# Enter your Access Key ID, Secret, region, and output format

Build directory not found:

• Check the build path when prompted during deployment
• Ensure your frontend is built (npm run build)
• Verify the build path contains index.html

Permission errors:

• Verify your AWS user has the required permissions listed above
• Check AWS CLI access: aws sts get-caller-identity

Dependencies Downloaded with npm install

• AWS CDK - Infrastructure as Code
• AWS CLI - AWS resource management
• Docker - Container orchestration
• Inquirer - Interactive prompts
• Chalk - Terminal colors
• Ora - Loading spinners

Examples

Complete Workflow

# Initialize project
mkdir my-app && cd my-app
npx pendulum init

# Start development
npx pendulum dev

# Deploy to production
npx pendulum deploy

# Clean up resources
npx pendulum destroy