npm package: @ketrics/ketrics-cli
Description: CLI tool for deploying applications to Ketrics platform
Author: Ketrics
Latest version: 0.8.0

# Ketrics CLI

A command-line tool for creating, building, validating, and deploying applications to the Ketrics serverless platform.

## Overview

The Ketrics CLI (`@ketrics/ketrics-cli`) is a TypeScript-based command-line interface that enables developers to manage their Ketrics applications across the complete application lifecycle. It fits into the Ketrics platform ecosystem as the primary interface for local development and deployment workflows.

### Key Responsibilities

- **Application Creation**: Bootstrap new projects from predefined templates
- **Build Orchestration**: Compile frontend and backend applications before deployment
- **Configuration Management**: Load and validate project configuration and environment variables
- **Package Bundling**: Create optimized ZIP archives with proper file structure and compression
- **Deployment Automation**: Coordinate the deploy process including API communication and S3 uploads
- **Configuration Validation**: Verify configuration files and environment setup before operations
- **Request Execution**: Execute HTTP API requests with variable interpolation and templating

### Architecture Boundaries

This component operates as a standalone CLI tool that:
- Does NOT handle cloud infrastructure provisioning (delegated to Ketrics backend)
- Does NOT manage authentication beyond token validation (relies on KETRICS_TOKEN format)
- Does NOT execute or monitor running applications (delegated to Ketrics platform)
- Focuses exclusively on local operations and integration with Ketrics deployment APIs

### Project Structure

```
ketrics-cli/
├── bin/
│   └── ketrics.ts              # CLI entry point
├── src/
│   ├── cli.ts                  # Commander.js setup and command definitions
│   ├── index.ts                # Public API exports
│   ├── version.ts              # Auto-generated version
│   ├── types/
│   │   └── index.ts            # Zod schemas and TypeScript interfaces
│   ├── commands/
│   │   ├── create.ts           # Bootstrap new project from template
│   │   ├── build.ts            # Build frontend/backend
│   │   ├── deploy.ts           # Deploy application
│   │   ├── validate.ts         # Validate configuration
│   │   └── run.ts              # Execute API requests
│   ├── services/
│   │   ├── config-service.ts   # Load/validate ketrics.config.json and .env
│   │   ├── build-service.ts    # Orchestrate npm build for frontend/backend
│   │   ├── api-client.ts       # HTTP communication with Ketrics API
│   │   ├── zip-service.ts      # ZIP archive creation and compression
│   │   ├── upload-service.ts   # S3 upload via presigned URLs
│   │   └── template-service.ts # Template discovery and copying
│   └── utils/
│       ├── logger.ts           # Colored console output
│       └── spinner.ts          # Loading indicators
├── templates/
│   └── HelloWorld/             # Example template for project scaffolding
├── package.json                # NPM package configuration
├── tsconfig.json               # TypeScript configuration
└── dist/                       # Compiled JavaScript (generated)
```

## Business Logic

### Problem Statement

Developers need a consistent way to:
1. Create new Ketrics applications with proper structure
2. Build applications locally before deployment
3. Package and upload applications to Ketrics infrastructure
4. Test API integrations without manual HTTP requests
5. Validate configuration before attempting deployments

### Core Workflows

#### 1. Application Creation (`ketrics create`)

**Inputs**: Application name, optional template name
**Process**:
1. Validate app name (alphanumeric, hyphens, underscores; must start with letter)
2. Discover available templates from the `templates/` directory
3. Prompt for template selection (interactive or via `--template` flag)
4. Create application directory
5. Copy template files recursively
6. Update app name in `ketrics.config.json`, `frontend/package.json`, and `backend/package.json`

**Outputs**: New project directory with template structure
**Exit on Error**: Name validation failure, template not found, directory exists

#### 2. Build Process (`ketrics build`)

