@phila/cli

CLI tool for City of Philadelphia AWS infrastructure management.

Installation

npm install -g @phila/cli
# or
pnpm add -g @phila/cli

Usage

The CLI is available as the city command:

city [command]

Commands

city init [appName]

Create a new Philadelphia infrastructure project from a template. If appName is not provided, you will be prompted for it.

# Interactive mode
city init

# With appName argument
city init my-app

This command will:

• Prompt for package manager (npm, pnpm, or yarn; default: npm)
• Guide you through template selection
• Prompt for project configuration
• Scaffold the project structure
• Set up initial AWS CDK infrastructure

city deploy [environment]

Deploy the project to AWS. Supports dev, test, and prod environments.

city deploy dev
city deploy prod

city validate [environment]

Run install, build, and CDK synth to verify the project is ready for deployment. Optionally specify an environment (dev, test, or prod) to synth against; if omitted, the first configured environment in city.config.json is used.

city validate           # Use first configured environment
city validate dev
city validate test
city validate prod

city ship [environment]

Ship code to AWS without full infrastructure deployment. Useful for quick code updates.

city ship dev --lambda api
city ship dev --web
city ship dev --ecs
city ship dev --all  # Ship all components

Options:

• --lambda [name] - Ship Lambda function (optionally specify name)
• --web - Ship frontend to S3/CloudFront
• --ecs - Ship ECS container
• --all - Ship all components (default when no flags specified)

Package manager: Uses packageManager from city.config.json when set (as chosen during city init); otherwise detects npm, pnpm, or yarn from lock files.

Frontend Configuration:

• Configure custom build command: city config set frontendBuildCommand <script> (default: build)
• Configure custom dist directory: city config set frontendDistDir <path> (default: dist)

Example for Nuxt projects:

city config set frontendBuildCommand generate
city config set frontendDistDir .output/public

city destroy [environment]

Open CloudFormation console to destroy a stack.

city destroy dev

city config

Manage project configuration.

city config show              # Display current configuration
city config get <key>         # Get a specific configuration value
city config set <key> <value> # Set a configuration value

city map

Navigate and query the codebase.

city map show                    # Show codebase map statistics
city map where <query>           # Find files by keyword
city map where --export <name>   # Search by export name
city map where --layer <layer>   # Filter by layer (l1, l2, l3, cli, core, etc.)
city map update                  # Regenerate codebase.json
city map check                   # Validate codebase.json

city templates

List available project templates.

city templates        # List all templates in tree format
city templates simple  # List all templates in simple format

Project Structure

When you run city init, it creates a project with:

• cdk/ - AWS CDK infrastructure code
• apps/ - Application code (Lambda functions, etc.)
• city.config.json - Project configuration
• package.json - Dependencies and scripts

Configuration

Project configuration is stored in city.config.json. Common settings include:

• packageManager - npm, pnpm, or yarn (chosen at init, default npm; used by validate, deploy, ship)
• AWS profile and environment settings
• Application name and resource naming conventions
• Frontend build configuration:
  • frontendBuildCommand - Custom npm script for builds (default: build)
  • frontendDistDir - Custom distribution directory (default: dist)

Use city config set <key> <value> to configure these settings.

Requirements

The CLI checks for required dependencies on startup:

• Node.js (>=18.0.0)
• npm, pnpm, or yarn (automatically detected from lock files)
• AWS CLI
• AWS CDK CLI

Missing dependencies will be detected and installation instructions provided.

Package manager: The CLI uses packageManager from city.config.json when present (set at init). If not set, it detects npm, pnpm, or yarn from lock files and uses the appropriate commands for validate, deploy, and ship.

Development

# Build
pnpm build

# Run tests
pnpm test

# Lint
pnpm lint

License

Part of the City of Philadelphia AWS Infrastructure Library.