@sembix/cli 1.3.0 → 1.4.0

package/README.md

@@ -8,27 +8,40 @@ A terminal-based CLI tool for managing Sembix products. An intuitive command-lin
 - [Prerequisites](#prerequisites)
 - [Deployment Process](#deployment-process)
 - [Installation](#installation)
+- [Quick Start](#quick-start)
+  - [GitHub Deployment Quick Start](#github-deployment-quick-start)
+  - [Studio CLI Quick Start](#studio-cli-quick-start)
 - [Configuration](#configuration)
   - [Option 1: Interactive Configuration (Recommended)](#option-1-interactive-configuration-recommended)
   - [Option 2: Environment Variables (.env file)](#option-2-environment-variables-env-file)
   - [Option 3: Config File (Recommended for Automation)](#option-3-config-file-recommended-for-automation)
   - [Creating a GitHub Token](#creating-a-github-token)
   - [Credential Priority](#credential-priority)
-- [Usage](#usage)
-  - [Quick Start](#quick-start)
-  - [Example: Complete First-Time Setup](#example-complete-first-time-setup)
 - [Commands](#commands)
-  - [`sembix configure`](#sembix-configure)
-  - [`sembix studio create`](#sembix-studio-create)
-  - [`sembix studio update`](#sembix-studio-update)
-  - [`sembix studio add-hub`](#sembix-studio-add-hub)
-  - [`sembix studio list`](#sembix-studio-list)
+  - [Global Commands](#global-commands)
+  - [Studio Deployment Commands](#studio-deployment-commands)
+  - [Studio API Commands](#studio-api-commands)
+  - [Global Options](#global-options)
+- [Usage Examples](#usage-examples)
+  - [Basic Usage Patterns](#basic-usage-patterns)
+  - [Common Workflows](#common-workflows)
+  - [Profile Management](#profile-management-examples)
+  - [Error Handling](#error-handling-examples)
+  - [Best Practices](#best-practices)
+- [Studio CLI](#studio-cli)
+  - [Studio Configuration](#studio-configuration)
+  - [Authentication](#authentication)
+  - [Workflow Operations](#workflow-operations)
 - [Workflow](#workflow)
 - [Configuration Priority](#configuration-priority)
 - [Config File Reference](#config-file-reference)
 - [Use Cases](#use-cases)
-- [Development](#development)
 - [Troubleshooting](#troubleshooting)
+  - [Authentication Issues](#authentication-issues)
+  - [GitHub API Issues](#github-api-issues)
+  - [Studio API Issues](#studio-api-issues)
+  - [Common Errors](#common-errors)
+- [Development](#development)
 - [Advanced Topics](#advanced-topics)
 - [License](#license)
 - [Support](#support)
@@ -45,6 +58,13 @@ A terminal-based CLI tool for managing Sembix products. An intuitive command-lin
 - 🔗 **Hub Integration** - Built-in Hub configuration as part of the main workflow
 - 🎨 **Beautiful UI** - Clean, colorful terminal interface with spinners and status updates
 - ⚡ **Priority Chain** - CLI flags > Config file > Interactive prompts > Defaults
+- 🌐 **Studio Integration** - Connect to Sembix Studio instances with profile-based configuration
+- 🔐 **Cognito Authentication** - Browser-based OAuth flow with automatic token refresh
+- 🔄 **Workflow Execution** - Start, monitor, and manage workflow runs remotely
+- 👤 **Profile Management** - Manage multiple Studio instances like AWS CLI profiles
+- 📊 **Output Formatting** - JSON, pretty-print, or text output for all commands
+- 🎯 **Project Management** - List, search, and view project details
+- 🔗 **Profile Defaults** - Set default projects per profile for faster workflow execution
 
 ## Prerequisites
 
@@ -54,6 +74,10 @@ A terminal-based CLI tool for managing Sembix products. An intuitive command-lin
   - `workflow` - Update GitHub Action workflows
 - **Deployment Repository** - A GitHub repository set up for Sembix Studio deployments
 
+### For Studio Integration (Optional)
+- **Sembix Studio Instance** - Access to a Sembix Studio deployment
+- **Cognito Configuration** - User Pool ID, Client ID, and Domain from Studio admin
+
 ## Deployment Process
 
 Sembix Studio uses a **two-phased deployment** process to establish secure cross-account access with the Sembix Hub:
@@ -115,6 +139,132 @@ npm install
 npm run dev -- studio create
 ```
 
+## Quick Start
+
+Get started with the Sembix CLI in 5 minutes. Choose the workflow that matches your needs:
+
+### GitHub Deployment Quick Start
+
+**Step 1: Configure credentials**
+
+```bash
+sembix configure
+```
+
+Prompts for:
+- GitHub Personal Access Token (required)
+- Default GitHub organization (optional)
+
+**Step 2: Create environment**
+
+```bash
+# Interactive mode (recommended for first-time)
+sembix studio create
+
+# Or with repository specified
+sembix studio create --repo owner/repo
+```
+
+This interactive wizard walks you through 9 configuration steps and creates your GitHub Actions environment with all required secrets.
+
+**Step 3: Deploy via GitHub Actions**
+
+1. Go to your repository's Actions tab
+2. Select the deployment workflow
+3. Choose your environment
+4. Run the workflow
+5. Copy the Hub role ARNs from deployment output
+
+**Step 4: Add Hub integration**
+
+```bash
+sembix studio add-hub production
+
+# Or with repository specified
+sembix studio add-hub production --repo owner/repo
+```
+
+Enter the Hub role ARNs from the deployment output.
+
+**Step 5: Deploy again**
+
+Run the GitHub Actions workflow again with Hub enabled. Your Studio environment is now fully operational!
+
+### Studio CLI Quick Start
+
+**Step 1: Configure Studio profile**
+
+```bash
+sembix configure
+```
+
+After GitHub credentials, choose to configure a Studio profile with:
+- Profile name (e.g., "production")
+- Studio API URL
+- Cognito User Pool ID, Client ID, Domain, and Region
+
+**Step 2: Authenticate**
+
+```bash
+# Login with default profile
+sembix login
+
+# Or specific profile
+sembix login --profile production
+```
+
+Opens your browser for Cognito authentication. Tokens are stored securely and refreshed automatically.
+
+**Step 3: Start a workflow**
+
+```bash
+# Interactive mode (recommended)
+sembix workflow start
+
+# With explicit IDs
+sembix workflow start --project-id proj_123 --workflow-id wf_456
+
+# With workflow name
+sembix workflow start --project-id proj_123 --workflow-name "Deploy"
+```
+
+**Step 4: Monitor workflow**
+
+```bash
+# Check status
+sembix workflow run status --workflow-id wf_456 --run-id run_789
+
+# Watch until completion
+sembix workflow run status --workflow-id wf_456 --run-id run_789 --watch
+```
+
+### Common Tasks Cheat Sheet
+
+```bash
+# List environments
+sembix studio list owner/repo
+
+# List profiles
+sembix profile list
+
+# Set default project
+sembix profile set-default-project production proj_123
+
+# List projects
+sembix project list
+
+# List workflows
+sembix workflow list
+
+# List workflow runs
+sembix workflow run list --workflow-id wf_456
+
+# Stop a workflow
+sembix workflow run stop --workflow-id wf_456 --run-id run_789
+```
+
+For detailed documentation, see the sections below.
+
 ## Configuration
 
 ### Option 1: Interactive Configuration (Recommended)
@@ -192,115 +342,50 @@ The CLI checks for credentials in this order (highest to lowest priority):
 3. `~/.sembix/config` (created by `sembix configure`)
 4. Project `.env` file
 
-## Usage
-
-### Quick Start
-
-**Step 1: Configure credentials (first time only)**
-
-```bash
-sembix configure
-```
-
-This interactive command will prompt you for:
-- GitHub Personal Access Token
-- Default GitHub organization (optional)
-
-Your credentials are saved securely to `~/.sembix/config`.
-
-**Step 2: Create your environment**
+## Commands
 
-For a complete deployment, follow the **two-phased process**:
+Complete reference for all Sembix CLI commands.
 
-```bash
-# PHASE 1: Bootstrap deployment
-sembix studio create --skip-hub
-# → Deploy via GitHub Actions
-# → Send IAM ARNs to Sembix support
-# → Receive Hub role ARNs from support
+### Command Structure
 
-# PHASE 2: Hub integration and full deployment
-sembix studio add-hub <environment>
-# → Deploy via GitHub Actions again
-# → Studio environment fully operational
 ```
-
-See the [Deployment Process](#deployment-process) section above for detailed explanation.
-
-**Alternative workflows:**
-
-```bash
-# Fully interactive (prompts for all configuration)
-sembix studio create
-
-# Fast setup with config file
-sembix studio create --config production.yaml
-
-# Fully automated with CLI flags
-sembix studio create production \
-  --repo acme/deploy \
-  --aws-account-id 123456789012 \
-  --aws-region us-east-1 \
-  --customer-role-arn arn:aws:iam::123456789012:role/Deploy \
-  --terraform-state-bucket my-tf-state \
-  # ... (all other flags)
+sembix <product> <action> [options] [arguments]
 ```
 
-### Example: Complete First-Time Setup
-
-```bash
-# 1. Configure credentials
-$ sembix configure
-GitHub Personal Access Token: ****
-Default GitHub Organization (optional): acme-corp
-✓ Configuration saved successfully!
-
-# 2. Create environment interactively
-$ sembix studio create
-? Select deployment repository: acme-corp/sembix-deployment
-? Environment name: production
-? AWS Account ID: 123456789012
-... [continues with prompts]
-✓ Environment created successfully!
-
-# 3. Deploy via GitHub Actions (in browser)
-#    → Go to GitHub Actions
-#    → Run workflow for "production" environment
-#    → Wait for deployment
-#    → Copy Hub role ARNs from output
-
-# 4. Add Hub integration
-$ sembix studio add-hub production
-? Hub Engine Execution Role ARN: arn:aws:iam::999999999999:role/hub-engine
-... [continues with prompts]
-✓ Hub integration configured!
+- **product**: The Sembix product (e.g., `studio`)
+- **action**: What you want to do (e.g., `create`, `list`, `add-hub`)
+- **options**: Flags like `--token` or `--repo`
+- **arguments**: Required or optional values (e.g., environment name)
 
-# 5. Deploy again via GitHub Actions
-#    → Run workflow again
-#    → Studio is now fully operational!
-```
+---
 
-## Commands
+### Global Commands
 
-### `sembix configure`
+#### `sembix configure`
 
 Configure Sembix CLI credentials and settings interactively.
 
-**Syntax:**
+**Usage:**
 
 ```bash
 sembix configure
 ```
 
 **What it does:**
-1. Prompts for your GitHub Personal Access Token (with validation)
+
+1. Prompts for your GitHub Personal Access Token
 2. Prompts for your default GitHub organization (optional)
-3. Saves configuration securely to `~/.sembix/config` with file permissions 0600
+3. Optionally prompts to configure a Sembix Studio profile for API access:
+   - Studio API URL
+   - Cognito User Pool ID, Client ID, Region, and Domain
+4. Saves configuration to `~/.sembix/config` with secure permissions (0600)
 
 **When to use:**
-- First time setup (recommended for all users)
-- Updating your GitHub token when it expires
+
+- First time setup (recommended)
+- Updating your GitHub token
 - Changing your default organization
+- Adding or updating Studio profiles for API access
 
 **Example:**
 
@@ -314,45 +399,61 @@ This will store your configuration in:
 
 ? GitHub Personal Access Token: ****
 ? Default GitHub Organization (optional): acme-corp
+? Configure Sembix Studio profile? Yes
 
-✓ Configuration saved successfully!
+━━━ Studio Profile Configuration ━━━
 
-Your credentials are stored securely in:
-  ~/.sembix/config
+? 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
 
-You can now run Sembix commands without the --token flag.
+✓ Configuration saved successfully!
+✓ Studio profile 'production' configured successfully!
 ```
 
 ---
 
-### `sembix studio create`
+### Studio Deployment Commands
+
+Commands for managing Sembix Studio GitHub Actions deployments.
+
+#### `sembix studio create [name]`
 
-Create a new Sembix Studio environment with complete configuration.
+Create a new Sembix Studio environment with full interactive configuration.
 
-**Syntax:**
+**Usage:**
 
 ```bash
-sembix studio create [environment-name] [options]
+# Interactive mode
+sembix studio create
+
+# With environment name
+sembix studio create production
+
+# With name and repository
+sembix studio create production --repo acme/deploy
 ```
 
-**Options:**
+**Key Options:**
 
 ```bash
-# General
--t, --token <token>           GitHub personal access token
--c, --config <path>           Path to YAML configuration file
--r, --repo <repo>             Target repository (owner/repo format)
--e, --env <environment>       Environment name (alternative to positional arg)
+-r, --repo <repo>              Target repository (owner/repo)
+-e, --env <environment>        Environment name
+-t, --token <token>            GitHub personal access token
+-c, --config <path>            Path to YAML configuration file
 
-# AWS Basic Configuration
---aws-account-id <id>         AWS Account ID (12 digits)
---aws-region <region>         AWS Region (e.g., us-east-1)
---customer-role-arn <arn>     GitHub Actions IAM role ARN
---terraform-state-bucket <bucket>  S3 bucket for Terraform state
+# AWS Configuration
+--aws-account-id <id>          AWS Account ID (12 digits)
+--aws-region <region>          AWS Region
+--customer-role-arn <arn>      GitHub Actions IAM role ARN
+--terraform-state-bucket <bucket>  Terraform state S3 bucket
 
 # Database
---database-name <name>        PostgreSQL database name
---database-user <user>        PostgreSQL database user
+--database-name <name>         PostgreSQL database name
+--database-user <user>         PostgreSQL database user
 
 # Networking
 --enable-vpc-endpoints <boolean>     Enable VPC endpoints (true/false)
@@ -387,203 +488,1385 @@ sembix studio create [environment-name] [options]
 --iam-studio-memory <arn>            Studio Memory role ARN
 --iam-studio-notification <arn>      Studio Notification role ARN
 
-# TLS/DNS
---cloudfront-domain <domain>         CloudFront custom domain
---cloudfront-cert-arn <arn>          CloudFront SSL certificate ARN (must be in us-east-1)
---bff-alb-cert-arn <arn>             BFF ALB SSL certificate ARN
---hosted-zone-id <id>                Route53 hosted zone ID
-
-# Feature Flags
---deploy-studio-memory <boolean>     Deploy Studio Memory service (true/false)
---deploy-studio-notifications <boolean>  Deploy Studio Notifications (true/false)
---enable-bff-waf <boolean>           Enable WAF for BFF (true/false)
-
-# Frontend
---github-app-client-id <id>          GitHub App OAuth client ID
---github-app-name <name>             GitHub App name
---jira-client-id <id>                Jira OAuth client ID
-
-# Hub Integration (Step 9)
---skip-hub                           Skip Hub integration configuration
---hub-engine-execution-role <arn>    Hub Engine Execution Role ARN
---hub-consumer-role <arn>            Hub Consumer Role ARN
---hub-admin-role <arn>               Hub Admin Role ARN
---hub-appconfig-role <arn>           Hub AppConfig Role ARN
---hub-appconfig-app-id <id>          Hub AppConfig Application ID
---hub-appconfig-env-id <id>          Hub AppConfig Environment ID
---hub-appconfig-profile-id <id>      Hub AppConfig Profile ID
+# TLS/DNS
+--cloudfront-domain <domain>   CloudFront custom domain
+--cloudfront-cert-arn <arn>    CloudFront SSL certificate ARN (us-east-1)
+--bff-alb-cert-arn <arn>       BFF ALB SSL certificate ARN
+--hosted-zone-id <id>          Route53 hosted zone ID
+
+# Hub Integration
+--skip-hub                     Skip Hub integration
+--hub-engine-execution-role <arn>  Hub Engine Execution Role ARN
+--hub-consumer-role <arn>      Hub Consumer Role ARN
+--hub-admin-role <arn>         Hub Admin Role ARN
+```
+
+**Examples:**
+
+```bash
+# Fully interactive
+sembix studio create
+
+# With config file
+sembix studio create --config production.yaml
+
+# Skip Hub (add later)
+sembix studio create production --repo acme/deploy --skip-hub
+```
+
+**What it does:**
+
+1. Validates repository and environment name
+2. Walks through 9 configuration steps
+3. Creates GitHub Actions environment
+4. Sets environment variables and encrypted secrets
+
+See [complete options list](#sembix-studio-create-all-options) below for all 50+ flags.
+
+#### `sembix studio update [name]`
+
+Update an existing Sembix Studio environment.
+
+**Usage:**
+
+```bash
+sembix studio update production --repo acme/deploy
+```
+
+**Options:** Same as `create` command
+
+**Examples:**
+
+```bash
+# Add Hub integration
+sembix studio update production --repo acme/deploy \
+  --hub-engine-execution-role arn:aws:iam::123456789012:role/HubEngine
+
+# Update feature flags
+sembix studio update production --repo acme/deploy \
+  --deploy-studio-memory true
+```
+
+#### `sembix studio add-hub [name]`
+
+Add Sembix Hub integration to an existing environment (Phase 2 deployment).
+
+**Usage:**
+
+```bash
+sembix studio add-hub production --repo acme/deploy
+```
+
+**Options:**
+
+- `-r, --repo <repo>` - Target repository
+- `--hub-engine-execution-role <arn>` - Hub Engine Execution Role ARN
+- `--hub-consumer-role <arn>` - Hub Consumer Role ARN
+- `--hub-admin-role <arn>` - Hub Admin Role ARN
+- `--hub-appconfig-role <arn>` - Hub AppConfig Role ARN (optional)
+- `--hub-appconfig-app-id <id>` - Hub AppConfig Application ID (optional)
+- `--hub-appconfig-env-id <id>` - Hub AppConfig Environment ID (optional)
+- `--hub-appconfig-profile-id <id>` - Hub AppConfig Profile ID (optional)
+
+**Example:**
+
+```bash
+sembix studio add-hub production \
+  --repo acme/deploy \
+  --hub-engine-execution-role arn:aws:iam::999888777666:role/HubEngineRole \
+  --hub-consumer-role arn:aws:iam::999888777666:role/HubConsumerRole \
+  --hub-admin-role arn:aws:iam::999888777666:role/HubAdminRole
+```
+
+#### `sembix studio list [repository]`
+
+List GitHub Actions environments in a repository.
+
+**Usage:**
+
+```bash
+# List all your repositories
+sembix studio list
+
+# List environments in specific repository
+sembix studio list acme-corp/sembix-deployment
+```
+
+---
+
+### Studio API Commands
+
+Commands for authenticating with and managing Sembix Studio via API.
+
+#### `sembix login [profile]`
+
+Authenticate with Sembix Studio via Cognito OAuth.
+
+**Usage:**
+
+```bash
+# Login with default profile
+sembix login
+
+# Login with specific profile
+sembix login production
+# or
+sembix login --profile production
+```
+
+**What it does:**
+
+1. Opens browser for Cognito authentication
+2. Exchanges OAuth code for access tokens
+3. Stores tokens securely in `~/.sembix/tokens/<profile>.json`
+4. Tokens are automatically refreshed when expired
+
+#### `sembix logout [profile]`
+
+Log out from Sembix Studio by removing stored tokens.
+
+**Usage:**
+
+```bash
+# Logout from default profile
+sembix logout
+
+# Logout from specific profile
+sembix logout production
+
+# Logout from all profiles
+sembix logout --all
+```
+
+#### Profile Commands
+
+**`sembix profile list`**
+
+List all configured Studio profiles with authentication status.
+
+```bash
+sembix profile list
+```
+
+**`sembix profile show <name>`**
+
+Show detailed information for a specific profile.
+
+```bash
+sembix profile show production
+```
+
+**`sembix profile set-default <name>`**
+
+Set a profile as the default.
+
+```bash
+sembix profile set-default production
+```
+
+**`sembix profile delete <name>`**
+
+Delete a profile and its stored tokens.
+
+```bash
+sembix profile delete staging
+```
+
+**`sembix profile set-default-project <profile> <project-id>`**
+
+Set a default project for a profile (allows omitting `--project-id` in commands).
+
+```bash
+sembix profile set-default-project production proj_abc123
+```
+
+**`sembix profile get-default-project <profile>`**
+
+Get the default project for a profile.
+
+```bash
+sembix profile get-default-project production
+```
+
+**`sembix profile clear-default-project <profile>`**
+
+Clear the default project for a profile.
+
+```bash
+sembix profile clear-default-project production
+```
+
+#### Project Commands
+
+**`sembix project list`**
+
+List and search projects in your Studio instance.
+
+```bash
+# List all projects
+sembix project list
+
+# Filter by name
+sembix project list --name "Production"
+
+# With specific profile
+sembix project list --profile production
+
+# Pretty output
+sembix project list --pretty
+```
+
+**`sembix project show`**
+
+Show details for a specific project.
+
+```bash
+sembix project show --project-id proj_abc123
+```
+
+#### Workflow Commands
+
+**`sembix workflow start`**
+
+Start a workflow instance (creates a new run).
+
+```bash
+# Interactive mode (prompts for project, workflow, inputs)
+sembix workflow start
+
+# With project ID and workflow ID
+sembix workflow start --project-id proj_123 --workflow-id wf_456
+
+# With workflow name
+sembix workflow start --project-id proj_123 --workflow-name "Deploy"
+
+# With inline JSON inputs
+sembix workflow start --project-id proj_123 --workflow-id wf_456 \
+  --inputs '{"environment":"production","version":"1.2.3"}'
+
+# With inputs from file
+sembix workflow start --project-id proj_123 --workflow-id wf_456 \
+  --inputs @inputs.json
+
+# Using default project (set via profile set-default-project)
+sembix workflow start --workflow-id wf_456 --inputs '{...}'
+```
+
+**Options:**
+
+- `-p, --profile <name>` - Profile to use
+- `--project-id <id>` - Project ID (uses default if not specified)
+- `--workflow-id <id>` - Workflow ID (OR use --workflow-name)
+- `--workflow-name <name>` - Workflow name (OR use --workflow-id)
+- `--inputs <json>` - Input variables as JSON string or @file.json
+- `--workspace-id <id>` - Workspace ID (optional)
+- `--issue-id <id>` - Issue ID (optional)
+- `--no-interactive` - Disable interactive prompts
+
+**`sembix workflow list`**
+
+List workflow instances (definitions).
+
+```bash
+# List all workflows
+sembix workflow list
+
+# Filter by project
+sembix workflow list --project-id proj_123
+```
+
+**`sembix workflow run list`**
+
+List workflow runs (executions). Excludes sub-workflow runs by default.
+
+```bash
+# List all runs
+sembix workflow run list
+
+# Filter by workflow
+sembix workflow run list --workflow-id wf_456
+
+# Filter by status
+sembix workflow run list --status RUNNING
+
+# Include sub-workflow runs
+sembix workflow run list --include-subflows
+
+# Pagination
+sembix workflow run list --limit 20 --offset 10
+```
+
+**`sembix workflow run status`**
+
+Get the status of a workflow run.
+
+```bash
+# Get current status
+sembix workflow run status --workflow-id wf_456 --run-id run_789
+
+# Watch until completion (polls every 5 seconds)
+sembix workflow run status --workflow-id wf_456 --run-id run_789 --watch
+```
+
+**`sembix workflow run show`**
+
+Show full details of a specific workflow run.
+
+```bash
+# Show run details
+sembix workflow run show --workflow-id wf_456 --run-id run_789
+
+# Watch until completion
+sembix workflow run show --workflow-id wf_456 --run-id run_789 --watch
+```
+
+**`sembix workflow run stop`**
+
+Stop a running workflow.
+
+```bash
+sembix workflow run stop --project-id proj_123 \
+  --workflow-id wf_456 --run-id run_789
+```
+
+---
+
+### Global Options
+
+These options work with most commands:
+
+#### `--token <token>` or `-t <token>`
+
+Override the GitHub token from all other sources.
+
+```bash
+sembix studio create --token ghp_custom_token
+```
+
+**Credential Priority:**
+1. `--token` flag (highest)
+2. `GITHUB_TOKEN` environment variable
+3. `~/.sembix/config` (created by `sembix configure`)
+4. `.env` file (lowest)
+
+#### `--profile <name>` or `-p <name>`
+
+Specify which Studio profile to use for API commands.
+
+```bash
+sembix workflow start --profile production
+```
+
+#### `--output <format>` or `--pretty`
+
+Set output format for command results.
+
+**Values:**
+- `json` (default) - Machine-readable JSON
+- `pretty` - Pretty-printed JSON with colors
+- `text` - Human-readable text (where supported)
+
+```bash
+sembix project list --output pretty
+# or shorthand:
+sembix project list --pretty
+```
+
+#### `--help` or `-h`
+
+Display help information for a command.
+
+```bash
+sembix --help
+sembix studio --help
+sembix studio create --help
+```
+
+#### `--version` or `-V`
+
+Display the CLI version.
+
+```bash
+sembix --version
+```
+
+---
+
+### Environment Variables
+
+Configure the CLI via `.env` file or system environment variables:
+
+```env
+# GitHub Personal Access Token (required for deployment commands)
+GITHUB_TOKEN=ghp_your_token_here
+
+# Default GitHub organization (optional)
+DEFAULT_GITHUB_ORG=your-org
+
+# Studio API client credentials (for CI/CD)
+SEMBIX_CLIENT_ID=7a8b9c0d1e2f3g4h
+SEMBIX_CLIENT_SECRET=abcdef123456...
+```
+
+---
+
+### Exit Codes
+
+- `0` - Success
+- `1` - Error (validation failure, API error, user cancellation)
+
+---
+
+### <a name="sembix-studio-create-all-options"></a>`sembix studio create` - All Options
+
+For reference, here's the complete list of all 50+ CLI flags for `sembix studio create`:
+
+**General:**
+- `-t, --token <token>` - GitHub personal access token
+- `-c, --config <path>` - Path to YAML configuration file
+- `-r, --repo <repo>` - Target repository (owner/repo format)
+- `-e, --env <environment>` - Environment name
+
+**AWS Basic Configuration:**
+- `--aws-account-id <id>` - AWS Account ID (12 digits)
+- `--aws-region <region>` - AWS Region (e.g., us-east-1)
+- `--customer-role-arn <arn>` - GitHub Actions IAM role ARN
+- `--terraform-state-bucket <bucket>` - S3 bucket for Terraform state
+
+**Database:**
+- `--database-name <name>` - PostgreSQL database name
+- `--database-user <user>` - PostgreSQL database user
+
+**Networking:**
+- `--enable-vpc-endpoints <boolean>` - Enable VPC endpoints (true/false)
+- `--use-custom-networking <boolean>` - Use existing VPC (true/false)
+- `--vpc-cidr <cidr>` - VPC CIDR block (e.g., 10.0.0.0/16)
+- `--public-subnet-cidrs <json>` - Public subnet CIDRs (JSON array)
+- `--private-subnet-cidrs <json>` - Private subnet CIDRs (JSON array)
+- `--az-count <count>` - Number of AZs (2 or 3)
+- `--custom-vpc-id <id>` - Existing VPC ID
+- `--custom-public-subnet-ids <ids>` - Existing public subnet IDs (comma-separated)
+- `--custom-private-subnet-ids <ids>` - Existing private subnet IDs (comma-separated)
+
+**Security - Security Groups:**
+- `--use-custom-security-groups <boolean>` - Use custom security groups (true/false)
+- `--sg-workflow-engine <id>` - Workflow Engine security group ID
+- `--sg-aurora <id>` - Aurora database security group ID
+- `--sg-rds-proxy <id>` - RDS Proxy security group ID
+- `--sg-bff-ecs <id>` - BFF ECS service security group ID
+- `--sg-bastion <id>` - Bastion host security group ID
+- `--sg-bff-alb <id>` - BFF ALB security group ID
+
+**Security - IAM Roles:**
+- `--use-custom-iam-roles <boolean>` - Use custom IAM roles (true/false)
+- `--iam-workflow-engine-exec <arn>` - Workflow Engine execution role ARN
+- `--iam-workflow-engine-task <arn>` - Workflow Engine task role ARN
+- `--iam-bff-ecs-exec <arn>` - BFF ECS task execution role ARN
+- `--iam-bff-ecs-task <arn>` - BFF ECS task role ARN
+- `--iam-rds-proxy <arn>` - RDS Proxy role ARN
+- `--iam-studio-memory <arn>` - Studio Memory role ARN
+- `--iam-studio-notification <arn>` - Studio Notification role ARN
+
+**TLS/DNS:**
+- `--cloudfront-domain <domain>` - CloudFront custom domain
+- `--cloudfront-cert-arn <arn>` - CloudFront SSL certificate ARN (must be in us-east-1)
+- `--bff-alb-cert-arn <arn>` - BFF ALB SSL certificate ARN
+- `--hosted-zone-id <id>` - Route53 hosted zone ID
+
+**Feature Flags:**
+- `--deploy-studio-memory <boolean>` - Deploy Studio Memory service (true/false)
+- `--deploy-studio-notifications <boolean>` - Deploy Studio Notifications (true/false)
+- `--enable-bff-waf <boolean>` - Enable WAF for BFF (true/false)
+
+**Frontend:**
+- `--github-app-client-id <id>` - GitHub App OAuth client ID
+- `--github-app-name <name>` - GitHub App name
+- `--jira-client-id <id>` - Jira OAuth client ID
+
+**Hub Integration (Step 9):**
+- `--skip-hub` - Skip Hub integration configuration
+- `--hub-engine-execution-role <arn>` - Hub Engine Execution Role ARN
+- `--hub-consumer-role <arn>` - Hub Consumer Role ARN
+- `--hub-admin-role <arn>` - Hub Admin Role ARN
+- `--hub-appconfig-role <arn>` - Hub AppConfig Role ARN
+- `--hub-appconfig-app-id <id>` - Hub AppConfig Application ID
+- `--hub-appconfig-env-id <id>` - Hub AppConfig Environment ID
+- `--hub-appconfig-profile-id <id>` - Hub AppConfig Profile ID
+
+---
+
+## Usage Examples
+
+Real-world examples showing different ways to use the CLI.
+
+### Basic Usage Patterns
+
+#### 1. Fully Interactive (Beginner-Friendly)
+
+Perfect for first-time users:
+
+```bash
+sembix studio create
+```
+
+**What happens:**
+- Prompts for repository selection
+- Prompts for environment name
+- Walks through all 9 configuration steps with explanations
+- Creates environment with all settings
+
+#### 2. Specify Repository and Environment
+
+Fast setup when you know both values:
+
+```bash
+sembix studio create production --repo acme-corp/sembix-deployment
+```
+
+**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
+
+#### 3. Using Config Files
+
+For repeatable, version-controlled setups:
+
+```bash
+# Create environment from config file
+sembix studio create --config production.yaml
+
+# Override specific values
+sembix studio create --config base.yaml \
+  --env custom-name \
+  --aws-account-id 123456789012
+```
+
+### Common Workflows
+
+#### Workflow 1: First-Time Setup (Learning Mode)
+
+```bash
+# Step 1: Configure credentials
+sembix configure
+
+# Step 2: Create environment interactively
+sembix studio create
+
+# Follow all prompts, read explanations...
+
+# Step 3: Deploy via GitHub Actions
+# Go to https://github.com/owner/repo/actions
+# Run deployment workflow
+# Copy Hub role ARNs from output
+
+# Step 4: Add Hub integration
+sembix studio add-hub
+
+# Select same repository and environment
+# Enter Hub role ARNs
+```
+
+#### Workflow 2: Experienced User (Fast Mode)
+
+```bash
+# Create with known values
+sembix studio create prod --repo acme/deploy
+
+# Answer remaining prompts
+# ... deployment happens in GitHub Actions ...
+
+# Add Hub with known values
+sembix studio add-hub prod --repo acme/deploy
+
+# Enter Hub role ARNs
+```
+
+#### Workflow 3: CI/CD / Automation
+
+For scripts and automation:
+
+```bash
+#!/bin/bash
+
+REPO="acme-corp/sembix-deployment"
+ENV="client-${CLIENT_NAME}-production"
+
+# Create environment (with config file)
+sembix studio create "${ENV}" \
+  --repo "${REPO}" \
+  --config base-config.yaml \
+  --token "${GITHUB_TOKEN}"
+
+# Later, after deployment...
+sembix studio add-hub "${ENV}" \
+  --repo "${REPO}" \
+  --token "${GITHUB_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
+```
+
+### Profile Management Examples
+
+#### Working with Multiple Studio Instances
+
+```bash
+# Configure multiple profiles
+sembix configure  # Profile name: production
+sembix configure  # Profile name: staging
+
+# Set default profile
+sembix profile set-default production
+
+# Set default projects for each profile
+sembix profile set-default-project production proj_prod_123
+sembix profile set-default-project staging proj_stage_456
+
+# List all profiles
+sembix profile list
+
+# Login to each profile
+sembix login production
+sembix login staging
+
+# Use different profiles for different workflows
+sembix workflow start --profile production --workflow-id wf_456
+sembix workflow start --profile staging --workflow-id wf_789
+```
+
+### 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
+```
+
+**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 update
+```
+
+#### Authentication Errors (Studio API)
+
+```bash
+# Error: Token expired
+$ sembix workflow start
+✗ Authentication required. Please run: sembix login
+```
+
+**Solution:**
+
+```bash
+sembix login --profile production
+```
+
+### Workflow Execution Patterns
+
+#### Start and Monitor a Workflow
+
+```bash
+# Start workflow and capture run ID
+RUN_ID=$(sembix workflow start \
+  --project-id proj_123 \
+  --workflow-id wf_456 \
+  --inputs '{"env":"production"}' \
+  | grep "Run ID" | awk '{print $3}')
+
+# Watch until completion
+sembix workflow run status \
+  --workflow-id wf_456 \
+  --run-id $RUN_ID \
+  --watch
+```
+
+#### List Recent Failures
+
+```bash
+sembix workflow run list \
+  --status FAILED \
+  --limit 10
+```
+
+#### Monitor Specific Workflow
+
+```bash
+sembix workflow run list \
+  --workflow-id wf_456 \
+  --status RUNNING
+```
+
+#### Using Workflow Inputs from Files
+
+```bash
+# Create inputs.json
+cat > inputs.json <<EOF
+{
+  "environment": "production",
+  "version": "1.2.3",
+  "config": {
+    "debug": false,
+    "replicas": 3
+  }
+}
+EOF
+
+# Use file in workflow start
+sembix workflow start \
+  --project-id proj_123 \
+  --workflow-id wf_456 \
+  --inputs @inputs.json
+```
+
+### 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 `~/.sembix/config` via `sembix configure`
+- Keep environment names lowercase with hyphens
+- Use config files for version-controlled setups
+- Set default projects per profile for faster workflow execution
+- Use `--pretty` for human-readable output
+- Use `--watch` to monitor long-running workflows
+
+#### ❌ DON'T
+
+- Don't use uppercase in environment names
+- Don't use spaces or special characters
+- Don't share your GitHub token or client credentials
+- Don't create environments without verifying repo access first
+- Don't forget to run deployment between create and add-hub
+- Don't commit sensitive credentials to git
+- Don't use production credentials in development
+
+### CI/CD Integration Examples
+
+#### GitHub Actions
+
+```yaml
+name: Deploy via Sembix
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Install Sembix CLI
+        run: npm install -g @sembix/cli
+
+      - name: Start Deployment Workflow
+        env:
+          SEMBIX_CLIENT_ID: ${{ secrets.SEMBIX_M2M_CLIENT_ID }}
+          SEMBIX_CLIENT_SECRET: ${{ secrets.SEMBIX_M2M_CLIENT_SECRET }}
+        run: |
+          sembix workflow start \
+            --profile production \
+            --project-id ${{ vars.PROJECT_ID }} \
+            --workflow-id ${{ vars.WORKFLOW_ID }} \
+            --inputs '{"version":"${{ github.sha }}"}'
+```
+
+#### GitLab CI
+
+```yaml
+deploy:
+  image: node:20
+  script:
+    - npm install -g @sembix/cli
+    - |
+      sembix workflow start \
+        --profile production \
+        --project-id ${PROJECT_ID} \
+        --workflow-id ${WORKFLOW_ID} \
+        --inputs "{\"version\":\"${CI_COMMIT_SHA}\"}"
+  variables:
+    SEMBIX_CLIENT_ID: ${M2M_CLIENT_ID}
+    SEMBIX_CLIENT_SECRET: ${M2M_CLIENT_SECRET}
+```
+
+### Output Formatting Examples
+
+```bash
+# JSON output (default) - for scripts/automation
+sembix project list --output json
+
+# Pretty JSON - for human reading
+sembix project list --output pretty
+# or shorthand:
+sembix project list --pretty
+
+# Text output - for terminal display
+sembix project list --output text
+```
+
+### Quick Reference Cheat Sheet
+
+```bash
+# GitHub Deployment
+sembix configure                              # First-time setup
+sembix studio create                          # Interactive create
+sembix studio create prod --repo owner/repo   # Quick create
+sembix studio add-hub prod --repo owner/repo  # Add Hub integration
+sembix studio list owner/repo                 # List environments
+
+# Studio API
+sembix configure                              # Configure profile
+sembix login                                  # Authenticate
+sembix profile list                           # List profiles
+sembix profile set-default-project prod proj_123  # Set default project
+
+# Projects & Workflows
+sembix project list                           # List projects
+sembix workflow start                         # Start workflow (interactive)
+sembix workflow run list                      # List workflow runs
+sembix workflow run status --workflow-id wf_456 --run-id run_789 --watch
+
+# Troubleshooting
+sembix --version                              # Check CLI version
+sembix studio list owner/repo                 # Verify repo access
+sembix profile list                           # Check profile status
+sembix login --profile production             # Re-authenticate
+```
+
+## Studio CLI
+
+The Sembix CLI now supports direct integration with Sembix Studio instances for workflow execution and management.
+
+### Studio Configuration
+
+Configure a Studio profile to connect to a Sembix Studio instance using the unified configure command:
+
+```bash
+sembix configure
+```
+
+This interactive command will first prompt for GitHub credentials, then optionally prompt you to configure a Studio profile with:
+- **Profile name** (default: "default")
+- **Studio API URL** (e.g., https://studio.example.com)
+- **Cognito User Pool ID** (e.g., us-east-1_ABC123)
+- **Cognito Client ID**
+- **Cognito Region**
+- **Cognito Domain** (e.g., https://auth.example.com)
+
+### Authentication
+
+The Sembix CLI supports two authentication methods:
+1. **Browser-based OAuth** - For developers on local machines
+2. **Client Credentials** - For CI/CD pipelines and automated workflows
+
+#### Local Development (Browser-based OAuth)
+
+Authenticate with a Studio instance using browser-based OAuth:
+
+```bash
+# Login to default profile
+sembix login
+
+# Login to specific profile
+sembix login --profile production
+
+# Logout from profile
+sembix logout --profile production
+
+# Logout from all profiles
+sembix logout --all
+```
+
+**What happens during login:**
+1. Opens your default browser to Cognito hosted UI
+2. You authenticate with your Studio credentials
+3. Tokens are securely stored in `~/.sembix/tokens/<profile>.json`
+4. Tokens are automatically refreshed when expired
+
+#### CI/CD Pipelines (Client Credentials)
+
+For automated workflows, use OAuth 2.0 Client Credentials flow:
+
+**Prerequisites:**
+- Obtain M2M (machine-to-machine) client credentials from your administrator:
+  - Client ID (e.g., `7a8b9c0d1e2f3g4h`)
+  - Client Secret (keep secure!)
+  - Required OAuth scopes:
+    - `sembix-api/projects.read` - List projects
+    - `sembix-api/workflows.read` - View workflows and runs
+    - `sembix-api/workflows.execute` - Start/stop workflows
+
+**Setup:**
+
+1. **Add credentials to your CI/CD secrets:**
+
+   GitHub Actions:
+   ```yaml
+   # In repository settings → Secrets and variables → Actions
+   SEMBIX_CLIENT_ID=7a8b9c0d1e2f3g4h5i6j7k8l
+   SEMBIX_CLIENT_SECRET=abcdef123456...
+   ```
+
+   GitLab CI:
+   ```yaml
+   # In repository settings → CI/CD → Variables
+   SEMBIX_CLIENT_ID=7a8b9c0d1e2f3g4h5i6j7k8l
+   SEMBIX_CLIENT_SECRET=abcdef123456...
+   ```
+
+2. **Use in your workflow:**
+
+   ```yaml
+   - name: Start workflow
+     env:
+       SEMBIX_CLIENT_ID: ${{ secrets.SEMBIX_M2M_CLIENT_ID }}
+       SEMBIX_CLIENT_SECRET: ${{ secrets.SEMBIX_M2M_CLIENT_SECRET }}
+     run: |
+       sembix workflow start \
+         --project-id abc123 \
+         --workflow-id def456 \
+         --inputs '{"key": "value"}'
+   ```
+
+**How it works:**
+- The CLI automatically detects `SEMBIX_CLIENT_ID` and `SEMBIX_CLIENT_SECRET` environment variables
+- Authenticates using OAuth 2.0 Client Credentials flow
+- No browser or interactive login needed
+- Tokens obtained on-demand (not stored)
+
+**Testing credentials locally:**
+```bash
+export SEMBIX_CLIENT_ID="your-client-id"
+export SEMBIX_CLIENT_SECRET="your-client-secret"
+
+# Verify credentials work
+sembix login
+# Output: "Client credentials detected... Client credentials are valid!"
+```
+
+**Security best practices:**
+- Never commit credentials to git
+- Use CI/CD secret management (GitHub Secrets, AWS Secrets Manager, etc.)
+- Rotate client secrets regularly (every 90 days recommended)
+- Use separate credentials for different environments (dev, staging, prod)
+
+See the [CI/CD Setup Guide](./docs/CI-CD-SETUP.md) for complete examples and troubleshooting.
+
+### Profile Management
+
+Manage Studio profiles:
+
+```bash
+# List all profiles
+sembix profile list
+
+# Show profile details
+sembix profile show production
+
+# Set default profile
+sembix profile set-default production
+
+# Delete profile
+sembix profile delete staging
+```
+
+**Profile list output:**
+```
+  Sembix Studio Profiles
+
+  Name         API URL                      Auth Status
+  ──────────────────────────────────────────────────────
+* default      https://studio.example.com   ✓ Authenticated
+  production   https://prod.example.com     ✗ Not authenticated
+  staging      https://staging.example.com  ✓ Authenticated
+
+* = default profile
+```
+
+### Profile Project Defaults
+
+Set default projects for profiles to avoid specifying `--project-id` repeatedly.
+
+**Set default project:**
+```bash
+sembix profile set-default-project <profile> <project-id>
+
+# Example
+sembix profile set-default-project production proj_abc123
+```
+
+**Get default project:**
+```bash
+sembix profile get-default-project <profile>
+
+# Example
+sembix profile get-default-project production
+# Output: proj_abc123
 ```
 
-**Examples:**
+**Clear default project:**
+```bash
+sembix profile clear-default-project <profile>
+
+# Example
+sembix profile clear-default-project production
+```
 
+**Usage with workflow commands:**
 ```bash
-# Interactive mode (prompts for everything)
-sembix studio create
+# Set default project
+sembix profile set-default-project production proj_abc123
 
-# Specify environment name
-sembix studio create production
+# Now you can omit --project-id
+sembix workflow start --workflow-id wf_456 --inputs '{...}'
+# Uses proj_abc123 automatically
+```
 
-# With repository
-sembix studio create production --repo acme/deploy
+### Project Management
 
-# Using config file
-sembix studio create --config production.yaml
+List and view projects in your Studio instance.
 
-# Config file with overrides
-sembix studio create --config base.yaml \
-  --env client-abc-production \
-  --aws-account-id 123456789012
+**List all projects:**
+```bash
+# List all projects
+sembix project list
 
-# Skip Hub integration (add later)
-sembix studio create production --repo acme/deploy --skip-hub
+# Filter by name
+sembix project list --name "My Project"
 
-# Fully automated with all flags
-sembix studio create production \
-  --repo acme/deploy \
-  --aws-account-id 123456789012 \
-  --aws-region us-east-1 \
-  --customer-role-arn arn:aws:iam::123456789012:role/Deploy \
-  --terraform-state-bucket my-tf-state \
-  --database-name sembix_studio \
-  --database-user sembix_studio_user \
-  --cloudfront-domain studio.acme.com \
-  --cloudfront-cert-arn arn:aws:acm:us-east-1:123456789012:certificate/abc \
-  --bff-alb-cert-arn arn:aws:acm:us-east-1:123456789012:certificate/def \
-  --hosted-zone-id Z1234567890ABC \
-  --github-app-client-id Iv1.0123456789abcdef \
-  --github-app-name sembix-studio-app \
-  --jira-client-id abc123def456
+# Filter by IDs
+sembix project list --ids "proj_123,proj_456"
+
+# With specific profile
+sembix project list --profile production
 ```
 
-**What it does:**
+**Show project details:**
+```bash
+sembix project show --project-id proj_abc123
 
-1. Validates repository and environment name
-2. Walks through 9 configuration steps (or uses provided config):
-   - Repository selection
-   - Basic AWS configuration
-   - Database configuration
-   - Networking (VPC, subnets)
-   - Security (security groups, IAM roles, KMS)
-   - DNS & TLS (CloudFront, ALB certificates)
-   - Feature flags (Memory, Notifications, WAF)
-   - Frontend configuration (GitHub App, Jira)
-   - **Hub integration (optional)**
-3. Creates GitHub Actions environment
-4. Sets environment variables and encrypted secrets
-5. Provides next steps for deployment
+# With specific profile
+sembix project show --project-id proj_abc123 --profile production
+```
+
+**Output:**
+```json
+{
+  "projectId": "proj_abc123",
+  "name": "My Project",
+  "description": "Project description",
+  "state": "ACTIVE",
+  "createdAt": "2024-01-15T10:00:00Z",
+  "workflowPackConfigured": true
+}
+```
 
-### `sembix studio update`
+### Workflow Operations
 
-Update an existing Sembix Studio environment.
+Execute and manage workflows:
+
+#### Start a Workflow
+
+```bash
+# Interactive mode (prompts for project, workflow, and inputs)
+sembix workflow start
+
+# With project ID and workflow ID
+sembix workflow start --project-id abc123 --workflow-id def456
+
+# With workflow name instead of ID
+sembix workflow start --project-id abc123 --workflow-name "Deploy to Production"
+
+# Start with inline JSON inputs
+sembix workflow start --project-id abc123 --workflow-id def456 --inputs '{"key": "value"}'
 
-**Syntax:**
+# Start with inputs from file
+sembix workflow start --project-id abc123 --workflow-id def456 --inputs @inputs.json
+
+# Non-interactive mode (skip prompts)
+sembix workflow start --project-id abc123 --workflow-id def456 --no-interactive
+
+# Using default project (set via profile set-default-project)
+sembix workflow start --workflow-id def456 --inputs '{...}'
+
+# Start with workspace and issue context
+sembix workflow start \
+  --project-id abc123 \
+  --workflow-id def456 \
+  --workspace-id ws-789 \
+  --issue-id issue-101 \
+  --inputs '{"param": "value"}'
+
+# Use specific profile
+sembix workflow start \
+  --profile production \
+  --project-id abc123 \
+  --workflow-id def456 \
+  --inputs '{"key": "value"}'
+```
+
+**Example inputs.json:**
+```json
+{
+  "inputVariables": {
+    "repositoryUrl": "https://github.com/acme/repo",
+    "branch": "main"
+  },
+  "workspaceId": "ws-123",
+  "workspaceName": "My Workspace",
+  "issueId": "issue-456",
+  "issueKey": "PROJ-123"
+}
+```
+
+#### Check Workflow Status
 
 ```bash
-sembix studio update [environment-name] [options]
+# Get current status
+sembix workflow run status --workflow-id wf_456 --run-id run_789
+
+# Watch workflow until completion (polls every 5 seconds)
+sembix workflow run status --workflow-id wf_456 --run-id run_789 --watch
 ```
 
-**Options:** Same as `create` command
+**Status output:**
+```
+  Workflow Run Status
+
+  Run ID:       run-789
+  Workflow ID:  def456
+  Status:       RUNNING
+  Progress:     45%
+  Created:      2024-01-15 10:30:00
+  Creator:      user-123
+```
 
-**Examples:**
+#### List Workflow Runs
 
 ```bash
-# Interactive update (re-prompts for all config)
-sembix studio update production --repo acme/deploy
+# List workflow instances (definitions)
+sembix workflow list
 
-# Add Hub integration to existing environment
-sembix studio update production --repo acme/deploy \
-  --hub-engine-execution-role arn:aws:iam::123456789012:role/HubEngine \
-  --hub-consumer-role arn:aws:iam::123456789012:role/HubConsumer \
-  --hub-admin-role arn:aws:iam::123456789012:role/HubAdmin
+# Filter by project
+sembix workflow list --project-id proj_123
 
-# Update specific fields only
-sembix studio update production --repo acme/deploy \
-  --deploy-studio-memory true \
-  --enable-bff-waf true
+# Filter by template IDs
+sembix workflow list --workflow-template-ids "tmpl_1,tmpl_2"
 
-# Update via config file
-sembix studio update --config production-updates.yaml
+# Show workflow instance details
+sembix workflow show --project-id proj_123 --workflow-id wf_456
 
-# Update database credentials
-sembix studio update production --repo acme/deploy \
-  --database-name new_db_name \
-  --database-user new_db_user
-```
+# List workflow runs (executions) - excludes subflows by default
+sembix workflow run list
 
-**What it does:**
+# Filter by workflow
+sembix workflow run list --workflow-id wf_456
 
-- Validates environment exists
-- Updates only the fields you provide (partial updates)
-- Interactive mode re-collects all configuration
-- Preserves existing settings for fields not specified
+# Filter by project
+sembix workflow run list --project-id proj_123
 
-### `sembix studio list`
+# Filter by status
+sembix workflow run list --status RUNNING
 
-List GitHub Actions environments in a repository.
+# Include sub-workflow runs
+sembix workflow run list --include-subflows
+
+# Filter to top-level runs only
+sembix workflow run list --parent-id NULL
+
+# Pagination
+sembix workflow run list --limit 20 --offset 10
+
+# Show specific run details
+sembix workflow run show --workflow-id wf_456 --run-id run_789
+
+# Watch run details until completion
+sembix workflow run show --workflow-id wf_456 --run-id run_789 --watch
+```
+
+**List output:**
+```
+  Workflow Runs
 
-**Syntax:**
+  Run ID    Workflow ID  Status      Progress  Created
+  ────────────────────────────────────────────────────────
+  run-789   def456       RUNNING     45%       2 hours ago
+  run-788   def456       COMPLETED   100%      1 day ago
+  run-787   abc123       FAILED      30%       2 days ago
+
+  Showing 1-3 of 15 results
+```
+
+#### Stop a Workflow Run
 
 ```bash
-sembix studio list [repository] [options]
+sembix workflow run stop --project-id proj_123 --workflow-id wf_456 --run-id run_789
 ```
 
-**Examples:**
+### Common Workflow Patterns
 
+**1. Start and monitor a workflow:**
 ```bash
-# List all your repositories
-sembix studio list
+# Start workflow and capture run ID
+RUN_ID=$(sembix workflow start \
+  --project-id abc123 \
+  --workflow-id def456 \
+  --inputs '{"key": "value"}' \
+  | grep "Run ID" | awk '{print $3}')
+
+# Watch until completion
+sembix workflow run status \
+  --workflow-id def456 \
+  --run-id $RUN_ID \
+  --watch
+```
 
-# List environments in specific repository
-sembix studio list acme-corp/sembix-deployment
+**2. List recent failures:**
+```bash
+sembix workflow run list \
+  --status FAILED \
+  --limit 10
+```
 
-# With custom token
-sembix studio list acme/deploy --token ghp_custom_token
+**3. Monitor specific workflow:**
+```bash
+sembix workflow run list \
+  --workflow-id def456 \
+  --status RUNNING
 ```
 
-### `sembix studio add-hub`
+### Output Formatting
 
-Add Sembix Hub integration to an existing Studio environment. **This is typically used in Phase 2 of the deployment process** after receiving Hub role ARNs from Sembix support.
+Control output format for all commands using global flags.
+
+**Available formats:**
+- `json` (default) - Machine-readable JSON output
+- `pretty` - Pretty-printed JSON with colors and indentation
+- `text` - Human-readable text output (where applicable)
+
+**Usage:**
 
-**Syntax:**
 ```bash
-sembix studio add-hub [environment] [options]
+# JSON output (default)
+sembix workflow run list --workflow-id wf_456
+
+# Pretty-printed JSON
+sembix workflow run list --workflow-id wf_456 --output pretty
+# or shorthand:
+sembix workflow run list --workflow-id wf_456 --pretty
+
+# Text output
+sembix project list --output text
 ```
 
-**Options:**
-- `-r, --repo <repo>` - Target repository (owner/repo format)
-- `-e, --env <environment>` - Environment name (alternative to positional argument)
-- `--hub-engine-execution-role <arn>` - Hub Engine Execution Role ARN (from Sembix support)
-- `--hub-consumer-role <arn>` - Hub Consumer Role ARN (from Sembix support)
-- `--hub-admin-role <arn>` - Hub Admin Role ARN (from Sembix support)
-- `--hub-appconfig-role <arn>` - Hub AppConfig Role ARN (from Sembix support)
-- `--hub-appconfig-app-id <id>` - Hub AppConfig Application ID (from Sembix support)
-- `--hub-appconfig-env-id <id>` - Hub AppConfig Environment ID (from Sembix support)
-- `--hub-appconfig-profile-id <id>` - Hub AppConfig Profile ID (from Sembix support)
+**Examples:**
 
-**Example:**
 ```bash
-# Interactive mode (prompts for ARNs)
-sembix studio add-hub production --repo acme/deploy
+# JSON (default) - for scripts/automation
+$ sembix project show --project-id proj_123
+{"projectId":"proj_123","name":"My Project","state":"ACTIVE",...}
+
+# Pretty JSON - for human reading
+$ sembix project show --project-id proj_123 --pretty
+{
+  "projectId": "proj_123",
+  "name": "My Project",
+  "state": "ACTIVE",
+  ...
+}
 
-# With CLI flags (using ARNs from Sembix support)
-sembix studio add-hub production \
-  --repo acme/deploy \
-  --hub-engine-execution-role arn:aws:iam::999888777666:role/HubEngineRole \
-  --hub-consumer-role arn:aws:iam::999888777666:role/HubConsumerRole \
-  --hub-admin-role arn:aws:iam::999888777666:role/HubAdminRole \
-  --hub-appconfig-role arn:aws:iam::999888777666:role/HubAppConfigRole \
-  --hub-appconfig-app-id abc123 \
-  --hub-appconfig-env-id def456 \
-  --hub-appconfig-profile-id ghi789
+# Text - for terminal display
+$ sembix project list --output text
+Projects:
+  1. My Project (proj_123) - ACTIVE
+  2. Another Project (proj_456) - ACTIVE
 ```
 
-**When to use this command:**
+**Global flags:**
+- `--output <format>` - Set output format: json, pretty, or text
+- `--pretty` - Shorthand for `--output pretty`
+
+### Error Handling
+
+**Authentication errors:**
+```bash
+# If you see "Authentication required" or "Token expired"
+sembix login --profile production
+```
 
-- **Phase 2 deployment** (recommended): After completing Phase 1 bootstrap deployment and receiving Hub ARNs from Sembix support
-- **Alternative**: Hub integration can also be added during initial environment creation (Step 9 of `create`) if you already have the Hub ARNs
-- **Updates**: Use the `update` command to modify existing Hub configuration
+**Profile not found:**
+```bash
+# Configure the profile first
+sembix configure
+# Choose to configure Studio profile with name: production
+```
 
-**Important:** The Hub role ARNs are provided by Sembix support after they configure the Hub to trust your AWS account. Do not use this command until you have received these ARNs.
+**Invalid inputs:**
+```bash
+# Validate your JSON syntax
+cat inputs.json | jq .
+```
 
 ## Workflow
 
@@ -851,61 +2134,438 @@ studio
 
 ## Troubleshooting
 
-### "GitHub token is required"
+Comprehensive troubleshooting guide for common issues.
+
+### Authentication Issues
 
-If you see this error, you need to configure your GitHub token. The easiest method is:
+#### "GitHub token is required"
 
+**Error:**
+```
+✗ 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
+```
+
+**Solution:**
 ```bash
+# Easiest method (recommended)
 sembix configure
+
+# Alternative: Create .env file
+echo "GITHUB_TOKEN=ghp_your_token_here" > .env
+
+# Or pass token directly
+sembix studio create --token ghp_your_token_here
 ```
 
-Alternatively, create a `.env` file:
+#### "Failed to create environment: Bad credentials"
 
-```env
-GITHUB_TOKEN=ghp_your_token_here
+**Cause:** GitHub token is invalid or missing required scopes.
+
+**Solution:**
+1. Create a new Personal Access Token at: https://github.com/settings/tokens
+2. Required scopes:
+   - ✅ `repo` (all sub-scopes)
+   - ✅ `workflow`
+3. Update your configuration:
+```bash
+sembix configure
 ```
 
-Or pass the token directly via CLI:
+#### "Authentication required" (Studio API)
+
+**Error:**
+```
+✗ Authentication required. Please run: sembix login
+```
 
+**Solution:**
 ```bash
-sembix studio create --token ghp_your_token_here
+# Login with default profile
+sembix login
+
+# Or specific profile
+sembix login --profile production
+
+# If tokens expired, re-authenticate
+sembix logout --profile production
+sembix login --profile production
 ```
 
-### "Failed to create environment: Bad credentials"
+#### Browser did not open (Studio login)
+
+**Error:** Browser window doesn't open during `sembix login`
 
-Your GitHub token may be invalid or missing required scopes. Create a new token with `repo` and `workflow` scopes.
+**Solution:**
+1. Manually copy the URL displayed in terminal
+2. Open it in your browser
+3. Complete authentication within 5 minutes
+4. If timeout occurs, run `sembix login` again
 
-### "Failed to encrypt secret"
+### GitHub API Issues
 
-The `libsodium-wrappers` library is required for encrypting GitHub secrets. Make sure dependencies are installed:
+#### "No repositories found"
 
+**Cause:** GitHub token doesn't have access to repositories.
+
+**Solution:**
+1. Verify token has `repo` scope
+2. Check organization access:
+   - GitHub Settings → Personal Access Tokens → Your token → Configure SSO (if applicable)
+   - Click "Authorize" for your organization
+3. Verify repository name is correct (use `owner/repo` format)
+
+#### "Repository not found or not accessible"
+
+**Error:**
+```
+✗ Repository 'owner/repo' not found or not accessible.
+```
+
+**Solution:**
 ```bash
-npm install
+# Verify repository name format
+sembix studio list  # Lists accessible repositories
+
+# Check token permissions
+# Go to: https://github.com/settings/tokens
+# Ensure 'repo' scope is enabled
+
+# If using organization repos, configure SSO
+```
+
+#### "Environment already exists"
+
+**Error:**
+```
+✗ Environment 'production' already exists in owner/repo
+```
+
+**Solution:**
+```bash
+# Option 1: Update existing environment
+sembix studio update production --repo owner/repo
+
+# Option 2: Use different environment name
+sembix studio create production-v2 --repo owner/repo
+
+# Option 3: Delete and recreate (not recommended)
+# Delete manually in GitHub UI, then:
+sembix studio create production --repo owner/repo
+```
+
+### Studio API Issues
+
+#### "Profile not found"
+
+**Error:**
+```
+✗ Profile 'production' not found
+```
+
+**Solution:**
+```bash
+# List configured profiles
+sembix profile list
+
+# Configure the profile
+sembix configure
+# Choose to configure Studio profile with name: production
+```
+
+#### "Cannot connect to Studio API"
+
+**Error:** Connection refused or timeout errors
+
+**Solution:**
+1. Verify API URL in profile configuration:
+```bash
+sembix profile show production
+```
+
+2. Check network connectivity:
+```bash
+curl https://studio.example.com/health
+```
+
+3. Reconfigure profile if URL is incorrect:
+```bash
+sembix configure
+# Use same profile name to update
 ```
 
-### "No repositories found"
+#### "401 Unauthorized"
 
-Make sure your GitHub token has access to the repositories you want to manage. Check the token's permissions and organization access.
+**Error:** API returns 401 error
 
-### "Invalid YAML syntax"
+**Solution:**
+```bash
+# Token expired - re-authenticate
+sembix login --profile production
+
+# If still failing, logout and login again
+sembix logout --profile production
+sembix login --profile production
+```
+
+#### "Workflow not found"
+
+**Error:**
+```
+✗ Workflow 'wf_456' not found
+```
+
+**Solution:**
+```bash
+# List available workflows
+sembix workflow list --project-id proj_123
+
+# Or use interactive mode to search
+sembix workflow start
+```
+
+### Common Errors
+
+#### "Failed to encrypt secret"
+
+**Error:** libsodium encryption error
+
+**Solution:**
+```bash
+# Reinstall dependencies
+rm -rf node_modules
+npm install
+
+# If still failing, try:
+npm install libsodium-wrappers --save
+```
+
+#### "Invalid YAML syntax"
 
-When using config files, validate your YAML syntax:
+**Error:** When using config files
 
+**Solution:**
 ```bash
-# Use a YAML validator
+# Validate YAML syntax
 npm install -g js-yaml
 js-yaml config.yaml
+
+# Or use online validator: yamllint.com
+
+# Common issues:
+# - Incorrect indentation (use spaces, not tabs)
+# - Missing quotes around special characters
+# - Malformed arrays/objects
+```
+
+#### "Invalid environment name"
+
+**Error:**
+```
+✗ Invalid environment name. Must be lowercase letters, numbers, and hyphens (min 3 chars).
 ```
 
-### "Environment already exists"
+**Rules:**
+- Lowercase letters only
+- Numbers allowed
+- Hyphens allowed (not at start/end)
+- No spaces or special characters
+- Minimum 3 characters
+
+**Valid examples:**
+- `production`
+- `client-abc-staging`
+- `dev-environment-2`
+
+**Invalid examples:**
+- `Production` (uppercase)
+- `My Environment` (spaces)
+- `prod_env` (underscores)
 
-Use the `update` command instead of `create`:
+#### "Permission denied writing tokens"
 
+**Error:** Cannot write to ~/.sembix directory
+
+**Solution:**
 ```bash
-sembix studio update production --repo acme/deploy
+# Check directory permissions
+ls -la ~/.sembix
+
+# Fix permissions
+chmod 700 ~/.sembix
+chmod 600 ~/.sembix/tokens/*
+
+# If directory doesn't exist
+mkdir -p ~/.sembix/tokens
+chmod 700 ~/.sembix
 ```
 
-Or delete the environment in GitHub and recreate it.
+#### "Invalid input format" (Workflows)
+
+**Error:** Workflow input validation failed
+
+**Solution:**
+```bash
+# Validate JSON syntax
+echo '{"key":"value"}' | jq .
+
+# Use file for complex inputs
+cat inputs.json | jq .  # Validate
+sembix workflow start --project-id proj_123 --workflow-id wf_456 --inputs @inputs.json
+
+# Check required vs optional inputs
+sembix workflow template show --project-id proj_123 --workflow-id wf_456
+```
+
+### Configuration Issues
+
+#### Config file not found
+
+**Error:**
+```
+✗ Config file not found: production.yaml
+```
+
+**Solution:**
+```bash
+# Use absolute path
+sembix studio create --config /full/path/to/production.yaml
+
+# Or relative to current directory
+sembix studio create --config ./configs/production.yaml
+
+# Verify file exists
+ls -la production.yaml
+```
+
+#### Config validation failed
+
+**Error:** Config file validation errors
+
+**Solution:**
+1. Check config.example.yaml for correct format
+2. Ensure all required fields are present
+3. Validate data types (strings, booleans, numbers)
+4. Check ARN formats match AWS patterns
+5. Verify CIDR blocks are valid
+
+### Build/Installation Issues
+
+#### "Cannot find module"
+
+**Error:** Module resolution errors
+
+**Solution:**
+```bash
+# Reinstall dependencies
+rm -rf node_modules package-lock.json
+npm install
+
+# Rebuild TypeScript
+npm run build
+
+# If still failing, check Node version
+node --version  # Should be 20 or higher
+```
+
+#### "Command not found: sembix"
+
+**Error:** CLI not in PATH after installation
+
+**Solution:**
+```bash
+# Global install
+npm install -g @sembix/cli
+
+# Verify installation
+which sembix
+sembix --version
+
+# If using npm link (development)
+npm link
+
+# Add npm global bin to PATH if needed
+export PATH="$PATH:$(npm config get prefix)/bin"
+```
+
+### CI/CD Issues
+
+#### Client credentials not working
+
+**Error:** SEMBIX_CLIENT_ID and SEMBIX_CLIENT_SECRET set but authentication fails
+
+**Solution:**
+1. Verify credentials are correct (no extra spaces)
+2. Check client has required scopes:
+   - `sembix-api/projects.read`
+   - `sembix-api/workflows.read`
+   - `sembix-api/workflows.execute`
+3. Test credentials locally:
+```bash
+export SEMBIX_CLIENT_ID="your-client-id"
+export SEMBIX_CLIENT_SECRET="your-client-secret"
+sembix login  # Should show "Client credentials detected..."
+```
+
+#### Environment variables not recognized
+
+**Error:** CI/CD pipeline can't find credentials
+
+**Solution:**
+```bash
+# GitHub Actions: Use secrets
+env:
+  SEMBIX_CLIENT_ID: ${{ secrets.SEMBIX_M2M_CLIENT_ID }}
+  SEMBIX_CLIENT_SECRET: ${{ secrets.SEMBIX_M2M_CLIENT_SECRET }}
+
+# GitLab CI: Use variables
+variables:
+  SEMBIX_CLIENT_ID: ${M2M_CLIENT_ID}
+  SEMBIX_CLIENT_SECRET: ${M2M_CLIENT_SECRET}
+
+# Verify secrets are set in CI/CD settings
+```
+
+### Getting Help
+
+If you encounter an issue not covered here:
+
+1. **Check version:**
+   ```bash
+   sembix --version
+   ```
+
+2. **Enable verbose output:**
+   ```bash
+   sembix studio create --verbose  # If supported
+   ```
+
+3. **Check logs:**
+   - GitHub token permissions
+   - API endpoint reachability
+   - Config file syntax
+
+4. **Common debugging steps:**
+   ```bash
+   # Verify GitHub access
+   sembix studio list
+
+   # Check profile status
+   sembix profile list
+
+   # Test authentication
+   sembix login --profile production
+
+   # Validate config file
+   js-yaml config.yaml
+   ```
+
+5. **Contact support:**
+   - Provide error message
+   - Include CLI version
+   - Share (sanitized) config file if applicable
 
 ## Advanced Topics
 
@@ -965,7 +2625,11 @@ For issues or questions, contact the Sembix team or open an issue in the reposit
 
 ## See Also
 
-- [QUICKSTART.md](./QUICKSTART.md) - 5-minute quick start guide
-- [USAGE-EXAMPLES.md](./USAGE-EXAMPLES.md) - Real-world usage examples
-- [COMMANDS.md](./COMMANDS.md) - Detailed command reference
-- [config.example.yaml](./config.example.yaml) - Complete config file example
+For additional detailed documentation, see these files included in the package:
+
+- [QUICKSTART.md](./QUICKSTART.md) - Step-by-step quick start guide with detailed walkthroughs
+- [USAGE-EXAMPLES.md](./USAGE-EXAMPLES.md) - Comprehensive real-world usage examples and patterns
+- [COMMANDS.md](./COMMANDS.md) - Complete command reference with all options and examples
+- [config.example.yaml](./config.example.yaml) - Fully annotated configuration file example
+
+**Note:** After installing the package (`npm install -g @sembix/cli`), these files are available in your global node_modules directory. The README provides comprehensive documentation, but these supplementary files offer additional depth and examples.