@sembix/cli 1.3.0 → 1.4.0

package/QUICKSTART.md

@@ -0,0 +1,829 @@
+# Sembix CLI - Quick Start Guide
+
+Get started with the Sembix CLI in 5 minutes.
+
+## Table of Contents
+
+- [GitHub Deployment Quick Start](#github-deployment-quick-start)
+- [Studio CLI Quick Start](#studio-cli-quick-start)
+
+---
+
+# GitHub Deployment Quick Start
+
+## Prerequisites Checklist
+
+- [ ] Node.js 20+ installed (`node --version`)
+- [ ] GitHub Personal Access Token with `repo` and `workflow` scopes
+- [ ] Access to a GitHub repository for Sembix Studio deployments
+- [ ] AWS account credentials and infrastructure details ready
+
+## Installation
+
+```bash
+# Install globally from npm
+npm install -g @sembix/cli
+
+# Verify installation
+sembix --version
+```
+
+**Alternative: Install from source**
+
+```bash
+# Clone and install from source
+npm install
+npm run build
+npm link
+```
+
+## Configuration
+
+Run the interactive configuration wizard:
+
+```bash
+sembix configure
+```
+
+This will:
+- Prompt for your GitHub Personal Access Token
+- Prompt for your default GitHub organization (optional)
+- Save credentials securely to `~/.sembix/config`
+
+**Alternative:** Create a `.env` file manually:
+```bash
+cp .env.example .env
+echo "GITHUB_TOKEN=ghp_your_token_here" > .env
+```
+
+## Quick Setup - 2 Commands
+
+### 1. Create Environment
+
+```bash
+sembix studio create
+```
+
+This interactive wizard will:
+- Guide you through all configuration options
+- Create GitHub Actions environment
+- Set all required secrets and variables
+
+**Time:** ~5-10 minutes
+
+### 2. Add Hub Integration (After First Deployment)
+
+After running your first deployment in GitHub Actions:
+
+```bash
+sembix studio add-hub
+```
+
+This will:
+- List your existing environments
+- Prompt for Hub role ARNs from deployment output
+- Update environment with Hub configuration
+
+**Time:** ~2 minutes
+
+## Example Workflow
+
+### Step 1: Initial Setup
+
+```bash
+$ sembix studio create
+
+┌─────────────────────────────────────────┐
+│                                         │
+│       Sembix Studio CLI              │
+│                                         │
+└─────────────────────────────────────────┘
+
+━━━ Repository Selection ━━━
+
+? Select deployment repository: acme-corp/sembix-deployment
+? Environment name: acme-production
+? AWS Account ID: 123456789012
+? AWS Region: us-east-1
+... [continues with all prompts]
+
+✓ Bootstrap environment created successfully!
+
+━━━ Next Steps ━━━
+
+Step 1: Run Bootstrap Deployment
+  1. Go to GitHub Actions
+  2. Run deployment workflow
+  3. Copy Hub role ARNs from output
+
+Step 2: Complete Hub Configuration
+  Run: sembix studio add-hub
+```
+
+### Step 2: GitHub Actions Deployment
+
+1. Navigate to: `https://github.com/acme-corp/sembix-deployment/actions`
+2. Select "Deploy Sembix Studio" workflow
+3. Click "Run workflow"
+4. Select environment: `acme-production`
+5. Wait for deployment to complete
+6. **Copy the Hub role ARNs from the workflow output**
+
+### Step 3: Add Hub Integration
+
+```bash
+$ sembix studio add-hub
+
+━━━ Repository & Environment Selection ━━━
+
+? Select deployment repository: acme-corp/sembix-deployment
+? Select environment: acme-production
+
+━━━ Sembix Hub Cross-Account Roles ━━━
+
+? Hub Engine Execution Role ARN: arn:aws:iam::999999999999:role/hub-engine-execution
+? Hub Consumer Role ARN: arn:aws:iam::999999999999:role/hub-consumer
+? Hub Admin Role ARN: arn:aws:iam::999999999999:role/hub-admin
+
+━━━ AppConfig Integration (Optional) ━━━
+
+? AppConfig Role ARN: [press Enter to skip]
+... [continues]
+
+✓ Hub integration configuration updated successfully!
+
+━━━ Next Steps ━━━
+
+Deploy with Hub Integration
+  1. Go to GitHub Actions
+  2. Run deployment workflow with acme-production
+  3. Full Hub integration is now active!
+```
+
+## Common Commands
+
+```bash
+# Setup new environment
+sembix studio create
+
+# Add Hub integration
+sembix studio add-hub
+# or use alias:
+sembix studio add-hub
+
+# List environments for a repo
+sembix list owner/repo
+
+# Use custom token (override .env)
+sembix studio create --token ghp_custom_token
+
+# Get help
+sembix --help
+sembix studio create --help
+```
+
+## Tips
+
+### 1. Prepare Your Information
+
+Before running `sembix studio create`, gather:
+- AWS Account ID
+- AWS Region
+- IAM role ARN for GitHub Actions
+- S3 bucket name for Terraform state
+- Database name and user
+- ACM certificate ARNs (CloudFront in us-east-1, ALB in your region)
+- Route53 hosted zone ID
+- GitHub App credentials
+- Jira client ID
+
+### 2. Use Defaults When Possible
+
+Many prompts have sensible defaults. Press Enter to accept them:
+- Database name: `sembix_studio`
+- Database user: `sembix_studio_user`
+- VPC CIDR: `10.0.0.0/16`
+- Enable features: Most are `true` by default
+
+### 3. Custom Networking
+
+If you're deploying to an existing VPC:
+- Answer "yes" to "Use existing VPC and subnets?"
+- Have VPC ID and subnet IDs ready
+- Skip VPC CIDR configuration
+
+### 4. Save Your Workflow
+
+After your first setup, you'll know which options you typically use. Document your standard configuration for faster future setups.
+
+### 5. Validate Before Deploy
+
+The CLI validates inputs in real-time:
+- AWS Account IDs must be 12 digits
+- IAM role ARNs must match AWS format
+- CloudFront certificates must be in us-east-1
+- Environment names must be lowercase alphanumeric with hyphens
+
+## Troubleshooting
+
+### Token Issues
+
+```bash
+# Error: GitHub token is required
+# Solution: Run sembix configure to set up your credentials
+
+sembix configure
+
+# Or check .env file exists and contains valid token
+cat .env
+# Should show: GITHUB_TOKEN=ghp_...
+```
+
+### Permission Issues
+
+```bash
+# Error: Resource not accessible by integration
+# Solution: Token needs 'repo' and 'workflow' scopes
+# Create new token at: https://github.com/settings/tokens
+```
+
+### Build Issues
+
+```bash
+# Error: Cannot find module
+# Solution: Reinstall dependencies
+
+rm -rf node_modules
+npm install
+npm run build
+```
+
+## Next Steps
+
+After successful setup:
+
+1. **Deploy Infrastructure** - Run GitHub Actions workflow
+2. **Verify Deployment** - Check AWS Console for resources
+3. **Add Hub Integration** - Run `sembix studio add-hub`
+4. **Final Deployment** - Deploy again with Hub enabled
+5. **Access Studio** - Navigate to your CloudFront domain
+
+## Getting Help
+
+```bash
+# CLI help
+sembix --help
+
+# Command-specific help
+sembix studio create --help
+sembix studio add-hub --help
+
+# Documentation
+cat README.md
+```
+
+## Reference
+
+- Full documentation: [README.md](./README.md)
+- Configuration reference: [README.md#configuration-reference](./README.md#configuration-reference)
+
+---
+
+# Studio CLI Quick Start
+
+Connect to and manage Sembix Studio instances directly from the CLI.
+
+## Prerequisites Checklist
+
+- [ ] Node.js 20+ installed (`node --version`)
+- [ ] Access to a Sembix Studio instance
+- [ ] Studio API URL (e.g., `https://studio.example.com`)
+- [ ] Cognito authentication credentials:
+  - [ ] User Pool ID (e.g., `us-east-1_ABC123`)
+  - [ ] Client ID
+  - [ ] Cognito Domain (e.g., `https://auth.example.com`)
+  - [ ] AWS Region (e.g., `us-east-1`)
+
+## Installation
+
+```bash
+# Install globally from npm
+npm install -g @sembix/cli
+
+# Verify installation
+sembix --version
+```
+
+## Quick Setup - 3 Commands
+
+### 1. Configure Studio Profile
+
+```bash
+sembix configure
+```
+
+This interactive wizard will:
+- Prompt for GitHub credentials (token and optional default org)
+- Optionally prompt to configure a Studio profile:
+  - Profile name (default: "default")
+  - Studio API URL
+  - Cognito configuration (User Pool ID, Client ID, Domain, Region)
+- Save configuration to `~/.sembix/config`
+
+**Time:** ~2 minutes
+
+### 2. Authenticate with Studio
+
+```bash
+sembix login
+```
+
+This will:
+- Open your browser for Cognito authentication
+- Complete OAuth flow with PKCE
+- Store authentication tokens securely
+- Display token expiration time
+
+**Time:** ~1 minute
+
+### 3. Start a Workflow
+
+```bash
+# Interactive mode (recommended for first time)
+sembix workflow start
+
+# Or with explicit IDs
+sembix workflow start --project-id proj_123 --workflow-id wf_456
+
+# Or with workflow name
+sembix workflow start --project-id proj_123 --workflow-name "Deploy to Production"
+```
+
+This will:
+- Start workflow execution in Studio
+- Return run ID and task ARN
+- Display success confirmation
+- Interactive mode prompts for project, workflow, and inputs
+
+**Time:** ~10 seconds
+
+### 4. Set Default Project (Optional)
+
+```bash
+sembix profile set-default-project production proj_abc123
+```
+
+This allows you to omit `--project-id` in future commands:
+
+```bash
+# Now you can just use:
+sembix workflow start --workflow-id wf_456
+
+# Instead of:
+sembix workflow start --project-id proj_abc123 --workflow-id wf_456
+```
+
+**Time:** ~5 seconds
+
+## Example Workflow
+
+### Step 1: Configure Studio Profile
+
+```bash
+$ sembix configure
+
+┌─────────────────────────────────────────┐
+│                                         │
+│   Configure Sembix CLI                  │
+│                                         │
+└─────────────────────────────────────────┘
+
+? GitHub Personal Access Token: **********************
+? Default GitHub Organization (optional): my-org
+? Configure Sembix Studio profile? Yes
+
+━━━ Studio Profile Configuration ━━━
+
+? Profile name: production
+? Studio API URL: https://studio.example.com
+? Cognito User Pool ID: us-east-1_ABC123
+? Cognito Client ID: 1a2b3c4d5e6f7g8h9i0j
+? Cognito Region: us-east-1
+? Cognito Domain: https://auth.example.com
+
+✓ Configuration saved successfully!
+✓ Studio profile 'production' configured successfully!
+
+━━━ Next Steps ━━━
+
+Authenticate with Studio:
+  sembix login production
+```
+
+### Step 2: Authenticate
+
+```bash
+$ sembix login --profile production
+
+┌─────────────────────────────────────────┐
+│                                         │
+│   Sembix Studio Authentication       │
+│                                         │
+└─────────────────────────────────────────┘
+
+Authenticating with profile: production
+
+✓ Starting local callback server on port 3000...
+✓ Opening browser for authentication...
+
+[Browser opens to Cognito login page]
+
+✓ Authentication successful!
+✓ Tokens stored securely
+
+Token expires: 2024-01-15 14:30:00 UTC (in 1 hour)
+
+━━━ Next Steps ━━━
+
+Start a workflow:
+  sembix workflow start --project-id <id> --workflow-id <id>
+
+List workflow runs:
+  sembix workflow list
+```
+
+### Step 3: Start a Workflow
+
+```bash
+$ sembix workflow start --project-id proj_abc123 --workflow-id wf_def456
+
+┌─────────────────────────────────────────┐
+│                                         │
+│      Start Workflow Execution        │
+│                                         │
+└─────────────────────────────────────────┘
+
+Starting workflow...
+
+✓ Workflow started successfully!
+
+Run ID: run_xyz789
+Task ARN: arn:aws:ecs:us-east-1:123456789012:task/cluster/abc123
+
+━━━ Next Steps ━━━
+
+Check workflow status:
+  sembix workflow run status --workflow-id wf_def456 --run-id run_xyz789
+
+Watch workflow progress:
+  sembix workflow run status --workflow-id wf_def456 --run-id run_xyz789 --watch
+```
+
+### Step 4: Check Workflow Status
+
+```bash
+$ sembix workflow run status --workflow-id wf_def456 --run-id run_xyz789
+
+┌─────────────────────────────────────────┐
+│                                         │
+│       Workflow Run Status            │
+│                                         │
+└─────────────────────────────────────────┘
+
+┌──────────────┬────────────────────────────────────────┐
+│ Field        │ Value                                  │
+├──────────────┼────────────────────────────────────────┤
+│ Run ID       │ run_xyz789                             │
+│ Workflow ID  │ wf_def456                              │
+│ Status       │ RUNNING                                │
+│ Progress     │ 45%                                    │
+│ Created At   │ 2024-01-15 13:30:00 UTC                │
+│ Creator ID   │ user_123                               │
+└──────────────┴────────────────────────────────────────┘
+
+━━━ Next Steps ━━━
+
+Watch for completion:
+  sembix workflow run status --workflow-id wf_def456 --run-id run_xyz789 --watch
+```
+
+### Step 5: Start Workflow with Input Variables
+
+```bash
+# Using JSON string
+$ sembix workflow start \
+  --project-id proj_abc123 \
+  --workflow-id wf_def456 \
+  --inputs '{"environment":"production","version":"1.2.3"}'
+
+# Using JSON file
+$ cat inputs.json
+{
+  "environment": "production",
+  "version": "1.2.3",
+  "config": {
+    "timeout": 300,
+    "retries": 3
+  }
+}
+
+$ sembix workflow start \
+  --project-id proj_abc123 \
+  --workflow-id wf_def456 \
+  --inputs @inputs.json
+
+✓ Workflow started successfully!
+Run ID: run_abc123
+```
+
+## Common Studio CLI Commands
+
+```bash
+# Profile Management
+sembix configure                     # Configure new profile
+sembix profile list                  # List all profiles
+sembix profile set-default <name>    # Set default profile
+sembix profile delete <name>         # Delete a profile
+sembix profile set-default-project <profile> <project-id>  # Set default project
+sembix profile get-default-project <profile>               # Get default project
+sembix profile clear-default-project <profile>             # Clear default project
+
+# Project Operations
+sembix project list                  # List all projects
+sembix project list --name "My Project"  # Search by name
+sembix project show --project-id <id>    # Show project details
+
+# Authentication
+sembix login                         # Login with default profile
+sembix login --profile production    # Login with specific profile
+sembix logout                        # Logout from default profile
+sembix logout --profile production   # Logout from specific profile
+sembix logout --all                  # Logout from all profiles
+
+# Workflow Operations
+sembix workflow start                                    # Interactive mode
+sembix workflow start --project-id <id> --workflow-id <id>
+sembix workflow start --project-id <id> --workflow-name "Name"
+sembix workflow start --workflow-id <id> --inputs @file.json  # Uses default project
+sembix workflow list                                     # List workflow instances
+sembix workflow show --project-id <id> --workflow-id <id>
+sembix workflow run list                                 # List workflow runs
+sembix workflow run list --workflow-id <id>
+sembix workflow run show --workflow-id <id> --run-id <id>
+sembix workflow run status --workflow-id <id> --run-id <id> --watch
+sembix workflow run stop --workflow-id <id> --run-id <id>
+
+# Using specific profile
+sembix workflow start --profile production --project-id <id> --workflow-id <id>
+
+# Output formatting
+sembix project list --output pretty
+sembix workflow run list --pretty
+```
+
+## Tips
+
+### 1. Multiple Studio Instances
+
+Manage multiple Studio instances with profiles:
+
+```bash
+# Configure production profile
+sembix configure
+# Profile name: production
+# API URL: https://studio-prod.example.com
+
+# Configure staging profile
+sembix configure
+# Profile name: staging
+# API URL: https://studio-staging.example.com
+
+# Use specific profile
+sembix login --profile staging
+sembix workflow start --profile staging --project-id <id> --workflow-id <id>
+
+# Switch default profile
+sembix profile set-default staging
+```
+
+### 2. Token Management
+
+Tokens are stored securely and refreshed automatically:
+
+```bash
+# Check which profiles have active tokens
+sembix profile list
+# Shows: production (authenticated), staging (not authenticated)
+
+# Tokens expire after 1 hour by default
+# CLI automatically refreshes tokens when needed
+
+# Manually logout to clear tokens
+sembix logout --profile production
+```
+
+### 3. Input Variables
+
+Multiple ways to provide workflow inputs:
+
+```bash
+# Simple JSON string
+--inputs '{"key":"value"}'
+
+# From file (recommended for complex inputs)
+--inputs @inputs.json
+
+# With workspace context
+--inputs '{"workspaceId":"ws_123","workspaceName":"my-workspace"}'
+
+# With issue context
+--inputs '{"issueId":"issue_456","issueKey":"PROJ-123"}'
+```
+
+### 4. Monitoring Workflows
+
+Watch workflow progress in real-time:
+
+```bash
+# Start workflow and get run ID
+RUN_ID=$(sembix workflow start --project-id proj_123 --workflow-id wf_456 | grep "Run ID" | awk '{print $3}')
+
+# Watch status until completion
+sembix workflow run status --workflow-id wf_456 --run-id $RUN_ID --watch
+
+# List recent runs
+sembix workflow run list --workflow-id wf_456 --limit 10
+```
+
+### 6. Output Formatting
+
+Control output format for better readability or automation:
+
+```bash
+# Pretty JSON for human reading
+sembix project list --pretty
+
+# JSON for scripts (default)
+sembix workflow run list --output json
+
+# Text for terminal display
+sembix project list --output text
+```
+
+### 7. Profile Configuration Files
+
+Profiles are stored in `~/.sembix/config`:
+
+```ini
+[profile production]
+api_url=https://studio-prod.example.com
+cognito_user_pool_id=us-east-1_ABC123
+cognito_client_id=1a2b3c4d5e6f7g8h9i0j
+cognito_region=us-east-1
+cognito_domain=https://auth-prod.example.com
+
+[profile staging]
+api_url=https://studio-staging.example.com
+cognito_user_pool_id=us-east-1_XYZ789
+cognito_client_id=9i8h7g6f5e4d3c2b1a0
+cognito_region=us-east-1
+cognito_domain=https://auth-staging.example.com
+```
+
+Tokens are stored separately in `~/.sembix/tokens/<profile>.json` with restricted permissions (0600).
+
+## Troubleshooting
+
+### Authentication Issues
+
+```bash
+# Error: Browser did not open
+# Solution: Manually open the URL displayed in terminal
+
+# Error: Authentication timeout
+# Solution: Complete authentication within 5 minutes
+# If timeout occurs, run 'sembix login' again
+
+# Error: Token expired
+# Solution: CLI automatically refreshes tokens
+# If refresh fails, run 'sembix login' again
+
+sembix login --profile production
+```
+
+### Profile Issues
+
+```bash
+# Error: Profile not found
+# Solution: Configure the profile first
+
+sembix configure
+
+# Error: No default profile
+# Solution: Set a default profile or specify --profile flag
+
+sembix profile set-default production
+# or
+sembix login --profile production
+
+# List all configured profiles
+sembix profile list
+```
+
+### API Connection Issues
+
+```bash
+# Error: Cannot connect to Studio API
+# Solution: Verify API URL in profile configuration
+
+sembix profile list
+# Check API URL is correct
+
+# Reconfigure profile if needed
+sembix configure
+# Use same profile name to update existing profile
+
+# Error: 401 Unauthorized
+# Solution: Re-authenticate
+
+sembix login --profile production
+```
+
+### Workflow Execution Issues
+
+```bash
+# Error: Invalid input format
+# Solution: Validate JSON syntax
+
+# Test JSON validity
+echo '{"key":"value"}' | jq .
+
+# Use file for complex inputs
+cat inputs.json | jq .  # Validate
+sembix workflow start --project-id <id> --workflow-id <id> --inputs @inputs.json
+
+# Error: Workflow not found
+# Solution: Verify project ID and workflow ID
+
+# List workflow instances
+sembix workflow list --project-id <id>
+
+# Or use interactive mode to search
+sembix workflow start
+```
+
+### Token Storage Issues
+
+```bash
+# Error: Permission denied writing tokens
+# Solution: Check ~/.sembix directory permissions
+
+ls -la ~/.sembix
+chmod 700 ~/.sembix
+chmod 600 ~/.sembix/tokens/*
+
+# Clear and re-authenticate
+sembix logout --all
+sembix login
+```
+
+## Next Steps
+
+After successful Studio CLI setup:
+
+1. **Explore Workflows** - List available workflows with `sembix workflow list`
+2. **Automate Executions** - Integrate workflow commands into CI/CD pipelines
+3. **Monitor Progress** - Use `--watch` flag for real-time status updates
+4. **Manage Profiles** - Configure profiles for different environments
+5. **Review Documentation** - See [COMMANDS.md](./COMMANDS.md) for complete command reference
+
+## Getting Help
+
+```bash
+# CLI help
+sembix --help
+
+# Studio CLI commands help
+sembix configure --help
+sembix login --help
+sembix workflow --help
+sembix workflow start --help
+sembix workflow status --help
+sembix workflow list --help
+sembix profile --help
+
+# Documentation
+cat README.md
+cat COMMANDS.md
+```
+
+## Reference
+
+- Full documentation: [README.md](./README.md)
+- Studio CLI documentation: [README.md#studio-cli](./README.md#studio-cli)
+- Command reference: [COMMANDS.md](./COMMANDS.md)
+- Studio CLI commands: [COMMANDS.md#studio-cli-commands](./COMMANDS.md#studio-cli-commands)
+
+---
+
+**Need more help?** Contact the Sembix team or refer to the main documentation.