@sembix/cli 1.2.1 → 1.4.0

package/COMMANDS.md

@@ -0,0 +1,1522 @@
+# Sembix CLI - Command Reference
+
+Complete reference for all Sembix CLI commands.
+
+## Command Structure
+
+```
+sembix <product> <action> [options] [arguments]
+```
+
+- **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)
+
+---
+
+## Global Commands
+
+### `sembix configure`
+
+Configure Sembix CLI credentials and settings interactively.
+
+**Usage:**
+
+```bash
+sembix configure
+```
+
+**What it does:**
+
+1. Prompts for your GitHub Personal Access Token
+2. Prompts for your default GitHub organization (optional)
+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)
+- Updating your GitHub token
+- Changing your default organization
+- Adding or updating Studio profiles for API access
+
+**Output:**
+
+```
+Configuration saved to ~/.sembix/config
+```
+
+After running this command, you won't need to specify `--token` or set `GITHUB_TOKEN` for future commands. If you configured a Studio profile, you can run `sembix login` to authenticate.
+
+---
+
+## Studio Commands
+
+All commands for managing Sembix Studio deployments.
+
+---
+
+## Studio CLI 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
+
+# Using --profile flag
+sembix login --profile staging
+```
+
+**Options:**
+
+- `[profile]` - Profile name to use (default: "default")
+- `-p, --profile <name>` - Alternative way to specify profile
+
+**What it does:**
+
+1. Loads the specified profile configuration
+2. Opens your browser for Cognito authentication
+3. Starts a local callback server to receive the OAuth code
+4. Exchanges the code for access tokens
+5. Stores tokens securely in `~/.sembix/tokens/<profile>.json`
+
+**When to use:**
+
+- After configuring a Studio profile with `sembix configure`
+- When tokens have expired
+- Before running workflow commands
+
+**Output:**
+
+```bash
+$ sembix login production
+━━━ Sembix Studio Authentication ━━━
+Authenticating with profile: production
+Starting authentication flow...
+A browser window will open for you to sign in.
+
+✓ Authentication successful!
+  Token expires: 12/15/2024, 3:45:00 PM
+```
+
+---
+
+### `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
+```
+
+**Options:**
+
+- `[profile]` - Profile name to logout from (default: "default")
+- `-p, --profile <name>` - Alternative way to specify profile
+- `--all` - Remove tokens for all profiles
+
+**What it does:**
+
+1. Removes stored authentication tokens for the specified profile
+2. Requires re-authentication with `sembix login` for future API calls
+
+**Examples:**
+
+```bash
+$ sembix logout production
+✓ Logged out from profile: production
+
+$ sembix logout --all
+✓ Logged out from all profiles
+```
+
+---
+
+### `sembix profile list`
+
+List all configured Studio profiles.
+
+**Usage:**
+
+```bash
+sembix profile list
+```
+
+**What it does:**
+
+- Displays all configured profiles
+- Shows API URL for each profile
+- Indicates which profile is the default (marked with `*`)
+- Shows authentication status (whether tokens exist)
+
+**Output:**
+
+```bash
+$ sembix profile list
+━━━ Configured Profiles ━━━
+
+* default
+  API URL: https://studio.example.com
+  Authenticated: Yes
+
+  production
+  API URL: https://prod.studio.example.com
+  Authenticated: Yes
+
+  staging
+  API URL: https://staging.studio.example.com
+  Authenticated: No
+```
+
+---
+
+### `sembix profile show <name>`
+
+Show detailed information for a specific profile.
+
+**Usage:**
+
+```bash
+sembix profile show production
+```
+
+**What it does:**
+
+- Displays full configuration for the specified profile
+- Shows API URL, Cognito configuration
+- Does not display sensitive token values
+
+**Output:**
+
+```bash
+$ sembix profile show production
+━━━ Profile: production ━━━
+
+API URL: https://prod.studio.example.com
+Cognito User Pool ID: us-east-1_ABC123
+Cognito Client ID: abc123def456
+Cognito Region: us-east-1
+Cognito Domain: https://auth.example.com
+Authenticated: Yes
+Token Expires: 12/15/2024, 3:45:00 PM
+```
+
+---
+
+### `sembix profile delete <name>`
+
+Delete a profile and its stored tokens.
+
+**Usage:**
+
+```bash
+sembix profile delete staging
+```
+
+**What it does:**
+
+1. Prompts for confirmation
+2. Removes profile configuration from `~/.sembix/config`
+3. Removes stored tokens from `~/.sembix/tokens/<profile>.json`
+
+**Output:**
+
+```bash
+$ sembix profile delete staging
+? Are you sure you want to delete profile 'staging'? Yes
+✓ Profile 'staging' deleted successfully
+```
+
+---
+
+### `sembix profile set-default <name>`
+
+Set a profile as the default.
+
+**Usage:**
+
+```bash
+sembix profile set-default production
+```
+
+**What it does:**
+
+- Sets the specified profile as the default
+- Default profile is used when no `--profile` flag is provided
+
+**Output:**
+
+```bash
+$ sembix profile set-default production
+✓ Default profile set to: production
+```
+
+---
+
+### `sembix profile set-default-project <profile> <project-id>`
+
+Set a default project for a profile.
+
+**Usage:**
+
+```bash
+sembix profile set-default-project production proj_abc123
+```
+
+**What it does:**
+
+- Associates a default project ID with the specified profile
+- Allows omitting `--project-id` in workflow commands
+- Stored in profile configuration
+
+**Output:**
+
+```bash
+$ sembix profile set-default-project production proj_abc123
+✓ Default project set for profile 'production': proj_abc123
+```
+
+---
+
+### `sembix profile get-default-project <profile>`
+
+Get the default project for a profile.
+
+**Usage:**
+
+```bash
+sembix profile get-default-project production
+```
+
+**Output:**
+
+```bash
+$ sembix profile get-default-project production
+proj_abc123
+```
+
+---
+
+### `sembix profile clear-default-project <profile>`
+
+Clear the default project for a profile.
+
+**Usage:**
+
+```bash
+sembix profile clear-default-project production
+```
+
+**Output:**
+
+```bash
+$ sembix profile clear-default-project production
+✓ Default project cleared for profile 'production'
+```
+
+---
+
+## Project Commands
+
+Commands for managing Studio projects.
+
+---
+
+### `sembix project list`
+
+List and search projects in your Studio instance.
+
+**Usage:**
+
+```bash
+# List all projects
+sembix project list
+
+# Filter by name
+sembix project list --name "My Project"
+
+# Filter by IDs
+sembix project list --ids "proj_123,proj_456"
+
+# With specific profile
+sembix project list --profile production
+
+# With output formatting
+sembix project list --output pretty
+```
+
+**Options:**
+
+- `-p, --profile <name>` - Studio profile to use
+- `--name <name>` - Filter by project name (partial match)
+- `--ids <ids>` - Filter by comma-separated project IDs
+- `--output <format>` - Output format: json, pretty, or text
+- `--pretty` - Pretty-print JSON output
+
+**What it does:**
+
+1. Authenticates with Studio API
+2. Queries projects with specified filters
+3. Returns list of matching projects
+
+**Output (JSON):**
+
+```json
+{
+  "message": "Projects retrieved successfully",
+  "items": [
+    {
+      "projectId": "proj_abc123",
+      "name": "My Project",
+      "description": "Project description",
+      "state": "ACTIVE",
+      "createdAt": "2024-01-15T10:00:00Z",
+      "workflowPackConfigured": true
+    }
+  ]
+}
+```
+
+**Output (Pretty):**
+
+```
+Projects:
+  1. My Project (proj_abc123)
+     State: ACTIVE
+     Created: 2024-01-15T10:00:00Z
+     Workflow Pack: Configured
+```
+
+---
+
+### `sembix project show`
+
+Show details for a specific project.
+
+**Usage:**
+
+```bash
+sembix project show --project-id proj_abc123
+
+# With specific profile
+sembix project show --project-id proj_abc123 --profile production
+```
+
+**Options:**
+
+- `--project-id <id>` - **Required** - Project ID
+- `-p, --profile <name>` - Studio profile to use
+- `--output <format>` - Output format: json, pretty, or text
+- `--pretty` - Pretty-print JSON output
+
+**What it does:**
+
+1. Authenticates with Studio API
+2. Fetches detailed project information
+3. Returns project details
+
+**Output:**
+
+```json
+{
+  "projectId": "proj_abc123",
+  "name": "My Project",
+  "description": "Detailed project description",
+  "state": "ACTIVE",
+  "createdAt": "2024-01-15T10:00:00Z",
+  "updatedAt": "2024-01-20T15:30:00Z",
+  "createdBy": "user_123",
+  "updatedBy": "user_456",
+  "workflowPackConfigured": true,
+  "providerConfiguration": {...},
+  "issueTrackerIntegration": {...}
+}
+```
+
+---
+
+## Workflow Commands
+
+Commands for managing workflow instances (definitions) and workflow runs (executions).
+
+---
+
+### `sembix workflow list`
+
+List workflow instances (definitions) in your Studio instance.
+
+**Usage:**
+
+```bash
+# List all workflows
+sembix workflow list
+
+# Filter by project
+sembix workflow list --project-id proj_123
+
+# Filter by template IDs
+sembix workflow list --workflow-template-ids "tmpl_1,tmpl_2"
+
+# Filter by parent workflow
+sembix workflow list --parent-workflow-id wf_parent
+
+# With specific profile
+sembix workflow list --profile production
+```
+
+**Options:**
+
+- `-p, --profile <name>` - Profile to use
+- `--project-id <id>` - Filter by project ID
+- `--workflow-template-ids <ids>` - Filter by comma-separated template IDs
+- `--parent-workflow-id <id>` - Filter by parent workflow ID
+- `--output <format>` - Output format: json, pretty, or text
+- `--pretty` - Pretty-print JSON output
+
+**Output:**
+
+```json
+{
+  "workflows": [
+    {
+      "workflowId": "wf_abc123",
+      "projectId": "proj_123",
+      "name": "Deploy to Production",
+      "state": "ACTIVE",
+      "workflowTemplateId": "tmpl_deploy",
+      "createdAt": "2024-01-15T10:00:00Z"
+    }
+  ]
+}
+```
+
+---
+
+### `sembix workflow show`
+
+Show details for a specific workflow instance.
+
+**Usage:**
+
+```bash
+sembix workflow show --project-id proj_123 --workflow-id wf_456
+```
+
+**Options:**
+
+- `-p, --profile <name>` - Profile to use
+- `--project-id <id>` - **Required** - Project ID
+- `--workflow-id <id>` - **Required** - Workflow ID
+- `--output <format>` - Output format: json, pretty, or text
+- `--pretty` - Pretty-print JSON output
+
+---
+
+### `sembix workflow start`
+
+Start a workflow instance (creates a new run).
+
+**Usage:**
+
+```bash
+# Interactive mode (prompts for project, workflow, and inputs)
+sembix workflow start
+
+# With project ID and workflow ID
+sembix workflow start --project-id proj_123 --workflow-id wf_456
+
+# With workflow name instead of ID
+sembix workflow start --project-id proj_123 --workflow-name "Deploy to Production"
+
+# With inline JSON inputs
+sembix workflow start --project-id proj_123 --workflow-id wf_456 --inputs '{"key":"value"}'
+
+# With inputs from file
+sembix workflow start --project-id proj_123 --workflow-id wf_456 --inputs @inputs.json
+
+# Non-interactive mode (skip prompts)
+sembix workflow start --project-id proj_123 --workflow-id wf_456 --no-interactive
+
+# 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 (optional in interactive mode - uses default or prompts)
+- `--workflow-id <id>` - Workflow ID (use this OR --workflow-name, optional in interactive mode)
+- `--workflow-name <name>` - Workflow name (use this OR --workflow-id, optional in interactive mode)
+- `--inputs <json>` - Input variables as JSON string or @file.json
+- `--workspace-id <id>` - Workspace ID
+- `--workspace-name <name>` - Workspace name
+- `--issue-id <id>` - Issue ID
+- `--issue-key <key>` - Issue key
+- `--no-interactive` - Disable interactive prompts for inputs
+- `--output <format>` - Output format: json, pretty, or text
+- `--pretty` - Pretty-print JSON output
+
+**Interactive Mode:**
+
+When `--project-id` or `--workflow-id` are omitted, the CLI enters interactive mode:
+
+1. **Project Selection:**
+   - If no default project is set, prompts to select from available projects
+   - If default project is set, uses it automatically
+
+2. **Workflow Selection:**
+   - Prompts to select from workflows in the chosen project
+   - Can search by name
+
+3. **Input Configuration:**
+   - Prompts for each required input variable
+   - Shows data type and description for each input
+   - Validates input values
+
+**What it does:**
+
+1. Validates authentication (refreshes tokens if needed)
+2. Parses input configuration from JSON string or file
+3. Calls Studio API to start workflow execution
+4. Returns run ID and task ARN
+
+**Examples:**
+
+```bash
+# Start workflow with inline JSON inputs
+$ sembix workflow start --project-id proj_123 --workflow-id wf_456 --inputs '{"environment":"production","version":"1.2.3"}'
+━━━ Start Workflow Execution ━━━
+✓ Workflow started successfully!
+  Run ID: run_789abc
+  Task ARN: arn:aws:ecs:us-east-1:123456789012:task/cluster/abc123
+
+# Start workflow with inputs from file
+$ cat inputs.json
+{
+  "environment": "staging",
+  "version": "1.2.3",
+  "config": {
+    "debug": true
+  }
+}
+
+$ sembix workflow start --project-id proj_123 --workflow-id wf_456 --inputs @inputs.json
+✓ Workflow started successfully!
+  Run ID: run_xyz789
+```
+
+---
+
+### `sembix workflow template show`
+
+Show workflow template details.
+
+**Usage:**
+
+```bash
+# Using template ID
+sembix workflow template show --project-id proj_123 --template-id tmpl_deploy
+
+# Using workflow ID (fetches template from workflow)
+sembix workflow template show --project-id proj_123 --workflow-id wf_456
+```
+
+**Options:**
+
+- `-p, --profile <name>` - Profile to use
+- `--project-id <id>` - **Required** - Project ID
+- `--template-id <id>` - Template ID (use this OR --workflow-id)
+- `--workflow-id <id>` - Workflow ID (use this OR --template-id)
+- `--output <format>` - Output format: json, pretty, or text
+- `--pretty` - Pretty-print JSON output
+
+---
+
+## Workflow Run Commands
+
+Commands for managing workflow runs (executions).
+
+---
+
+### `sembix workflow run list`
+
+List workflow runs (excludes sub-workflow runs by default).
+
+**Usage:**
+
+```bash
+# List all runs
+sembix workflow run list
+
+# Filter by workflow
+sembix workflow run list --workflow-id wf_456
+
+# Filter by project
+sembix workflow run list --project-id proj_123
+
+# Filter by template
+sembix workflow run list --workflow-template-id tmpl_deploy
+
+# Filter by status
+sembix workflow run list --status RUNNING
+
+# 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
+
+# Filter by workspace
+sembix workflow run list --workspace-id ws_123
+
+# Filter by issue
+sembix workflow run list --issue-key PROJ-123
+```
+
+**Options:**
+
+- `-p, --profile <name>` - Profile to use
+- `--workflow-id <id>` - Filter by workflow ID
+- `--project-id <id>` - Filter by project ID
+- `--workflow-template-id <id>` - Filter by workflow template ID
+- `--parent-id <id>` - Filter by parent workflow run ID (use "NULL" for top-level runs only)
+- `--include-subflows` - Include sub-workflow runs in results (default: excluded)
+- `--status <status>` - Filter by status (PENDING, IN_PROGRESS, COMPLETED, FAILED, CANCELLED)
+- `--limit <number>` - Number of results (default: 10)
+- `--offset <number>` - Offset for pagination (default: 0)
+- `--sort-by <field>` - Sort field
+- `--sort-order <order>` - Sort order (ASC|DESC)
+- `--current-user` - Filter to current user runs
+- `--workspace-id <id>` - Filter by workspace ID
+- `--workspace-name <name>` - Filter by workspace name
+- `--issue-id <id>` - Filter by issue ID
+- `--issue-key <key>` - Filter by issue key
+- `--output <format>` - Output format: json, pretty, or text
+- `--pretty` - Pretty-print JSON output
+
+**Output:**
+
+```json
+{
+  "items": [
+    {
+      "workflowId": "wf_456",
+      "projectId": "proj_123",
+      "workflowTemplateId": "tmpl_deploy",
+      "parentId": null,
+      "sortBy": "createdAt",
+      "sortOrder": "DESC",
+      "limit": 10,
+      "offset": 0,
+      "runs": [
+        {
+          "runId": "run_xyz789",
+          "workflowId": "wf_456",
+          "name": "Deploy to Production",
+          "status": "IN_PROGRESS",
+          "progress": 45,
+          "createdAt": "2024-01-15T14:30:00Z",
+          "creatorId": "user_123"
+        }
+      ],
+      "totalCount": 15
+    }
+  ]
+}
+```
+
+---
+
+### `sembix workflow run show`
+
+Show details of a specific workflow run.
+
+**Usage:**
+
+```bash
+# Show run details
+sembix workflow run show --workflow-id wf_456 --run-id run_xyz789
+
+# Watch run details until completion
+sembix workflow run show --workflow-id wf_456 --run-id run_xyz789 --watch
+```
+
+**Options:**
+
+- `-p, --profile <name>` - Profile to use
+- `--workflow-id <id>` - **Required** - Workflow ID
+- `--run-id <id>` - **Required** - Run ID
+- `-w, --watch` - Watch run details until completion
+- `--output <format>` - Output format: json, pretty, or text
+- `--pretty` - Pretty-print JSON output
+
+**Output:**
+
+```json
+{
+  "run": {
+    "runId": "run_xyz789",
+    "workflowId": "wf_456",
+    "projectId": "proj_123",
+    "name": "Deploy to Production",
+    "status": "IN_PROGRESS",
+    "progress": 45,
+    "createdAt": "2024-01-15T14:30:00Z",
+    "startedAt": "2024-01-15T14:30:05Z",
+    "creatorId": "user_123",
+    "steps": [
+      {
+        "stepId": "step_1",
+        "name": "Initialize",
+        "state": "Complete",
+        "events": [...]
+      },
+      {
+        "stepId": "step_2",
+        "name": "Deploy",
+        "state": "Pending",
+        "events": []
+      }
+    ],
+    "currentStepId": "step_2",
+    "events": [...]
+  }
+}
+```
+
+---
+
+### `sembix workflow run status`
+
+Get the status of a workflow run (simplified view).
+
+**Usage:**
+
+```bash
+# Get current status
+sembix workflow run status --workflow-id wf_456 --run-id run_xyz789
+
+# Watch status until completion
+sembix workflow run status --workflow-id wf_456 --run-id run_xyz789 --watch
+```
+
+**Options:**
+
+- `-p, --profile <name>` - Profile to use
+- `--workflow-id <id>` - Workflow ID (optional if run-id is unique)
+- `--run-id <id>` - Run ID (optional if workflow-id is provided)
+- `-w, --watch` - Watch status until completion
+- `--output <format>` - Output format: json, pretty, or text
+- `--pretty` - Pretty-print JSON output
+
+**Note:** This command provides a simplified status view. Use `sembix workflow run show` for full run details.
+
+---
+
+### `sembix workflow run stop`
+
+Stop a running workflow.
+
+**Usage:**
+
+```bash
+sembix workflow run stop --project-id proj_123 --workflow-id wf_456 --run-id run_xyz789
+```
+
+**Options:**
+
+- `-p, --profile <name>` - Profile to use
+- `--project-id <id>` - Project ID (optional if workflow-id is unique)
+- `--workflow-id <id>` - Workflow ID (optional if run-id is unique)
+- `--run-id <id>` - Run ID (optional if workflow-id is provided)
+- `--output <format>` - Output format: json, pretty, or text
+- `--pretty` - Pretty-print JSON output
+
+**Output:**
+
+```json
+{
+  "message": "Workflow run stopped successfully",
+  "runId": "run_xyz789"
+}
+```
+
+### `sembix studio create [name]`
+
+Create a new Sembix Studio environment with full interactive configuration.
+
+**Usage:**
+
+```bash
+# Interactive mode (recommended for first-time users)
+sembix studio create
+
+# With environment name
+sembix studio create acme-production
+
+# With environment name and repository
+sembix studio create acme-production --repo acme-corp/sembix-deployment
+
+# With custom GitHub token
+sembix studio create --token ghp_your_custom_token
+```
+
+**Options:**
+
+- `[name]` - Optional environment name (will prompt if not provided)
+- `-r, --repo <repo>` - Target repository in `owner/repo` format
+- `-t, --token <token>` - GitHub personal access token (overrides `.env`)
+
+**What it does:**
+
+1. Guides you through 8 configuration steps:
+   - Repository selection
+   - Basic configuration (AWS, Terraform)
+   - Database settings
+   - Networking (VPC, subnets)
+   - Security (IAM roles, security groups, KMS)
+   - DNS & TLS (domains, certificates)
+   - Feature flags (Memory, Notifications, WAF)
+   - Frontend configuration (GitHub App, Jira)
+
+2. Creates GitHub Actions environment
+3. Sets environment variables (public values)
+4. Creates environment secrets (encrypted sensitive values)
+
+**Output:**
+
+- Links to GitHub Actions for deployment
+- Instructions for next steps (run deployment, add Hub integration)
+
+**Examples:**
+
+```bash
+# Fully interactive
+$ sembix studio create
+━━━ Step 1: Repository Selection ━━━
+? Select your deployment repository: acme-corp/sembix-deployment
+? Environment name: acme-production
+...
+
+# Quick setup with name provided
+$ sembix studio create staging-env
+━━━ Step 1: Repository Selection ━━━
+✓ Using environment name: staging-env
+? Select your deployment repository: ...
+
+# Fully non-interactive (skip repo and name prompts)
+$ sembix studio create prod --repo acme-corp/deployments
+✓ Using repository: acme-corp/deployments
+✓ Using environment name: prod
+━━━ Step 2: Basic Configuration ━━━
+...
+```
+
+---
+
+### `sembix studio add-hub [name]`
+
+Add Sembix Hub cross-account roles and AppConfig integration to an existing environment.
+
+**Usage:**
+
+```bash
+# Interactive mode
+sembix studio add-hub
+
+# With environment name
+sembix studio add-hub acme-production
+
+# With environment name and repository
+sembix studio add-hub acme-production --repo acme-corp/sembix-deployment
+
+# With custom GitHub token
+sembix studio add-hub --token ghp_your_custom_token
+```
+
+**Options:**
+
+- `[name]` - Optional environment name (will prompt if not provided)
+- `-r, --repo <repo>` - Target repository in `owner/repo` format
+- `-t, --token <token>` - GitHub personal access token (overrides `.env`)
+
+**When to use:**
+
+After you've:
+1. Created an environment with `sembix studio create`
+2. Run your first deployment via GitHub Actions
+3. Received Hub role ARNs from the deployment output
+
+**What it does:**
+
+1. Selects repository and environment (or uses provided values)
+2. Prompts for Hub role ARNs:
+   - Hub Engine Execution Role ARN
+   - Hub Consumer Role ARN
+   - Hub Admin Role ARN
+3. Optionally prompts for AppConfig configuration:
+   - AppConfig Role ARN
+   - AppConfig Application ID
+   - AppConfig Environment ID
+   - AppConfig Profile ID
+4. Updates environment secrets with Hub configuration
+
+**Output:**
+
+- Confirmation that Hub integration was added
+- Link to GitHub Actions for redeployment with Hub enabled
+
+**Examples:**
+
+```bash
+# Interactive - select everything
+$ sembix studio add-hub
+━━━ Repository & Environment Selection ━━━
+? Select deployment repository: acme-corp/sembix-deployment
+? Select environment to update: acme-production
+━━━ Sembix Hub Cross-Account Roles ━━━
+? Hub Engine Execution Role ARN: arn:aws:iam::...
+
+# Quick - provide environment name
+$ sembix studio add-hub acme-production
+━━━ Repository & Environment Selection ━━━
+✓ Using environment: acme-production
+? Select deployment repository: ...
+
+# Fully specified
+$ sembix studio add-hub prod --repo acme-corp/deployments
+✓ Using repository: acme-corp/deployments
+✓ Using environment: prod
+━━━ Sembix Hub Cross-Account Roles ━━━
+...
+```
+
+---
+
+### `sembix studio list [repository]`
+
+List all Studio environments in a repository, or list all your repositories.
+
+**Usage:**
+
+```bash
+# List all your repositories
+sembix studio list
+
+# List environments in a specific repository
+sembix studio list acme-corp/sembix-deployment
+
+# With custom GitHub token
+sembix studio list --token ghp_your_custom_token
+```
+
+**Options:**
+
+- `[repository]` - Optional repository in `owner/repo` format
+- `-t, --token <token>` - GitHub personal access token (overrides `.env`)
+
+**What it does:**
+
+**Without repository argument:**
+- Lists all repositories accessible with your GitHub token
+- Provides tip to specify a repository to see its environments
+
+**With repository argument:**
+- Lists all GitHub Actions environments in the specified repository
+- Shows environment names and URLs
+- Provides helpful tips if no environments found
+
+**Examples:**
+
+```bash
+# List all repositories
+$ sembix studio list
+
+┌─────────────────────────────────────────┐
+│                                         │
+│       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. sembix-partners/client-xyz
+
+Run: sembix studio list <repository> to see environments
+
+# List environments in a repository
+$ sembix studio list acme-corp/sembix-deployment
+
+  Environments in acme-corp/sembix-deployment
+
+━━━ Environments ━━━
+
+  1. acme-production
+     https://github.com/acme-corp/sembix-deployment/settings/environments/acme-production
+
+  2. acme-staging
+     https://github.com/acme-corp/sembix-deployment/settings/environments/acme-staging
+
+# No environments found
+$ sembix studio list new-repo/empty
+
+  Environments in new-repo/empty
+
+⚠ No environments found in new-repo/empty
+
+💡 Create your first environment:
+   sembix studio create
+```
+
+---
+
+## Global Options
+
+These options work with any command:
+
+### `--output <format>`
+
+Set output format for command results.
+
+**Values:**
+- `json` (default) - Machine-readable JSON
+- `pretty` - Pretty-printed JSON with colors
+- `text` - Human-readable text (where supported)
+
+**Usage:**
+```bash
+sembix project list --output pretty
+sembix workflow run list --output json
+```
+
+### `--pretty`
+
+Shorthand for `--output pretty`.
+
+**Usage:**
+```bash
+sembix project list --pretty
+```
+
+---
+
+### `--help` or `-h`
+
+Display help information for a command.
+
+```bash
+# Main help
+sembix --help
+
+# Studio help
+sembix studio --help
+
+# Specific command help
+sembix studio create --help
+sembix studio add-hub --help
+sembix studio list --help
+```
+
+### `--version` or `-V`
+
+Display the CLI version.
+
+```bash
+sembix --version
+# Output: 1.0.0
+```
+
+### `--token <token>` or `-t <token>`
+
+Override the GitHub token from all other sources (environment variables, `~/.sembix/config`, `.env` file).
+
+```bash
+sembix studio create --token ghp_custom_token_here
+```
+
+**Credential Priority:**
+1. `--token` flag (highest)
+2. `GITHUB_TOKEN` environment variable
+3. `~/.sembix/config` (created by `sembix configure`)
+4. `.env` file (lowest)
+
+**When to use:**
+- Testing with different GitHub accounts
+- CI/CD pipelines with different tokens
+- Temporary token for specific operation
+
+### `--profile <name>` or `-p <name>`
+
+Specify which Studio profile to use for API commands.
+
+```bash
+sembix workflow start --profile production --project-id proj_123 --workflow-id wf_456
+```
+
+**Profile Priority:**
+1. `--profile` flag (highest)
+2. Default profile set via `sembix profile set-default`
+3. "default" profile (if exists)
+
+**When to use:**
+- Working with multiple Studio instances
+- Switching between production and staging environments
+- Testing with different Studio configurations
+
+---
+
+## Environment Variables
+
+Configure the CLI via `.env` file:
+
+```env
+# Required: GitHub Personal Access Token
+GITHUB_TOKEN=ghp_your_token_here
+
+# Optional: Default GitHub organization
+DEFAULT_GITHUB_ORG=your-org
+```
+
+**GitHub Token Scopes Required:**
+- `repo` - Full control of private repositories
+- `workflow` - Update GitHub Actions workflows
+
+---
+
+## Exit Codes
+
+The CLI uses standard exit codes:
+
+- `0` - Success
+- `1` - Error (validation failure, API error, user cancellation)
+
+**Error Examples:**
+
+```bash
+$ sembix studio create
+✗ GITHUB_TOKEN environment variable is required
+# Exit code: 1
+
+$ sembix studio create invalid_name
+✗ Invalid environment name. Must be lowercase letters, numbers, and hyphens (min 3 chars).
+# Exit code: 1
+
+$ sembix studio add-hub nonexistent --repo acme/repo
+✗ Environment 'nonexistent' not found in acme/repo
+# Exit code: 1
+```
+
+---
+
+## Tips & Best Practices
+
+### 1. **Use Command Arguments for Automation**
+
+For scripts and CI/CD, provide arguments instead of relying on interactive prompts:
+
+```bash
+#!/bin/bash
+# Create environment non-interactively
+sembix studio create "${ENV_NAME}" --repo "${REPO}" --token "${GITHUB_TOKEN}"
+
+# Start workflow non-interactively
+sembix workflow start --profile production --project-id "${PROJECT_ID}" --workflow-id "${WORKFLOW_ID}" --inputs @inputs.json
+```
+
+### 2. **Start Interactive for First-Time Setup**
+
+For your first environment, use fully interactive mode to learn about all options:
+
+```bash
+sembix studio create
+# Follow all prompts and learn what each field means
+
+# For Studio API setup
+sembix configure
+# Configure GitHub credentials and Studio profile interactively
+```
+
+### 3. **List Before Creating**
+
+Check existing environments before creating new ones:
+
+```bash
+sembix studio list acme-corp/sembix-deployment
+# See what already exists, avoid duplicates
+
+# List configured profiles
+sembix profile list
+# See what Studio profiles are configured
+```
+
+### 4. **Validate Token Permissions**
+
+If you encounter errors, verify your token has correct scopes:
+
+```bash
+# GitHub Settings → Developer settings → Personal access tokens
+# Required: repo, workflow
+```
+
+### 5. **Use Profiles for Multiple Studio Instances**
+
+Configure separate profiles for different Studio environments:
+
+```bash
+# Configure production profile (interactive)
+sembix configure
+# Choose to configure Studio profile, enter profile name: production
+
+# Configure staging profile (interactive)
+sembix configure
+# Choose to configure Studio profile, enter profile name: staging
+
+# Switch between profiles
+sembix workflow list --profile production
+sembix workflow list --profile staging
+```
+
+### 6. **Use Watch Mode for Long-Running Workflows**
+
+Monitor workflow execution in real-time:
+
+```bash
+# Start workflow and get run ID
+RUN_ID=$(sembix workflow start --project-id proj_123 --workflow-id wf_456 --inputs @inputs.json | grep "Run ID" | awk '{print $3}')
+
+# Watch until completion
+sembix workflow status --workflow-id wf_456 --run-id "${RUN_ID}" --watch
+```
+
+### 7. **Store Input Variables in Files**
+
+For complex workflow inputs, use JSON 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
+```
+
+---
+
+## Workflow Examples
+
+### Complete Workflow Execution Flow
+
+```bash
+# 1. Configure Studio profile
+sembix configure
+# Choose to configure Studio profile with name: production
+
+# 2. Authenticate
+sembix login production
+
+# 3. Set default project (optional)
+sembix profile set-default-project production proj_123
+
+# 4. Start workflow (interactive mode)
+sembix workflow start
+
+# Or start with explicit parameters
+sembix workflow start \
+  --profile production \
+  --workflow-id wf_456 \
+  --inputs '{"environment":"production","version":"1.2.3"}'
+
+# Output: Run ID: run_789abc
+
+# 5. Check status
+sembix workflow run status \
+  --profile production \
+  --workflow-id wf_456 \
+  --run-id run_789abc
+
+# 6. Watch until completion
+sembix workflow run status \
+  --profile production \
+  --workflow-id wf_456 \
+  --run-id run_789abc \
+  --watch
+```
+
+### Managing Multiple Profiles
+
+```bash
+# Configure multiple profiles (interactive)
+sembix configure  # Profile name: production
+sembix configure  # Profile name: staging
+sembix configure  # Profile name: dev
+
+# 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
+sembix profile set-default-project dev proj_dev_789
+
+# List all profiles
+sembix profile list
+
+# Login to each profile
+sembix login production
+sembix login staging
+sembix login dev
+
+# Use different profiles for different workflows
+sembix workflow start --profile production --workflow-id wf_456
+sembix workflow start --profile staging --workflow-id wf_789
+```
+
+### Filtering and Searching Workflow Runs
+
+```bash
+# List all runs for a specific workflow
+sembix workflow run list --workflow-id wf_456
+
+# List failed runs
+sembix workflow run list --status FAILED
+
+# List runs for a project
+sembix workflow run list --project-id proj_123
+
+# List top-level runs only (exclude subflows)
+sembix workflow run list --parent-id NULL
+
+# Include sub-workflow runs
+sembix workflow run list --include-subflows
+
+# Paginate through results
+sembix workflow run list --limit 20 --offset 0
+sembix workflow run list --limit 20 --offset 20
+
+# Combine filters
+sembix workflow run list \
+  --workflow-id wf_456 \
+  --status COMPLETED \
+  --limit 10
+
+# Show full run details
+sembix workflow run show --workflow-id wf_456 --run-id run_789
+```
+
+### Project Management Examples
+
+```bash
+# List all projects
+sembix project list
+
+# Search projects by name
+sembix project list --name "Production"
+
+# Show project details
+sembix project show --project-id proj_123
+
+# With pretty output
+sembix project list --pretty
+```
+
+### 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
+```
+
+---
+
+## Future Commands
+
+Commands planned for future releases:
+
+```bash
+# Update existing environment
+sembix studio update <name>
+
+# Delete environment
+sembix studio delete <name>
+
+# Show environment details
+sembix studio info <name>
+
+# Validate configuration
+sembix studio validate <name>
+
+# Export configuration
+sembix studio export <name> > config.yaml
+
+# Import configuration
+sembix studio import config.yaml
+
+# Workflow templates
+sembix workflow template list
+sembix workflow template show <id>
+
+# Workflow logs
+sembix workflow logs --run-id <id>
+```
+
+---
+
+## Getting Help
+
+- **CLI Help**: `sembix --help`, `sembix studio --help`
+- **Documentation**: See `README.md` for detailed setup instructions
+- **Issues**: Report issues at https://github.com/anthropics/claude-code/issues
+
+---
+
+**Last Updated**: November 2024
+**CLI Version**: 1.0.0