@sembix/cli 1.3.0 → 1.4.0

package/USAGE-EXAMPLES.md

@@ -0,0 +1,872 @@
+# Sembix CLI - Usage Examples
+
+Real-world examples showing different ways to use the CLI.
+
+## Getting Started
+
+### First Time Setup
+
+Before creating environments, configure your credentials:
+
+```bash
+sembix configure
+```
+
+**What happens:**
+- Prompts for GitHub Personal Access Token
+- Prompts for default GitHub organization (optional)
+- Saves to `~/.sembix/config` securely
+
+**Alternative:** Create a `.env` file with `GITHUB_TOKEN=ghp_...`
+
+---
+
+## Basic Usage Patterns
+
+### 1. Fully Interactive (Beginner-Friendly)
+
+Perfect for first-time users or when you want to see all options:
+
+```bash
+sembix studio create
+```
+
+**What happens:**
+- Prompts for repository selection
+- Prompts for environment name
+- Walks through all 8 configuration steps with explanations
+- Creates environment with all settings
+
+---
+
+### 2. Quick Create with Name Only
+
+When you know the environment name but want to select repo interactively:
+
+```bash
+sembix studio create production
+```
+
+**What happens:**
+- Uses "production" as environment name
+- Prompts for repository selection
+- Walks through configuration steps
+- Creates environment
+
+---
+
+### 3. Specify Repository and Environment
+
+Fast setup when you know both values:
+
+```bash
+sembix studio create production --repo acme-corp/sembix-deployment
+```
+
+Or using the `-e` flag:
+
+```bash
+sembix studio create --repo acme-corp/sembix-deployment --env production
+```
+
+**What happens:**
+- ✅ Validates repository exists
+- ✅ Validates environment name format
+- ✅ Checks environment doesn't already exist
+- Skips repository and name prompts
+- Walks through configuration steps
+- Creates environment
+
+**Validation errors:**
+
+```bash
+# Invalid repository
+$ sembix studio create prod --repo invalid/repo
+✗ Repository 'invalid/repo' not found or not accessible.
+
+💡 Make sure:
+   • The repository name is correct (owner/repo)
+   • Your GitHub token has access to this repository
+
+# Environment already exists
+$ sembix studio create existing --repo acme/deploy
+✗ Environment 'existing' already exists in acme/deploy
+
+💡 Tip:
+   • Use a different environment name
+   • Or update the existing environment with: sembix studio add-hub
+
+# Invalid environment name
+$ sembix studio create PROD --repo acme/deploy
+✗ Invalid environment name. Must be lowercase letters, numbers, and hyphens (min 3 chars).
+```
+
+---
+
+## Hub Integration Usage
+
+### 1. Fully Interactive
+
+```bash
+sembix studio add-hub
+```
+
+**What happens:**
+- Prompts for repository selection
+- Lists environments in that repository
+- Prompts for environment to update
+- Collects Hub role ARNs
+- Updates environment
+
+---
+
+### 2. Specify Environment Only
+
+```bash
+sembix studio add-hub production
+```
+
+**What happens:**
+- Uses "production" as environment name
+- Prompts for repository selection
+- ✅ Validates environment exists in selected repository
+- Collects Hub role ARNs
+- Updates environment
+
+---
+
+### 3. Specify Both Repository and Environment
+
+Fastest way - no prompts except for Hub configuration:
+
+```bash
+sembix studio add-hub production --repo acme-corp/sembix-deployment
+```
+
+Or using flags:
+
+```bash
+sembix studio add-hub --repo acme-corp/sembix-deployment --env production
+```
+
+**What happens:**
+- ✅ Validates repository exists
+- ✅ Validates environment exists in repository
+- Skips repository and environment prompts
+- Collects Hub role ARNs
+- Updates environment
+
+**Validation errors:**
+
+```bash
+# Environment doesn't exist
+$ sembix studio add-hub nonexistent --repo acme/deploy
+✗ Environment 'nonexistent' not found in acme/deploy
+
+Available environments:
+  - production
+  - staging
+
+# Repository not found
+$ sembix studio add-hub prod --repo invalid/repo
+✗ Repository 'invalid/repo' not found or not accessible.
+```
+
+---
+
+## Common Workflows
+
+### Workflow 1: First-Time Setup (Learning Mode)
+
+```bash
+# Step 1: Create environment interactively to learn all options
+sembix studio create
+
+# Follow all prompts, read explanations...
+
+# Step 2: Deploy via GitHub Actions (manual step)
+# Go to https://github.com/owner/repo/actions
+# Run deployment workflow
+# Copy Hub role ARNs from output
+
+# Step 3: Add Hub integration interactively
+sembix studio add-hub
+
+# Select same repository and environment
+# Enter Hub role ARNs
+```
+
+---
+
+### Workflow 2: Experienced User (Fast Mode)
+
+```bash
+# Create environment with known values
+sembix studio create prod --repo acme/deploy
+
+# Answer remaining prompts (AWS, DB, networking, etc.)
+# ... deployment happens in GitHub Actions ...
+
+# Add Hub with known values
+sembix studio add-hub prod --repo acme/deploy
+
+# Enter Hub role ARNs
+# Done!
+```
+
+---
+
+### Workflow 3: CI/CD / Automation
+
+For scripts and automation, provide all non-AWS values upfront:
+
+```bash
+#!/bin/bash
+
+REPO="acme-corp/sembix-deployment"
+ENV="client-${CLIENT_NAME}-production"
+TOKEN="${GITHUB_TOKEN}"
+
+# Create environment (still requires interactive AWS config)
+sembix studio create "${ENV}" \
+  --repo "${REPO}" \
+  --token "${TOKEN}"
+
+# Later, after deployment...
+sembix studio add-hub "${ENV}" \
+  --repo "${REPO}" \
+  --token "${TOKEN}"
+```
+
+---
+
+### Workflow 4: Multiple Environments
+
+Setting up multiple environments for the same repository:
+
+```bash
+# Production
+sembix studio create production --repo acme/deploy
+
+# Staging
+sembix studio create staging --repo acme/deploy
+
+# Development
+sembix studio create development --repo acme/deploy
+
+# List all environments
+sembix studio list acme/deploy
+```
+
+---
+
+## Using Different GitHub Tokens
+
+### Set Default Token (Recommended)
+
+```bash
+# Interactive configuration (easiest)
+sembix configure
+
+# This saves your token to ~/.sembix/config
+# All commands will use this token by default
+```
+
+### Override Token Per Command
+
+```bash
+# Use different token for specific operation
+sembix studio create --token ghp_custom_token --repo acme/deploy
+
+# Useful for:
+# - Testing with different accounts
+# - CI/CD with service account tokens
+# - One-time operations
+```
+
+### Alternative: Environment Variable
+
+```bash
+# In .env file
+GITHUB_TOKEN=ghp_your_default_token
+
+# Or as environment variable
+export GITHUB_TOKEN=ghp_your_token
+
+# All commands use this token by default
+sembix studio create
+sembix studio add-hub
+sembix studio list
+```
+
+---
+
+## Listing Environments
+
+### List All Repositories
+
+```bash
+sembix studio list
+```
+
+**Output:**
+```
+┌─────────────────────────────────────────┐
+│                                         │
+│       Sembix CLI                     │
+│                                         │
+└─────────────────────────────────────────┘
+
+  Sembix Studio - Environments
+
+💡 Tip: Specify a repository to see its environments
+   Example: sembix studio list owner/repo
+
+━━━ Your Repositories ━━━
+
+  1. acme-corp/sembix-deployment
+  2. globex-inc/studio-deploy
+  3. partner-xyz/deployments
+```
+
+---
+
+### List Environments in Repository
+
+```bash
+sembix studio list acme-corp/sembix-deployment
+```
+
+**Output:**
+```
+  Environments in acme-corp/sembix-deployment
+
+━━━ Environments ━━━
+
+  1. production
+     https://github.com/acme-corp/sembix-deployment/settings/environments/production
+
+  2. staging
+     https://github.com/acme-corp/sembix-deployment/settings/environments/staging
+
+  3. development
+     https://github.com/acme-corp/sembix-deployment/settings/environments/development
+```
+
+---
+
+## Error Handling Examples
+
+### Missing GitHub Token
+
+```bash
+$ sembix studio create
+✗ GitHub token is required. Please provide it using one of these methods:
+  1. Run: sembix configure
+  2. Set GITHUB_TOKEN environment variable
+  3. Pass --token flag to the command
+  4. Create a .env file with GITHUB_TOKEN
+
+Configuration file location: ~/.sembix/config
+```
+
+**Solution:**
+```bash
+sembix configure
+```
+
+### Invalid Repository Format
+
+```bash
+$ sembix studio create prod --repo invalid_format
+✗ Invalid repository format. Use: owner/repo
+```
+
+### Repository Not Found
+
+```bash
+$ sembix studio create prod --repo nonexistent/repo
+✗ Repository 'nonexistent/repo' not found or not accessible.
+
+💡 Make sure:
+   • The repository name is correct (owner/repo)
+   • Your GitHub token has access to this repository
+```
+
+### Invalid Environment Name
+
+```bash
+$ sembix studio create "My Environment" --repo acme/deploy
+✗ Invalid environment name. Must be lowercase letters, numbers, and hyphens (min 3 chars).
+```
+
+### Environment Already Exists
+
+```bash
+$ sembix studio create production --repo acme/deploy
+✗ Environment 'production' already exists in acme/deploy
+
+💡 Tip:
+   • Use a different environment name
+   • Or update the existing environment with: sembix studio add-hub
+```
+
+### Environment Not Found (Hub Integration)
+
+```bash
+$ sembix studio add-hub nonexistent --repo acme/deploy
+✗ Environment 'nonexistent' not found in acme/deploy
+
+Available environments:
+  - production
+  - staging
+```
+
+### Missing GitHub Token
+
+```bash
+$ sembix studio create
+✗ GITHUB_TOKEN environment variable is required. Please set it in a .env file or as an environment variable.
+```
+
+---
+
+## Quick Reference
+
+### Create Command Syntax
+
+```bash
+# All valid formats:
+sembix studio create
+sembix studio create <name>
+sembix studio create --env <name>
+sembix studio create --repo <owner/repo>
+sembix studio create <name> --repo <owner/repo>
+sembix studio create --repo <owner/repo> --env <name>
+sembix studio create --repo <owner/repo> --env <name> --token <token>
+```
+
+### Add-Hub Command Syntax
+
+```bash
+# All valid formats:
+sembix studio add-hub
+sembix studio add-hub <name>
+sembix studio add-hub --env <name>
+sembix studio add-hub --repo <owner/repo>
+sembix studio add-hub <name> --repo <owner/repo>
+sembix studio add-hub --repo <owner/repo> --env <name>
+sembix studio add-hub --repo <owner/repo> --env <name> --token <token>
+```
+
+### List Command Syntax
+
+```bash
+# All valid formats:
+sembix studio list
+sembix studio list <owner/repo>
+sembix studio list --token <token>
+sembix studio list <owner/repo> --token <token>
+```
+
+---
+
+## Tips for Power Users
+
+### 1. Aliases
+
+Add to your shell profile:
+
+```bash
+# ~/.zshrc or ~/.bashrc
+alias sc='sembix studio create'
+alias sh='sembix studio add-hub'
+alias sl='sembix studio list'
+
+# Usage
+sc prod --repo acme/deploy
+sh prod --repo acme/deploy
+sl acme/deploy
+```
+
+---
+
+### 2. Environment Variables
+
+Store common values:
+
+```bash
+# In your .env or shell profile
+export SEMBIX_REPO="acme-corp/sembix-deployment"
+export GITHUB_TOKEN="ghp_your_token"
+
+# Use in commands
+sembix studio create prod --repo "$SEMBIX_REPO"
+```
+
+---
+
+### 3. Tab Completion
+
+Most shells support command completion for `--repo`, `--env`, etc.
+
+---
+
+### 4. Validation First
+
+Check what exists before creating:
+
+```bash
+# See what's already there
+sembix studio list acme/deploy
+
+# Create new environment
+sembix studio create newenv --repo acme/deploy
+```
+
+---
+
+## Best Practices
+
+### ✅ DO
+
+- Use `--repo` and `--env` for repeated operations
+- Validate with `sembix studio list` first
+- Use descriptive environment names (client-production, staging-v2)
+- Store GitHub token in `.env` file
+- Keep environment names lowercase with hyphens
+
+### ❌ DON'T
+
+- Don't use uppercase in environment names
+- Don't use spaces or special characters
+- Don't share your GitHub token
+- Don't create environments without verifying repo access first
+- Don't forget to run deployment between create and add-hub
+
+---
+
+## Project Management Usage
+
+### 1. List All Projects
+
+```bash
+sembix project list
+```
+
+**Output:**
+```json
+{
+  "message": "Projects retrieved successfully",
+  "items": [
+    {
+      "projectId": "proj_abc123",
+      "name": "Production Deployment",
+      "state": "ACTIVE",
+      "createdAt": "2024-01-15T10:00:00Z"
+    },
+    {
+      "projectId": "proj_def456",
+      "name": "Staging Environment",
+      "state": "ACTIVE",
+      "createdAt": "2024-01-20T14:30:00Z"
+    }
+  ]
+}
+```
+
+---
+
+### 2. Search Projects by Name
+
+```bash
+sembix project list --name "Production"
+```
+
+---
+
+### 3. Show Project Details
+
+```bash
+sembix project show --project-id proj_abc123
+```
+
+**Output:**
+```json
+{
+  "projectId": "proj_abc123",
+  "name": "Production Deployment",
+  "description": "Main production deployment project",
+  "state": "ACTIVE",
+  "createdAt": "2024-01-15T10:00:00Z",
+  "workflowPackConfigured": true,
+  "providerConfiguration": {...}
+}
+```
+
+---
+
+## Profile Default Project Usage
+
+### 1. Set Default Project for Profile
+
+```bash
+sembix profile set-default-project production proj_abc123
+```
+
+**Output:**
+```
+✓ Default project set for profile 'production': proj_abc123
+```
+
+---
+
+### 2. Use Default Project in Commands
+
+```bash
+# Set default
+sembix profile set-default-project production proj_abc123
+
+# Now you can omit --project-id
+sembix workflow start --workflow-id wf_456 --inputs '{...}'
+
+# Instead of
+sembix workflow start --project-id proj_abc123 --workflow-id wf_456 --inputs '{...}'
+```
+
+---
+
+### 3. Get Default Project
+
+```bash
+sembix profile get-default-project production
+```
+
+**Output:**
+```
+proj_abc123
+```
+
+---
+
+### 4. Clear Default Project
+
+```bash
+sembix profile clear-default-project production
+```
+
+**Output:**
+```
+✓ Default project cleared for profile 'production'
+```
+
+---
+
+## Interactive Workflow Start Usage
+
+### 1. Fully Interactive Mode
+
+```bash
+sembix workflow start
+```
+
+**What happens:**
+1. Prompts to select profile (if multiple configured)
+2. Prompts to select project (or uses default)
+3. Prompts to select workflow from project
+4. Prompts for each required input variable
+5. Starts workflow with provided inputs
+
+**Example interaction:**
+```
+? Select profile: production
+? Select project: Production Deployment (proj_abc123)
+? Select workflow: Deploy to Production (wf_deploy_prod)
+
+Configure workflow inputs:
+
+? environment (string): production
+? version (string): 1.2.3
+? replicas (number): 3
+
+✓ Workflow started successfully!
+  Run ID: run_xyz789
+  Task ARN: arn:aws:ecs:...
+```
+
+---
+
+### 2. Interactive with Workflow Name
+
+```bash
+sembix workflow start --project-id proj_abc123 --workflow-name "Deploy"
+```
+
+**What happens:**
+1. Searches for workflows matching "Deploy" in project
+2. If multiple matches, prompts to select
+3. Prompts for input variables
+4. Starts workflow
+
+---
+
+### 3. Non-Interactive Mode
+
+```bash
+sembix workflow start \
+  --project-id proj_abc123 \
+  --workflow-id wf_456 \
+  --inputs @inputs.json \
+  --no-interactive
+```
+
+**What happens:**
+- Skips all prompts
+- Uses provided inputs directly
+- Fails if required inputs are missing
+
+---
+
+## Output Formatting Usage
+
+### 1. JSON Output (Default)
+
+```bash
+sembix project list
+```
+
+**Output:**
+```json
+{"message":"Projects retrieved successfully","items":[...]}
+```
+
+---
+
+### 2. Pretty JSON Output
+
+```bash
+sembix project list --pretty
+```
+
+**Output:**
+```json
+{
+  "message": "Projects retrieved successfully",
+  "items": [
+    {
+      "projectId": "proj_abc123",
+      "name": "Production Deployment",
+      "state": "ACTIVE"
+    }
+  ]
+}
+```
+
+---
+
+### 3. Text Output
+
+```bash
+sembix project list --output text
+```
+
+**Output:**
+```
+Projects:
+  1. Production Deployment (proj_abc123) - ACTIVE
+  2. Staging Environment (proj_def456) - ACTIVE
+```
+
+---
+
+## Workflow Run Management Usage
+
+### 1. List Workflow Runs (Excludes Subflows)
+
+```bash
+sembix workflow run list --workflow-id wf_456
+```
+
+**Output:**
+```json
+{
+  "items": [
+    {
+      "runs": [
+        {
+          "runId": "run_xyz789",
+          "status": "IN_PROGRESS",
+          "progress": 45,
+          "createdAt": "2024-01-15T14:30:00Z"
+        }
+      ],
+      "totalCount": 15
+    }
+  ]
+}
+```
+
+---
+
+### 2. Include Sub-Workflow Runs
+
+```bash
+sembix workflow run list --workflow-id wf_456 --include-subflows
+```
+
+---
+
+### 3. Filter to Top-Level Runs Only
+
+```bash
+sembix workflow run list --parent-id NULL
+```
+
+---
+
+### 4. Show Full Run Details
+
+```bash
+sembix workflow run show --workflow-id wf_456 --run-id run_xyz789
+```
+
+**Output:**
+```json
+{
+  "run": {
+    "runId": "run_xyz789",
+    "status": "IN_PROGRESS",
+    "progress": 45,
+    "steps": [
+      {
+        "stepId": "step_1",
+        "name": "Initialize",
+        "state": "Complete"
+      },
+      {
+        "stepId": "step_2",
+        "name": "Deploy",
+        "state": "Pending"
+      }
+    ],
+    "currentStepId": "step_2"
+  }
+}
+```
+
+---
+
+### 5. Watch Run Until Completion
+
+```bash
+sembix workflow run show --workflow-id wf_456 --run-id run_xyz789 --watch
+```
+
+**What happens:**
+- Polls run status every 5 seconds
+- Displays progress updates
+- Exits when run reaches terminal state (COMPLETED, FAILED, CANCELLED)
+
+---
+
+**Last Updated**: November 2024