**Inputs**: Current working directory must contain `frontend/` and `backend/` subdirectories
**Process**:
1. Validate both directories exist with `node_modules` installed
2. Execute `npm run build` in `frontend/` directory
3. Validate `frontend/dist/` was created
4. Execute `npm run build` in `backend/` directory
5. Validate `backend/dist/` was created
6. Report dist paths to user

**Outputs**: Built artifacts in `frontend/dist/` and `backend/dist/`
**Exit on Error**: Missing directories, missing node_modules, build failure, missing dist output

#### 3. Deployment Process (`ketrics deploy`)

**Inputs**: Working directory with built `frontend/dist/` and `backend/dist/`, `.env` with credentials
**Process**:
1. Load and validate environment configuration
2. Validate token format (must start with `ktd_`)
3. Build frontend and backend (calls buildAll)
4. Collect files from both dist directories into a structured ZIP
5. Create presigned S3 URL via Ketrics API (`POST /tenants/{id}/applications/{id}/deploy`)
6. Upload ZIP buffer to S3 via presigned URL
7. Return deployment ID and summary

**Outputs**: Deployment confirmation with ID, file count, and timing
**Special Mode - Dry Run** (`--dry-run`): Shows files to be deployed without uploading
**Exit on Error**: Config loading failure, token validation, build failure, API error, upload failure

#### 4. Configuration Validation (`ketrics validate`)

**Inputs**: Optional paths to `ketrics.config.json` and `.env`
**Process**:
1. Check file existence
2. Parse JSON and validate against schemas
3. Check token format (warning only)
4. Collect all errors and warnings
5. Report validation results

**Outputs**: List of errors (blocking) and warnings (informational)
**Exit on Error**: Any validation errors present

#### 5. API Request Execution (`ketrics run`)

**Inputs**: JSON configuration file with endpoint, method, headers, body
**Process**:
1. Load environment configuration (requires `KETRICS_AUTH_TOKEN` and `KETRICS_RUNTIME_URL`)
2. Parse JSON run file (validates schema)
3. Create variable map from environment (tenantId, applicationId, token)
4. Interpolate all template variables: `{{tenantId}}`, `{{applicationId}}`, `{{token}}`
5. Construct full URL from runtime URL + interpolated endpoint
6. Execute HTTP request with interpolated headers/body
7. Display request and response details

**Outputs**: HTTP response status and body
**Exit on Error**: Missing env vars, invalid JSON, connection refused, timeout

### Business Rules

- **Token Format**: Deployment tokens must start with `ktd_` (validated before API calls)
- **App Name Format**: Must start with letter, contain only alphanumeric/hyphens/underscores
- **Build Prerequisites**: Both frontend and backend must have `node_modules` before building
- **Dist Structure**: Frontend builds to `frontend/dist/`, backend builds to `backend/dist/`
- **File Patterns**: Include/exclude patterns use glob syntax for flexible file selection
- **ZIP Compression**: Level 9 compression (maximum) used for all deployments
- **Request Timeout**: API calls timeout at 30 seconds, S3 uploads at 5 minutes
- **Variable Interpolation**: All string values in run JSON are scanned for `{{varName}}` patterns

### Input/Output Expectations

**Configuration Files**:
- `ketrics.config.json`: JSON with name, version, actions, entry, include/exclude patterns
- `.env`: Key=value format with KETRICS_* variables
- Run JSON: POST/PUT/DELETE/PATCH/GET requests with endpoint, headers, body

**Exit Codes**:
- `0`: Successful execution
- `1`: Any error condition (validation failure, build failure, API error, etc.)

## Technical Details

### Technology Stack

- **Runtime**: Node.js 24.0.0+ (specified in package.json engines)
- **Language**: TypeScript 5.3.3 with strict type checking
- **CLI Framework**: Commander.js 12.0.0 (argument parsing and command structure)
- **HTTP Client**: Axios 1.6.0 (with timeout and error handling)
- **Validation**: Zod 3.22.4 (schema validation for configs and responses)
- **UI/UX**:
  - Chalk 4.1.2 (colored terminal output)
  - Ora 5.4.1 (loading spinners)
  - @inquirer/prompts 7.10.1 (interactive prompts)
