@eve-horizon/cli 0.0.1

package/dist/lib/help.js

@@ -0,0 +1,938 @@
+"use strict";
+/**
+ * Progressive help system for Eve Horizon CLI.
+ *
+ * Help is available at every level:
+ * - eve --help              → top-level commands
+ * - eve profile --help      → profile subcommands
+ * - eve profile set --help  → specific usage
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HELP = void 0;
+exports.showMainHelp = showMainHelp;
+exports.showCommandHelp = showCommandHelp;
+exports.showSubcommandHelp = showSubcommandHelp;
+exports.shouldShowHelp = shouldShowHelp;
+exports.HELP = {
+    org: {
+        description: 'Manage organizations. Organizations group projects and users.',
+        usage: 'eve org <subcommand> [options]',
+        subcommands: {
+            list: {
+                description: 'List all organizations',
+                usage: 'eve org list [--limit N] [--offset N]',
+                options: [
+                    '--limit <n>          Number of results (default: 10)',
+                    '--offset <n>         Skip first n results',
+                    '--include-deleted    Include soft-deleted orgs',
+                ],
+            },
+            get: {
+                description: 'Get organization details',
+                usage: 'eve org get <org_id>',
+            },
+            ensure: {
+                description: 'Create org if it doesn\'t exist, or return existing',
+                usage: 'eve org ensure <name>',
+                examples: ['eve org ensure "My Company"'],
+            },
+            update: {
+                description: 'Update organization',
+                usage: 'eve org update <org_id> [--name <name>] [--deleted <bool>]',
+            },
+        },
+        examples: [
+            'eve org ensure "Acme Corp"',
+            'eve org list --limit 20',
+        ],
+    },
+    project: {
+        description: 'Manage projects. Projects link a git repo to an organization for running jobs.',
+        usage: 'eve project <subcommand> [options]',
+        subcommands: {
+            list: {
+                description: 'List projects in an organization',
+                usage: 'eve project list [--org <org_id>]',
+                options: [
+                    '--org <id>           Organization ID (uses profile default)',
+                    '--limit <n>          Number of results',
+                    '--offset <n>         Skip first n results',
+                ],
+            },
+            get: {
+                description: 'Get project details',
+                usage: 'eve project get <project_id>',
+            },
+            ensure: {
+                description: 'Create project if it doesn\'t exist, or return existing',
+                usage: 'eve project ensure --name <name> --repo-url <url> [--org <org_id>] [--branch <branch>] [--slug <slug>]',
+                options: [
+                    '--name <name>        Project name (required)',
+                    '--repo-url <url>     Git repository URL (required)',
+                    '--org <id>           Organization ID',
+                    '--branch <branch>    Default branch (default: main)',
+                    '--slug <slug>        Short memorable slug (4-8 chars, e.g., MyProj)',
+                    '--force              Re-clone repo even if project exists',
+                ],
+                examples: [
+                    'eve project ensure --name my-app --slug MyApp --repo-url https://github.com/org/repo',
+                    'eve project ensure --name my-app --repo-url file:///path/to/repo --force',
+                ],
+            },
+            update: {
+                description: 'Update project',
+                usage: 'eve project update <project_id> [--name <name>] [--deleted <bool>]',
+            },
+            sync: {
+                description: 'Sync manifest from local .eve/manifest.yaml to Eve API',
+                usage: 'eve project sync [project] [--path <manifest_path>]',
+                options: [
+                    '<project>             Project ID (uses profile default if omitted)',
+                    '--path <path>         Path to manifest (default: .eve/manifest.yaml)',
+                ],
+                examples: [
+                    'eve project sync',
+                    'eve project sync proj_xxx',
+                    'eve project sync --path ./custom-manifest.yaml',
+                ],
+            },
+        },
+    },
+    secrets: {
+        description: 'Manage secrets at project/org/user scope. Values are never returned in plaintext.',
+        usage: 'eve secrets <subcommand> [options]',
+        subcommands: {
+            set: {
+                description: 'Create or update a secret value',
+                usage: 'eve secrets set <key> <value> [--project <id>|--org <id>|--user <id>] [--type <type>]',
+                options: [
+                    '--project <id>       Project ID (uses profile default)',
+                    '--org <id>           Organization ID',
+                    '--user <id>          User ID',
+                    '--type <type>        env_var | file | github_token | ssh_key',
+                ],
+            },
+            list: {
+                description: 'List secrets (metadata only)',
+                usage: 'eve secrets list [--project <id>|--org <id>|--user <id>]',
+            },
+            show: {
+                description: 'Show a masked secret value',
+                usage: 'eve secrets show <key> [--project <id>|--org <id>|--user <id>]',
+            },
+            delete: {
+                description: 'Delete a secret',
+                usage: 'eve secrets delete <key> [--project <id>|--org <id>|--user <id>]',
+            },
+            import: {
+                description: 'Import EVE_SECRET_* entries from an env file',
+                usage: 'eve secrets import [--file <path>] [--project <id>|--org <id>|--user <id>]',
+                options: [
+                    '--file <path>        Defaults to .env',
+                ],
+            },
+        },
+        examples: [
+            'eve secrets set GITHUB_TOKEN ghp_xxx --project proj_xxx --type github_token',
+            'eve secrets show GITHUB_TOKEN --project proj_xxx',
+        ],
+    },
+    job: {
+        description: `Manage jobs. Jobs are units of work executed by AI agents against a project's repo.
+
+Phase lifecycle: idea → backlog → ready → active → review → done (or cancelled)
+Jobs default to 'ready' phase, making them immediately schedulable.`,
+        usage: 'eve job <subcommand> [options]',
+        subcommands: {
+            create: {
+                description: 'Create a new job',
+                usage: 'eve job create --project <id> --description "..." [options]',
+                options: [
+                    '--project <id>         Project ID (or use profile default)',
+                    '--description <text>   Work description/prompt (required)',
+                    '--title <text>         Title (auto-generated from description if omitted)',
+                    '--parent <id>          Parent job ID (for sub-jobs)',
+                    '--type <type>          Issue type: task, bug, feature, epic, chore (default: task)',
+                    '--priority <0-4>       Priority P0-P4 (default: 2)',
+                    '--phase <phase>        Initial phase (default: ready)',
+                    '--review <type>        Review requirement: none, human, agent (default: none)',
+                    '--labels <a,b,c>       Comma-separated labels',
+                    '--assignee <id>        Assign to agent/user',
+                    '--defer-until <date>   Hide until date (ISO 8601)',
+                    '--due-at <date>        Deadline (ISO 8601)',
+                    '',
+                    'Scheduling hints (used by scheduler when claiming):',
+                    '--harness <name>       Preferred harness, e.g., mclaude:fast',
+                    '--worker-type <type>   Worker type preference',
+                    '--permission <policy>  Permission policy: default, auto_edit, yolo',
+                    '--timeout <seconds>    Execution timeout',
+                    '',
+                    'Inline execution (for agents creating sub-jobs):',
+                    '--claim                Create and immediately claim the job',
+                    '--agent <id>           Agent ID for claim (default: $EVE_AGENT_ID)',
+                ],
+                examples: [
+                    'eve job create --description "Fix the login bug in auth.ts"',
+                    'eve job create --description "Add dark mode" --priority 1 --harness mclaude',
+                    'eve job create --parent MyProj-abc123 --description "Implement tokens" --claim',
+                ],
+            },
+            list: {
+                description: 'List jobs in a project',
+                usage: 'eve job list [--project <id>] [--phase <phase>] [--assignee <id>] [--since <time>] [--stuck]',
+                options: [
+                    '--project <id>       Project ID (or use profile default)',
+                    '--phase <phase>      Filter by phase',
+                    '--assignee <id>      Filter by assignee',
+                    '--priority <n>       Filter by priority',
+                    '--since <time>       Filter jobs created after time (e.g., "1h", "30m", "2d", or ISO timestamp)',
+                    '--stuck              Show only jobs stuck in active phase (no progress for 5+ min)',
+                    '--stuck-minutes <n>  Minutes threshold for stuck detection (default: 5)',
+                    '--limit <n>          Number of results (default: 50)',
+                    '--offset <n>         Skip first n results',
+                ],
+                examples: [
+                    'eve job list --phase active',
+                    'eve job list --since 1h',
+                    'eve job list --stuck',
+                ],
+            },
+            ready: {
+                description: 'Show schedulable jobs (ready phase, not blocked, not deferred)',
+                usage: 'eve job ready [--project <id>] [--limit <n>]',
+                options: [
+                    '--project <id>       Project ID (or use profile default)',
+                    '--limit <n>          Number of results (default: 10)',
+                ],
+            },
+            blocked: {
+                description: 'Show jobs blocked by dependencies',
+                usage: 'eve job blocked [--project <id>]',
+                options: [
+                    '--project <id>       Project ID (or use profile default)',
+                ],
+            },
+            show: {
+                description: 'Get job details',
+                usage: 'eve job show <job-id> [--verbose]',
+                options: [
+                    '--verbose            Include attempt details, exit codes, durations',
+                ],
+                examples: ['eve job show MyProj-abc123', 'eve job show MyProj-abc123 --verbose'],
+            },
+            current: {
+                description: 'Get the current job context (defaults to EVE_JOB_ID)',
+                usage: 'eve job current [<job-id>] [--json|--tree]',
+                options: [
+                    '--tree               Render job hierarchy instead of JSON',
+                ],
+                examples: ['eve job current', 'eve job current MyProj-abc123 --tree'],
+            },
+            diagnose: {
+                description: 'Comprehensive job debugging (state, attempts, timeline, logs, recommendations)',
+                usage: 'eve job diagnose <job-id>',
+                examples: ['eve job diagnose MyProj-abc123'],
+            },
+            tree: {
+                description: 'Show job hierarchy (parent + children)',
+                usage: 'eve job tree <job-id>',
+                examples: ['eve job tree MyProj-abc123'],
+            },
+            update: {
+                description: 'Update job fields',
+                usage: 'eve job update <job-id> [--phase <phase>] [--priority <n>] ...',
+                options: [
+                    '--phase <phase>       Transition phase (validated)',
+                    '--priority <n>        Set priority (0-4)',
+                    '--assignee <id>       Set assignee',
+                    '--title <text>        Update title',
+                    '--description <text>  Update description',
+                    '--labels <a,b,c>      Set labels',
+                    '--defer-until <date>  Set defer date',
+                    '--due-at <date>       Set due date',
+                    '--review <type>       Set review requirement',
+                ],
+            },
+            close: {
+                description: 'Mark job as done',
+                usage: 'eve job close <job-id> [--reason "..."]',
+                options: [
+                    '--reason <text>      Completion reason',
+                ],
+            },
+            cancel: {
+                description: 'Mark job as cancelled',
+                usage: 'eve job cancel <job-id> [--reason "..."]',
+                options: [
+                    '--reason <text>      Cancellation reason',
+                ],
+            },
+            dep: {
+                description: 'Manage job dependencies',
+                usage: 'eve job dep <add|remove|list> [args]',
+                options: [
+                    'add <from> <to>      Add dependency: from depends on to',
+                    'remove <from> <to>   Remove dependency',
+                    'list <job-id>        Show dependencies and dependents',
+                ],
+                examples: [
+                    'eve job dep add MyProj-abc123 MyProj-def456',
+                    'eve job dep list MyProj-abc123',
+                ],
+            },
+            claim: {
+                description: 'Claim a job for execution (creates attempt, transitions to active)',
+                usage: 'eve job claim <job-id> [--agent <id>] [--harness <name>]',
+                options: [
+                    '--agent <id>         Agent identifier (default: $EVE_AGENT_ID or cli-user)',
+                    '--harness <name>     Harness to use (overrides hints)',
+                    '',
+                    'NOTE: This is typically called by the scheduler or by agents creating',
+                    'sub-jobs. For normal workflows, jobs are auto-scheduled when ready.',
+                ],
+            },
+            release: {
+                description: 'Release a claimed job (ends attempt, returns to ready)',
+                usage: 'eve job release <job-id> [--agent <id>] [--reason "..."]',
+                options: [
+                    '--agent <id>         Agent identifier (default: $EVE_AGENT_ID or cli-user)',
+                    '--reason <text>      Release reason',
+                ],
+            },
+            attempts: {
+                description: 'List execution attempts for a job',
+                usage: 'eve job attempts <job-id>',
+            },
+            logs: {
+                description: 'View execution logs for a job attempt',
+                usage: 'eve job logs <job-id> [--attempt <n>] [--after <seq>]',
+                options: [
+                    '--attempt <n>        Attempt number (default: latest)',
+                    '--after <seq>        Return logs after sequence number',
+                ],
+            },
+            submit: {
+                description: 'Submit job for review',
+                usage: 'eve job submit <job-id> --summary "..."',
+                options: [
+                    '--summary <text>     Submission summary (required)',
+                    '--agent-id <id>      Agent ID (default: cli-user)',
+                ],
+            },
+            approve: {
+                description: 'Approve a job in review',
+                usage: 'eve job approve <job-id> [--comment "..."]',
+                options: [
+                    '--comment <text>     Approval comment',
+                    '--reviewer-id <id>   Reviewer ID (default: cli-user)',
+                ],
+            },
+            reject: {
+                description: 'Reject a job in review (creates new attempt)',
+                usage: 'eve job reject <job-id> --reason "..."',
+                options: [
+                    '--reason <text>      Rejection reason (required)',
+                    '--reviewer-id <id>   Reviewer ID (default: cli-user)',
+                ],
+            },
+            result: {
+                description: 'Get job execution result',
+                usage: 'eve job result <job-id> [--attempt <n>]',
+                options: [
+                    '--attempt <n>        Attempt number (default: latest)',
+                ],
+                examples: ['eve job result MyProj-abc123'],
+            },
+            wait: {
+                description: 'Wait for job completion, polling until done',
+                usage: 'eve job wait <job-id> [--timeout <seconds>] [--quiet]',
+                options: [
+                    '--timeout <seconds>  Max wait time (default: 300)',
+                    '--quiet              Suppress progress output',
+                ],
+                examples: ['eve job wait MyProj-abc123', 'eve job wait MyProj-abc123 --timeout 600'],
+            },
+            follow: {
+                description: 'Stream job logs in real-time (SSE)',
+                usage: 'eve job follow <job-id> [--raw] [--no-result]',
+                options: [
+                    '--raw                Show raw log entries',
+                    '--no-result          Don\'t fetch final result when done',
+                ],
+                examples: ['eve job follow MyProj-abc123'],
+            },
+        },
+        examples: [
+            'eve job create --description "Fix the bug in auth.ts"',
+            'eve job list --phase ready',
+            'eve job show MyProj-abc123',
+            'eve job close MyProj-abc123 --reason "Completed"',
+        ],
+    },
+    harness: {
+        description: 'Inspect available harnesses, variants, and auth status.',
+        usage: 'eve harness <subcommand> [options]',
+        subcommands: {
+            list: {
+                description: 'List available harnesses',
+                usage: 'eve harness list',
+            },
+            get: {
+                description: 'Get harness details and auth requirements',
+                usage: 'eve harness get <name>',
+                examples: ['eve harness get mclaude'],
+            },
+        },
+        examples: ['eve harness list', 'eve harness get mclaude'],
+    },
+    profile: {
+        description: `Manage CLI profiles. Profiles store defaults (API URL, org, project) so you don't
+have to specify them on every command. Useful when working with multiple environments.`,
+        usage: 'eve profile <subcommand> [options]',
+        subcommands: {
+            list: {
+                description: 'List all profiles',
+                usage: 'eve profile list',
+            },
+            show: {
+                description: 'Show profile details',
+                usage: 'eve profile show [name]',
+                examples: ['eve profile show', 'eve profile show prod'],
+            },
+            use: {
+                description: 'Switch active profile',
+                usage: 'eve profile use <name>',
+                examples: ['eve profile use prod'],
+            },
+            create: {
+                description: 'Create a new profile',
+                usage: 'eve profile create <name> [--api-url <url>] [--org <id>] [--project <id>]',
+                options: [
+                    '--api-url <url>           API base URL',
+                    '--org <id>                Default organization ID',
+                    '--project <id>            Default project ID',
+                    '--harness <name>          Default harness (e.g., mclaude:fast)',
+                    '--supabase-url <url>      Supabase URL (for cloud auth)',
+                    '--supabase-anon-key <key> Supabase anon key',
+                ],
+                examples: [
+                    'eve profile create local --api-url http://localhost:4701',
+                    'eve profile create prod --api-url https://api.example.com --org org_xxx',
+                ],
+            },
+            set: {
+                description: 'Update profile settings',
+                usage: 'eve profile set [name] [--api-url <url>] [--org <id>] [--project <id>]',
+                options: [
+                    '--api-url <url>           API base URL',
+                    '--org <id>                Default organization ID',
+                    '--project <id>            Default project ID',
+                    '--harness <name>          Default harness',
+                    '--supabase-url <url>      Supabase URL',
+                    '--supabase-anon-key <key> Supabase anon key',
+                ],
+                examples: [
+                    'eve profile set --org org_xxx --project proj_yyy',
+                    'eve profile set prod --api-url https://new-api.example.com',
+                ],
+            },
+            remove: {
+                description: 'Remove a profile',
+                usage: 'eve profile remove <name>',
+            },
+        },
+        examples: [
+            'eve profile create local --api-url http://localhost:4701',
+            'eve profile use local',
+            'eve profile set --org org_xxx',
+        ],
+    },
+    auth: {
+        description: `Authenticate with Eve Horizon. Auth is optional for local development but required
+for cloud deployments. Credentials are stored per-profile.`,
+        usage: 'eve auth <subcommand> [options]',
+        subcommands: {
+            login: {
+                description: 'Login with email and password',
+                usage: 'eve auth login --email <email> --password <password>',
+                options: [
+                    '--email <email>      Email address',
+                    '--password <pass>    Password',
+                ],
+            },
+            logout: {
+                description: 'Clear stored credentials',
+                usage: 'eve auth logout',
+            },
+            status: {
+                description: 'Check authentication status',
+                usage: 'eve auth status',
+            },
+            whoami: {
+                description: 'Show current user info',
+                usage: 'eve auth whoami',
+            },
+        },
+    },
+    env: {
+        description: 'Manage environments for projects. Environments are deployment targets (staging, production, test).',
+        usage: 'eve env <subcommand> [options]',
+        subcommands: {
+            list: {
+                description: 'List environments for a project',
+                usage: 'eve env list [project]',
+                options: [
+                    '<project>             Project ID or slug (uses profile default if omitted)',
+                ],
+                examples: ['eve env list', 'eve env list proj_xxx'],
+            },
+            show: {
+                description: 'Show details of an environment',
+                usage: 'eve env show <project> <name>',
+                examples: ['eve env show proj_xxx staging', 'eve env show my-project production'],
+            },
+            create: {
+                description: 'Create an environment',
+                usage: 'eve env create <name> --type=<type> [options]',
+                options: [
+                    '<name>                Environment name (e.g., staging, production, test)',
+                    '--type <type>         Environment type: persistent or temporary (required)',
+                    '--namespace <ns>      K8s namespace (optional)',
+                    '--db-ref <ref>        Database reference (optional)',
+                    '--project <id>        Project ID (uses profile default if omitted)',
+                ],
+                examples: [
+                    'eve env create staging --type=persistent',
+                    'eve env create test --type=persistent --namespace=eve-test',
+                ],
+            },
+            deploy: {
+                description: 'Deploy to an environment',
+                usage: 'eve env deploy <project> <name> [--tag=<tag>]',
+                options: [
+                    '<project>             Project ID or slug',
+                    '<name>                Environment name (staging, production, test)',
+                    '--tag <tag>           Image tag (e.g., "local" for local images, "sha-abc" for CI)',
+                ],
+                examples: [
+                    'eve env deploy proj_xxx staging',
+                    'eve env deploy my-project test --tag local',
+                ],
+            },
+        },
+        examples: ['eve env list', 'eve env create test --type=persistent', 'eve env deploy proj_xxx staging'],
+    },
+    api: {
+        description: 'Explore project API sources and call them with Eve auth.',
+        usage: 'eve api <subcommand> [options]',
+        subcommands: {
+            list: {
+                description: 'List API sources for a project',
+                usage: 'eve api list [project] [--env <name>]',
+                options: [
+                    '<project>             Project ID (uses profile default if omitted)',
+                    '--env <name>          Environment name (optional filter)',
+                ],
+                examples: ['eve api list', 'eve api list proj_xxx --env staging'],
+            },
+            show: {
+                description: 'Show details for a single API source',
+                usage: 'eve api show <name> [project]',
+                options: ['--env <name>          Environment name (optional filter)'],
+                examples: ['eve api show app', 'eve api show app proj_xxx --env staging'],
+            },
+            spec: {
+                description: 'Show cached API spec (OpenAPI/GraphQL)',
+                usage: 'eve api spec <name> [project]',
+                options: ['--env <name>          Environment name (optional filter)'],
+                examples: ['eve api spec app', 'eve api spec app proj_xxx --env staging'],
+            },
+            refresh: {
+                description: 'Refresh cached API spec',
+                usage: 'eve api refresh <name> [project]',
+                options: ['--env <name>          Environment name (optional filter)'],
+                examples: ['eve api refresh app --env staging'],
+            },
+            examples: {
+                description: 'Print curl templates from the cached API spec',
+                usage: 'eve api examples <name> [project]',
+                options: ['--env <name>          Environment name (optional filter)'],
+                examples: ['eve api examples app', 'eve api examples app --env staging'],
+            },
+            call: {
+                description: 'Call an API endpoint with Eve auth',
+                usage: 'eve api call <name> <method> <path> [options]',
+                options: [
+                    '--project <id>       Project ID (uses profile default)',
+                    '--env <name>         Environment name (optional source)',
+                    '--json <payload>     JSON body inline or @file',
+                    '--jq <expr>          Filter JSON output with jq',
+                    '--graphql <query>    GraphQL query inline or @file',
+                    '--variables <json>   JSON variables for GraphQL query',
+                    '--token <token>      Override auth token',
+                    '--print-curl         Print curl command instead of executing',
+                ],
+                examples: [
+                    'eve api call app GET /notes --jq ".items"',
+                    'eve api call app POST /notes --json "{\"title\":\"Hello\"}"',
+                    'eve api call graphql POST /graphql --graphql "{ notes { id } }"',
+                ],
+            },
+        },
+    },
+    db: {
+        description: 'Inspect and query environment databases with Eve auth + RLS.',
+        usage: 'eve db <subcommand> [options]',
+        subcommands: {
+            schema: {
+                description: 'Show database schema for an environment',
+                usage: 'eve db schema --env <name> [--project <id>]',
+                options: ['--env <name>          Environment name (required)'],
+                examples: ['eve db schema --env staging'],
+            },
+            rls: {
+                description: 'Show RLS policies and tables for an environment',
+                usage: 'eve db rls --env <name> [--project <id>]',
+                options: ['--env <name>          Environment name (required)'],
+                examples: ['eve db rls --env staging'],
+            },
+            sql: {
+                description: 'Run parameterized SQL as the calling user',
+                usage: 'eve db sql --env <name> --sql <statement> [options]',
+                options: [
+                    '--env <name>          Environment name (required)',
+                    '--sql <statement>     SQL to run (inline)',
+                    '--file <path>         Read SQL from file',
+                    '--params <json>       JSON array/object of parameters',
+                    '--write               Allow writes (requires db.write scope)',
+                ],
+                examples: [
+                    'eve db sql --env staging --sql "select * from notes"',
+                    'eve db sql --env staging --file ./query.sql --params "[1]"',
+                ],
+            },
+            migrate: {
+                description: 'Apply pending migrations for an environment',
+                usage: 'eve db migrate --env <name> [--project <id>]',
+                options: [
+                    '--env <name>          Environment name (required)',
+                    '--path <dir>         Migrations directory (default .eve/migrations)',
+                ],
+                examples: ['eve db migrate --env staging', 'eve db migrate --env test --path ./migrations'],
+            },
+        },
+    },
+    pipeline: {
+        description: 'Run and inspect pipelines defined in the project manifest.',
+        usage: 'eve pipeline <subcommand> [options]',
+        subcommands: {
+            list: {
+                description: 'List pipelines for a project',
+                usage: 'eve pipeline list [project]',
+                options: [
+                    '<project>             Project ID or slug (uses profile default if omitted)',
+                ],
+                examples: ['eve pipeline list', 'eve pipeline list proj_xxx'],
+            },
+            show: {
+                description: 'Show pipeline definition',
+                usage: 'eve pipeline show <project> <name>',
+                examples: ['eve pipeline show proj_xxx release', 'eve pipeline show my-project deploy'],
+            },
+            run: {
+                description: 'Run a pipeline',
+                usage: 'eve pipeline run <name> --ref <sha> [--env <env>] [--wait]',
+                options: [
+                    '--ref <sha>          Git SHA or ref (required)',
+                    '--env <env>          Target environment',
+                    '--project <id>       Project ID (uses profile default)',
+                    '--wait               Wait for completion',
+                    '--timeout <n>        Max wait time (seconds)',
+                    '--inputs <json>      JSON inputs for the pipeline',
+                ],
+                examples: [
+                    'eve pipeline run deploy-test --ref abc123 --env test',
+                    'eve pipeline run deploy-test --ref abc123 --env test --wait --timeout 120',
+                ],
+            },
+            runs: {
+                description: 'List runs for a pipeline',
+                usage: 'eve pipeline runs <name> [project]',
+                options: [
+                    '--limit <n>          Number of results (default: 10)',
+                    '--offset <n>         Skip first n results',
+                ],
+                examples: ['eve pipeline runs deploy-test', 'eve pipeline runs deploy-test proj_xxx'],
+            },
+            'show-run': {
+                description: 'Show a pipeline run',
+                usage: 'eve pipeline show-run <name> <run-id> [--project <id>]',
+                examples: ['eve pipeline show-run deploy-test prun_xxx'],
+            },
+            approve: {
+                description: 'Approve a pipeline run awaiting approval',
+                usage: 'eve pipeline approve <run-id>',
+                examples: ['eve pipeline approve prun_xxx'],
+            },
+            cancel: {
+                description: 'Cancel a pipeline run',
+                usage: 'eve pipeline cancel <run-id> [--reason <text>]',
+                examples: ['eve pipeline cancel prun_xxx --reason "superseded"'],
+            },
+        },
+        examples: ['eve pipeline list', 'eve pipeline run deploy-test --ref abc123 --env test'],
+    },
+    workflow: {
+        description: 'Inspect workflows defined in the project manifest (read-only in Phase 1).',
+        usage: 'eve workflow <subcommand> [options]',
+        subcommands: {
+            list: {
+                description: 'List workflows for a project',
+                usage: 'eve workflow list [project]',
+                options: [
+                    '<project>             Project ID or slug (uses profile default if omitted)',
+                ],
+                examples: ['eve workflow list', 'eve workflow list proj_xxx'],
+            },
+            show: {
+                description: 'Show workflow definition',
+                usage: 'eve workflow show <project> <name>',
+                examples: ['eve workflow show proj_xxx qa-review', 'eve workflow show my-project release-notes'],
+            },
+        },
+        examples: ['eve workflow list', 'eve workflow show proj_xxx qa-review'],
+    },
+    event: {
+        description: 'Emit and inspect events. Apps use this to participate in the Event Ecosystem.',
+        usage: 'eve event <subcommand> [options]',
+        subcommands: {
+            list: {
+                description: 'List events for a project',
+                usage: 'eve event list [project] [--type] [--source] [--status]',
+                options: [
+                    '<project>             Project ID or slug (uses profile default if omitted)',
+                    '--type <type>         Filter by event type (e.g., github.push, app.deploy.complete)',
+                    '--source <source>     Filter by source (e.g., github, cron, app)',
+                    '--status <status>     Filter by status (pending, processed, failed)',
+                    '--limit <n>           Number of results',
+                    '--offset <n>          Skip first n results',
+                ],
+                examples: ['eve event list', 'eve event list --type app.deploy.complete --source app'],
+            },
+            show: {
+                description: 'Show event details',
+                usage: 'eve event show <event_id> [--project <id>]',
+                examples: ['eve event show evt_xxx', 'eve event show evt_xxx --project proj_yyy'],
+            },
+            emit: {
+                description: 'Emit an event to trigger pipelines or notify other services',
+                usage: 'eve event emit --type <type> --source <source> [options]',
+                options: [
+                    '--project <id>        Project ID (required)',
+                    '--type <type>         Event type (e.g., app.build.complete, deploy.finished)',
+                    '--source <source>     Event source (e.g., app, ci, manual)',
+                    '--env <name>          Environment name',
+                    '--branch <branch>     Git branch reference',
+                    '--sha <sha>           Git commit SHA',
+                    '--payload <json>      JSON payload with event data',
+                ],
+                examples: [
+                    'eve event emit --project proj_xxx --type app.build.complete --source app',
+                    'eve event emit --project proj_xxx --type deploy.finished --source ci --env production --payload \'{"version":"1.2.3"}\'',
+                ],
+            },
+        },
+        examples: [
+            'eve event list',
+            'eve event emit --type app.ready --source app --project proj_xxx',
+        ],
+    },
+    system: {
+        description: 'System administration and health checks.',
+        usage: 'eve system <subcommand> [options]',
+        subcommands: {
+            health: {
+                description: 'Quick health check of the API',
+                usage: 'eve system health',
+                examples: ['eve system health', 'eve system health --json'],
+            },
+            status: {
+                description: 'Show comprehensive system status (API, orchestrator, worker, queue)',
+                usage: 'eve system status',
+                examples: ['eve system status', 'eve system status --json'],
+            },
+            jobs: {
+                description: 'List all jobs across all projects (admin view)',
+                usage: 'eve system jobs [--org <id>] [--project <id>] [--phase <phase>] [--limit <n>] [--offset <n>]',
+                options: [
+                    '--org <id>           Filter by organization ID',
+                    '--project <id>       Filter by project ID',
+                    '--phase <phase>      Filter by job phase',
+                    '--limit <n>          Number of results (default: 50)',
+                    '--offset <n>         Skip first n results',
+                ],
+                examples: [
+                    'eve system jobs',
+                    'eve system jobs --phase active',
+                    'eve system jobs --project proj_xxx',
+                ],
+            },
+            envs: {
+                description: 'List all environments across all projects (admin view)',
+                usage: 'eve system envs [--org <id>] [--project <id>] [--limit <n>] [--offset <n>]',
+                options: [
+                    '--org <id>           Filter by organization ID',
+                    '--project <id>       Filter by project ID',
+                    '--limit <n>          Number of results (default: 50)',
+                    '--offset <n>         Skip first n results',
+                ],
+                examples: [
+                    'eve system envs',
+                    'eve system envs --project proj_xxx',
+                ],
+            },
+            logs: {
+                description: 'Fetch recent logs for a system service (api, orchestrator, worker, postgres)',
+                usage: 'eve system logs <service> [--tail <n>]',
+                options: [
+                    '--tail <n>          Number of log lines (default: 100)',
+                ],
+                examples: [
+                    'eve system logs api',
+                    'eve system logs worker --tail 200',
+                ],
+            },
+            pods: {
+                description: 'List pods across the cluster (admin view)',
+                usage: 'eve system pods',
+                examples: ['eve system pods'],
+            },
+            events: {
+                description: 'List recent cluster events (admin view)',
+                usage: 'eve system events [--limit <n>]',
+                options: [
+                    '--limit <n>         Max number of events (default: 50)',
+                ],
+                examples: ['eve system events', 'eve system events --limit 20'],
+            },
+            config: {
+                description: 'Show deployment configuration summary (system admins only)',
+                usage: 'eve system config',
+                examples: ['eve system config'],
+            },
+        },
+        examples: [
+            'eve system health',
+            'eve system status',
+            'eve system jobs',
+            'eve system envs',
+            'eve system logs api',
+        ],
+    },
+};
+function showMainHelp() {
+    console.log('Eve Horizon CLI');
+    console.log('');
+    console.log('Usage: eve <command> [subcommand] [options]');
+    console.log('');
+    console.log('Commands:');
+    console.log('  org        Manage organizations');
+    console.log('  project    Manage projects');
+    console.log('  job        Manage jobs (create, list, show, update, claim, etc.)');
+    console.log('  env        Manage environments (list, show, deploy)');
+    console.log('  api        Explore API sources and call endpoints');
+    console.log('  db         Inspect env DB schema, RLS, and SQL');
+    console.log('  pipeline   Inspect manifest pipelines (list, show)');
+    console.log('  workflow   Inspect manifest workflows (list, show)');
+    console.log('  event      Emit and inspect events (app integration)');
+    console.log('  secrets    Manage secrets (project/org/user scope)');
+    console.log('  harness    Inspect harnesses and auth status');
+    console.log('  profile    Manage CLI profiles (API URL, defaults)');
+    console.log('  auth       Authentication (login, logout, status)');
+    console.log('  system     System health and status checks');
+    console.log('');
+    console.log('Global options:');
+    console.log('  --help               Show help for command');
+    console.log('  --api-url <url>      Override API URL');
+    console.log('  --profile <name>     Use named profile');
+    console.log('  --org <id>           Override default org');
+    console.log('  --project <id>       Override default project');
+    console.log('  --json               Output as JSON');
+    console.log('');
+    console.log('Examples:');
+    console.log('  eve org ensure "My Company"');
+    console.log('  eve project ensure --name my-app --slug MyApp --repo-url https://github.com/org/repo');
+    console.log('  eve job create --description "Fix the bug in auth.ts"');
+    console.log('  eve job list --phase ready');
+    console.log('  eve job show MyProj-abc123');
+    console.log('');
+    console.log('Run "eve <command> --help" for more information on a command.');
+}
+function showCommandHelp(command) {
+    const help = exports.HELP[command];
+    if (!help) {
+        console.log(`Unknown command: ${command}`);
+        console.log('Run "eve --help" for available commands.');
+        return;
+    }
+    console.log(`eve ${command} - ${help.description.split('\n')[0]}`);
+    console.log('');
+    if (help.description.includes('\n')) {
+        console.log(help.description);
+        console.log('');
+    }
+    console.log(`Usage: ${help.usage}`);
+    console.log('');
+    if (help.subcommands) {
+        console.log('Subcommands:');
+        const maxLen = Math.max(...Object.keys(help.subcommands).map(k => k.length));
+        for (const [name, sub] of Object.entries(help.subcommands)) {
+            console.log(`  ${name.padEnd(maxLen + 2)} ${sub.description}`);
+        }
+        console.log('');
+    }
+    if (help.examples && help.examples.length > 0) {
+        console.log('Examples:');
+        help.examples.forEach(ex => console.log(`  ${ex}`));
+        console.log('');
+    }
+    console.log(`Run "eve ${command} <subcommand> --help" for subcommand details.`);
+}
+function showSubcommandHelp(command, subcommand) {
+    const cmdHelp = exports.HELP[command];
+    if (!cmdHelp) {
+        console.log(`Unknown command: ${command}`);
+        return;
+    }
+    const subHelp = cmdHelp.subcommands?.[subcommand];
+    if (!subHelp) {
+        console.log(`Unknown subcommand: ${command} ${subcommand}`);
+        console.log(`Run "eve ${command} --help" for available subcommands.`);
+        return;
+    }
+    console.log(`eve ${command} ${subcommand} - ${subHelp.description}`);
+    console.log('');
+    console.log(`Usage: ${subHelp.usage}`);
+    if (subHelp.options && subHelp.options.length > 0) {
+        console.log('');
+        console.log('Options:');
+        subHelp.options.forEach(opt => console.log(`  ${opt}`));
+    }
+    if (subHelp.examples && subHelp.examples.length > 0) {
+        console.log('');
+        console.log('Examples:');
+        subHelp.examples.forEach(ex => console.log(`  ${ex}`));
+    }
+}
+function shouldShowHelp(subcommand, flags) {
+    if (flags.help || flags.h) {
+        return subcommand ? 'subcommand' : 'command';
+    }
+    if (subcommand === '--help' || subcommand === '-h') {
+        return 'command';
+    }
+    if (!subcommand) {
+        return 'command';
+    }
+    return false;
+}