npm package: @pendulum-baas/cli
Description: Command-line interface for managing Pendulum BaaS projects - from local development to AWS production deployment
Author: Pendulum Team
Latest version: 1.0.8

# 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:
```bash
npm install -g @pendulum-baas/cli
```

Or use directly with npx:
```bash
npx @pendulum-baas/cli <command>
```

## Commands
```bash
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

***

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

***

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

***

```bash
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)
```bash
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
```bash
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`:
```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:
```bash
# Linux
sudo systemctl start docker

# macOS/Windows  
# Start Docker Desktop application
```

### AWS credentials not configured:
```bash
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
```bash
# 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
```