- **File Operations**: Native Node.js fs and path modules
- **Compression**: Archiver 6.0.1 (ZIP creation with streaming)
- **Pattern Matching**: Glob 10.3.0 (file selection with include/exclude)
- **Environment Loading**: dotenv 16.3.1 (.env file parsing)
- **Process Execution**: Native Node.js child_process (execSync for npm commands)

### Dependencies Analysis

```json
{
  "core-cli": ["commander@12.0.0"],
  "validation": ["zod@3.22.4"],
  "http": ["axios@1.6.0"],
  "compression": ["archiver@6.0.1"],
  "file-patterns": ["glob@10.3.0"],
  "environment": ["dotenv@16.3.1"],
  "ui": ["chalk@4.1.2", "ora@5.4.1", "@inquirer/prompts@7.10.1"],
  "dev-dependencies": ["typescript@5.3.3", "ts-node@1.7.1", "@types/*"]
}
```

### File Descriptions

**bin/ketrics.ts**
- Entry point executable (shebang for direct CLI usage)
- Instantiates CLI via `createCLI()` and parses process.argv
- Results in `dist/bin/ketrics.js` which is referenced in package.json bin field

**src/cli.ts**
- Configures Commander.js program with CLI name, version, and help text
- Defines 5 commands: create, build, deploy, validate, run
- Maps command arguments/options to handler functions
- Exported as `createCLI()` function

**src/commands/*.ts**
- Each file exports single command handler function
- Validates inputs, orchestrates service layer calls
- Handles errors and formats output via logger
- No business logic—purely orchestration and user interaction

**src/services/*.ts**

- **config-service.ts**: Zod validation, dotenv parsing, schema enforcement. Functions: `loadEnvConfig()`, `loadKetricsConfig()`, `validateConfig()`
- **build-service.ts**: npm script execution via child_process. Functions: `buildAll()`, `runBuild()`, `validateBuildDirectory()`, `validateDistDirectory()`
- **api-client.ts**: Axios POST to `/tenants/{id}/applications/{id}/deploy`. Returns presigned URL and deployment ID. Error handling for 401/403/404 status codes.
- **zip-service.ts**: Archiver for ZIP creation, glob for file collection, streaming compression. Dual functions for config-based and directory-based bundling.
- **upload-service.ts**: Axios PUT to S3 presigned URL with binary data. 5-minute timeout for large uploads. Error handling for 400/403/413 status codes.
- **template-service.ts**: Directory traversal to discover templates, recursive copying, JSON field updates. Functions: `getAvailableTemplates()`, `copyTemplate()`, `updateAppName()`

**src/types/index.ts**
- Zod schemas for runtime validation: `ketricsConfigSchema`, `envConfigSchema`, `runFileSchema`, `runEnvConfigSchema`
- TypeScript interfaces derived from schemas via `z.infer<T>`
- API response types: `DeployResponse` (presigned URL data)
- Supporting types: `FileInfo`, `ValidationResult`, `TemplateInfo`

**src/utils/logger.ts**
- Singleton object with named methods: `info()`, `success()`, `warn()`, `error()`, `log()`, `newline()`, `header()`, `keyValue()`, `indent()`, `file()`, `box()`
- Uses chalk for ANSI color codes
- Replaces raw `console.log()` throughout codebase

**src/utils/spinner.ts**
- `createSpinner(text)`: Ora spinner instance
- `withSpinner<T>(text, operation, successText)`: Wraps async operation with spinner, handles errors, returns result
- Provides visual feedback for long-running operations

**src/version.ts**
- Single auto-generated export: `VERSION = "0.2.3"`
- Generated by `scripts/generate-version.js` during build
- Referenced in cli.ts for `--version` flag

### Configuration Options and Environment Variables

**ketrics.config.json Schema** (Zod validation):
```typescript
{
  name: string,              // Project name (required, min 1 char)
  version: string,           // Semver format e.g. "1.0.0" (required)
  description?: string,      // Optional project description
  runtime: "nodejs18" | "nodejs20" | "static", // Default: "nodejs18"
  actions: string[],         // At least 1 action name (required)
  entry: string,             // Entry point file (required)
  include: string[],         // Glob patterns to include (required, min 1)
  exclude: string[]          // Glob patterns to exclude (default: [])
}
```

**Environment Variables** (loaded from .env):
```
KETRICS_TOKEN              # Deploy token starting with "ktd_" (required)
KETRICS_API_URL            # Ketrics API base URL (required, must be valid URL)
KETRICS_TENANT_ID          # Tenant UUID (required, UUID format)
KETRICS_APPLICATION_ID     # Application UUID (required, UUID format)
KETRICS_AUTH_TOKEN         # Runtime auth token (optional, required for run command)
KETRICS_RUNTIME_URL        # Runtime API URL (optional, required for run command, must be URL)
```

### External Integrations

**Ketrics Tenant API**
- Endpoint: `POST /tenants/{KETRICS_TENANT_ID}/applications/{KETRICS_APPLICATION_ID}/deploy`
- Authentication: Bearer token (KETRICS_TOKEN)
- Request: Empty POST body
- Response: `{ success: boolean, data: { uploadUrl, deploymentId, s3Key, expiresAt, expiresInSeconds } }`
- Errors: 401 (bad token), 403 (no access), 404 (app not found)

**AWS S3** (via presigned URL)
- Method: PUT request to presigned URL from deploy response
- Headers: `Content-Type: application/zip`, `Content-Length: <bytes>`
- Body: Raw ZIP buffer (binary)
- Timeout: 300 seconds (5 minutes)
- Errors: 400 (expired URL), 403 (URL reused), 413 (file too large)

**Ketrics Runtime API** (for run command)
- Base URL: KETRICS_RUNTIME_URL from .env
- Endpoint: User-specified path in run JSON
- Authentication: Bearer token (KETRICS_AUTH_TOKEN in Authorization header)
- Methods: GET, POST, PUT, DELETE, PATCH
- Timeout: 30 seconds
- Response: Any JSON/text (no validation)

## Data Flow

### Deploy Command Data Flow

```
User Input (--env flag, working directory)
    ↓
Load .env → dotenv.parse() → Zod validation → EnvConfig object
    ↓
Build frontend → execSync('npm run build') → frontend/dist/
    ↓
Build backend → execSync('npm run build') → backend/dist/
    ↓
Collect files → fs.readdirSync() recursive → FileInfo[] array
    ↓
Create ZIP → Archiver stream + glob + compression → Buffer
    ↓
API Call → axios.post() → Ketrics /deploy endpoint → DeployResponse
    ↓
S3 Upload → axios.put() → presigned URL + ZIP buffer → AWS S3
    ↓
Result → logger.box() → Deployment ID displayed to user
```

### Create Command Data Flow

```
User Input (app name, optional --template)
    ↓
Validate name → Regex check → boolean result
    ↓
Discover templates → fs.readdirSync(templates/) → TemplateInfo[]
    ↓
Prompt selection → inquirer.select() → User choice or --template flag
    ↓
Copy template → Recursive fs.copyFileSync() → New directory tree
    ↓
Update names → JSON.parse/stringify → Update name field in 3 files
    ↓
Result → logger.success() → Next steps printed to user
```

### Run Command Data Flow

```
User Input (JSON file path, optional --env flag)
    ↓
Load .env → dotenv.parse() → EnvConfig validation
    ↓
Load JSON file → fs.readFileSync() → JSON.parse() → Zod validation → RunFileConfig
    ↓
Create variables → Map EnvConfig to VariableMap { tenantId, applicationId, token }
    ↓
Interpolate strings → Regex replace {{varName}} → Fully resolved endpoint/headers/body
    ↓
Build full URL → KETRICS_RUNTIME_URL + endpoint → Full HTTP URL
    ↓
HTTP Request → axios() → Method/headers/body from interpolated config → AxiosResponse
    ↓
Display response → JSON.stringify(response.data) → Pretty-printed to console
```

### Configuration Validation Data Flow

```
User Input (optional --config and --env paths)
    ↓
Read ketrics.config.json → fs.readFileSync() → JSON.parse() → Zod parse
    ↓
Collect errors/warnings → Zod error messages + custom checks
    ↓
Read .env → dotenv.config() → Extract KETRICS_* vars → Zod parse
    ↓
Token format check → Regex /^ktd_/ → Warning if doesn't match
    ↓
Return ValidationResult → { valid: boolean, errors: [], warnings: [] }
    ↓
Display results → logger.error() or logger.success()
```

## Error Handling

### Error Scenarios and Handling

**Configuration Loading Errors**
- File not found: "Configuration file not found: {path}\nRun 'ketrics init' to create one."
- Invalid JSON: "Invalid JSON in configuration file: {path}"
- Zod validation: Field-by-field error messages with paths
- Recovery: Exit with code 1, display errors before exit

**Build Errors**
- Directory missing: "frontend/ directory not found"
- Missing node_modules: "Missing node_modules in {name}/. Run 'cd {name} && npm install' first."
- Build command failure: "{name} build failed. Check the output above for errors."
- Missing dist: "{name} build did not produce dist/ directory"
- Recovery: execSync() inherits stdio (shows npm output), thrown Error caught by command handler

**API/Network Errors**
- 401 Unauthorized: "Authentication failed: Invalid or expired deployment token.\nPlease check your KETRICS_TOKEN in the .env file."
- 403 Forbidden: "Authorization failed: Token does not have access to this application.\nPlease verify KETRICS_TENANT_ID and KETRICS_APPLICATION_ID."
- 404 Not Found: "Application not found. Please verify KETRICS_APPLICATION_ID."
- Network unreachable: "Network error: Could not connect to {url}\nPlease check your internet connection and KETRICS_API_URL."
- S3 upload 400: "Upload failed: Invalid request. The presigned URL may have expired."
- S3 upload 403: "Upload failed: Access denied. The presigned URL may have expired or been used."
- S3 upload 413: "Upload failed: File too large. Maximum upload size exceeded."
- Recovery: Error message logged, process exit(1)

**Input Validation Errors**
- Invalid app name: "App name must start with a letter and contain only letters, numbers, hyphens, and underscores"
- Missing template: "Template not found: {name}" with list of available templates
- Directory exists: "Folder '{appName}' already exists."
- Invalid run JSON: "Invalid run file format:" with detailed Zod path and message
- Recovery: Error logged, process exit(1)

### Retry Logic

- **Explicit Retries**: None implemented—all operations are single-attempt
- **Presigned URL Expiration**: 15 minutes (expiresInSeconds from API response)
- **Timeout Handling**:
  - API calls: 30 second timeout
  - S3 uploads: 300 second timeout (5 minutes)
  - User can re-run command if timeout occurs

### Fallback Mechanisms

- **Template Selection**: If multiple templates exist, interactive selection via inquirer; if one template exists, auto-select; if none exist, error with instructions
- **Build Validation**: Checks for node_modules and package.json before running npm build
- **Token Format**: Validates token format (`ktd_` prefix) before API call, providing early feedback
- **Variable Interpolation**: Unknown variables in run JSON remain as-is with warning logged

### Logging Approach

**Logger Levels** (not severity-based, visual categorization):
- `info()`: Blue "ℹ" icon + message (informational)
- `success()`: Green "✔" icon + message (operation succeeded)
- `warn()`: Yellow "⚠" icon + message (non-blocking issues)
- `error()`: Red "✖" icon + message (operation failed)
- `log()`: Plain text (neutral output)
- `header()`: Bold text with newlines (section markers)
- `keyValue()`: Gray key + value (structured data)
- `box()`: Green checkmark box (success summary)

**Log Points**:
1. Command start: `logger.header()` with command name
2. Major operation start: `withSpinner()` text
3. Operation completion: `spinner.succeed()` text
4. Data summaries: `logger.keyValue()` for important values
5. Errors: `logger.error()` before exit or throw
6. Success: `logger.box()` or `logger.success()` at end

**Example Deploy Logging**:
```
Ketrics CLI v1.0.0          [header]
ℹ Loading environment...    [spinner start]
✔ Loaded environment        [spinner succeed]
Building frontend...        [info]
Building backend...         [info]
✔ Build completed           [success]
Frontend dist: ...          [keyValue]
```

## Usage

### Installation and Setup

```bash
# Install globally
npm install -g @ketrics/ketrics-cli

# Or use as dev dependency
npm install --save-dev @ketrics/ketrics-cli

# Verify installation
ketrics --version
```

### Running Commands

#### Create a New Application

```bash
# Interactive template selection
ketrics create my-app

# Specify template directly
ketrics create my-app --template HelloWorld
```

**Output**:
- New directory `my-app/` with template structure
- Console instructions for next steps
- Pre-configured `ketrics.config.json` and package.json files

**Prerequisites**: None (discovers templates from bundled templates/)

#### Build Application

```bash
cd my-app
ketrics build
```

**Output**:
- Compiled `frontend/dist/` directory
- Compiled `backend/dist/` directory
- Console summary with paths

**Prerequisites**:
- Current directory contains `frontend/` and `backend/` subdirectories
- Both directories have `node_modules/` installed
- Both directories have `package.json` with `build` script

#### Deploy Application

```bash
# Standard deployment
ketrics deploy

# Custom .env path
ketrics deploy --env ./config/.env.production

# Dry run (see what would deploy without uploading)
ketrics deploy --dry-run
```

**Output**:
- Deployment ID
- File count and total size
- Processing confirmation

**Prerequisites**:
- `.env` file with KETRICS_TOKEN, KETRICS_API_URL, KETRICS_TENANT_ID, KETRICS_APPLICATION_ID
- Built `frontend/dist/` and `backend/dist/` directories
- Valid deployment token (starts with `ktd_`)

#### Validate Configuration

```bash
# Validate with defaults
ketrics validate

# Custom paths
ketrics validate --config ./config/ketrics.config.json --env ./.env.staging
```

**Output**:
- List of errors (if any)
- List of warnings (if any)
- Success/failure status

**Prerequisites**: None (creates validation report even if files don't exist)

#### Execute API Requests

```bash
# Create request file: request.json
{
  "endpoint": "/users/{{tenantId}}/profile",
  "method": "GET",
  "headers": {
    "Authorization": "Bearer {{token}}"
  }
}

# Execute request
ketrics run request.json

# Verbose output
ketrics run request.json --verbose

# Custom .env
ketrics run request.json --env ./.env.dev
```

**Output**:
- Formatted HTTP request (method, URL, headers, body)
- Formatted HTTP response (status, body)
- Duration in seconds

**Prerequisites**:
- `.env` file with KETRICS_AUTH_TOKEN and KETRICS_RUNTIME_URL
- Valid JSON request file

### Example Invocations

**Full Deployment Workflow**:
```bash
# Create new project
ketrics create my-todo-app --template HelloWorld

# Navigate to project
cd my-todo-app

# Install dependencies
cd frontend && npm install
cd ../backend && npm install
cd ..

# Copy .env from template
cp .env.example .env
# Edit .env with your credentials

# Validate configuration
ketrics validate

# Build application
ketrics build

# Deploy to Ketrics
ketrics deploy
```

**Testing API Endpoints**:
```bash
# Create .env with runtime credentials
cat > .env.test << EOF
KETRICS_TENANT_ID=12345678-1234-1234-1234-123456789012
KETRICS_APPLICATION_ID=87654321-4321-4321-4321-210987654321
KETRICS_AUTH_TOKEN=your_runtime_token_here
KETRICS_RUNTIME_URL=https://api.runtime.ketrics.io
EOF

# Create request file
cat > api-test.json << EOF
{
  "endpoint": "/health",
  "method": "GET",
  "headers": {
    "Authorization": "Bearer {{token}}"
  }
}
EOF

# Execute
ketrics run api-test.json --env .env.test
```

### Testing Approach

**Unit Testing** (not included in code):
- Would test individual service functions: `loadEnvConfig()`, `buildAll()`, `collectFiles()`, etc.
- Mock file system, axios, child_process
- Verify schema validation with valid/invalid inputs
- Test error handling paths

**Integration Testing** (not included in code):
- Test complete command workflows
- Use temporary directories and files
- Mock Ketrics API responses
- Verify file structure creation and modification

**Manual Testing** (recommended):
1. Create test project with `ketrics create test-app`
2. Modify `.env` with test credentials
3. Run `ketrics validate` to verify setup
4. Run `ketrics build` to verify npm scripts exist
5. Run `ketrics deploy --dry-run` to verify packaging
6. Run `ketrics run` with test request to verify runtime access
7. Full `ketrics deploy` to staging environment

**Testing Checklist**:
- Create command with interactive and flag-based template selection
- Build command with missing node_modules, missing dist directories
- Deploy command with invalid token format, network errors, S3 failures
- Validate command with missing files, invalid JSON, schema violations
- Run command with missing variables, malformed JSON, API errors
- Edge cases: empty directories, very large files, special characters in names

## Advanced Topics

### Custom Configuration Patterns

The `include`/`exclude` patterns in `ketrics.config.json` use glob syntax:

```json
{
  "include": [
    "frontend/dist/**/*",
    "backend/dist/**/*"
  ],
  "exclude": [
    "**/*.map",
    "**/node_modules/**",
    "**/.git/**"
  ]
}
```

### Programmatic Usage

The CLI exports services for use in other Node.js applications:

```typescript
import {
  loadEnvConfig,
  buildAll,
  createDeploymentZipBundle,
  uploadToS3,
  initiateDeploy
} from '@ketrics/ketrics-cli';

// Load config
const config = loadEnvConfig('/path/to/.env');

// Build application
const buildResult = buildAll(process.cwd());

// Create ZIP
const zip = await createDeploymentZipBundle(
  buildResult.frontendDistPath,
  buildResult.backendDistPath
);

// Upload
await uploadToS3(presignedUrl, zip.buffer);
```

### Environment-Specific Deployments

Use different `.env` files for different environments:

```bash
# Staging
ketrics deploy --env .env.staging

# Production
ketrics deploy --env .env.production
```

### Debugging

Enable verbose output where available:

```bash
# Run command with verbose flag
ketrics run request.json --verbose

# Build process inherits stdio (shows npm output)
ketrics build  # Shows all npm build output

# API client logs URL before request
# (Search for "console.log" in api-client.ts for debug points)
```

## Version Information

- **CLI Version**: 0.2.3 (auto-generated in `src/version.ts`)
- **Node.js Requirement**: 24.0.0 or later
- **TypeScript**: 5.3.3
- **Last Updated**: 2024-2025

## Contributing

When modifying the CLI:
1. Follow TypeScript strict mode (tsconfig.json)
2. Export types and services from `src/index.ts`
3. Add Zod schemas for new configuration options
4. Use logger utility instead of console.log
5. Wrap async operations with withSpinner for UX
6. Run `npm run build` before testing (generates version.ts)
7. Test all command paths, especially error scenarios