@formigio/fazemos-cli 0.10.46 → 0.10.49

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
 import chalk from 'chalk';
-import { config, getEnv, getToken, getActiveOrgId, setActiveOrgId, addEnvironment, hasEnvironments, 
+import { config, getEnv, getToken, getActiveEnvName, getActiveEnvSource, setEnvOverride, getActiveOrgId, setActiveOrgId, addEnvironment, hasEnvironments, 
 // F15 — project context helpers
 getActiveProjectId, setActiveProjectId, clearActiveProjectId, findProjectBySlug, findProjectById, findOrgById, 
 // Directory-scoped context override (.fazemos.json)
@@ -199,7 +199,12 @@ const program = new Command();
 program
     .name('fazemos')
     .description('Fazemos CLI — Team Accomplishment Platform')
-    .version(pkg.version);
+    .version(pkg.version)
+    // Session-scoped environment override. Precedence: this flag > FAZEMOS_ENV
+    // env var > the persisted active env. Lets one command (or, via the env var,
+    // a whole session) target a different environment without a shared-disk
+    // `fazemos env` switch that would clobber a concurrent session.
+    .option('--env <name>', 'Environment to use for this invocation (overrides FAZEMOS_ENV and the persisted active env)');
 // ── Directory-scoped default org/project (.fazemos.json) ─────
 //
 // Before any command action runs, discover the nearest `.fazemos.json`
@@ -266,6 +271,11 @@ async function applyDirContext(topCommand) {
     }
 }
 program.hook('preAction', async (_thisCommand, actionCommand) => {
+    // Apply the global `--env` flag first so every downstream resolution (dir
+    // context slug lookups, auth, API calls) sees the right environment.
+    const envFlag = program.opts().env;
+    if (envFlag)
+        setEnvOverride(envFlag);
     // Resolve the top-level command name (e.g. `worksheets list` → `worksheets`).
     let c = actionCommand;
     let top = c?.name?.();
@@ -332,8 +342,8 @@ program
 // ── Environment ─────────────────────────────────────────────
 program
     .command('env')
-    .description('Show or switch environment')
-    .argument('[name]', 'Environment to switch to')
+    .description('Show or switch environment. The persisted switch is machine-global; for per-session isolation set FAZEMOS_ENV or pass --env.')
+    .argument('[name]', 'Environment to switch to (persisted, machine-global)')
     .action((name) => {
     if (!hasEnvironments()) {
         console.log(chalk.yellow('No environments configured. Run: fazemos init <name> --api-url <url>'));
@@ -347,10 +357,25 @@ program
             process.exit(1);
         }
         config.set('activeEnv', name);
-        console.log(chalk.green(`Switched to ${name}`));
+        console.log(chalk.green(`Switched persisted environment to ${name}`));
+        // A persisted switch is machine-global. If this session is pinned to a
+        // different env via the override chain, the switch won't take effect here
+        // until the override is cleared — say so rather than silently no-op'ing.
+        const src = getActiveEnvSource();
+        if ((src === 'session' || src === 'flag') && getActiveEnvName() !== name) {
+            const via = src === 'flag' ? '--env' : 'FAZEMOS_ENV';
+            console.log(chalk.yellow(`Note: this session is pinned to "${getActiveEnvName()}" via ${via}; ` +
+                `the persisted switch won't take effect here until that override is cleared.`));
+        }
     }
     const env = getEnv();
-    console.log(`  Environment: ${chalk.cyan(env.name)}`);
+    const src = getActiveEnvSource();
+    const srcLabel = src === 'flag'
+        ? chalk.gray(' (this invocation, via --env)')
+        : src === 'session'
+            ? chalk.gray(' (this session, via FAZEMOS_ENV)')
+            : '';
+    console.log(`  Environment: ${chalk.cyan(env.name)}${srcLabel}`);
     console.log(`  API:         ${env.apiUrl}`);
     console.log(`  Cognito:     ${env.cognitoPoolId}`);
     const token = getToken();
@@ -433,11 +458,11 @@ auth
     .command('logout')
     .description('Clear stored credentials')
     .action(() => {
-    const env = config.get('activeEnv');
+    const env = getActiveEnvName();
     const auths = config.get('auth');
     delete auths[env];
     config.set('auth', auths);
-    console.log(chalk.green('Logged out'));
+    console.log(chalk.green(`Logged out of ${env}`));
 });
 // ── Whoami ──────────────────────────────────────────────────
 program
@@ -459,6 +484,13 @@ program
         }
         console.log(`  User:    ${chalk.cyan(data.user.email)}`);
         console.log(`  Member:  ${data.member.displayName} (${data.member.role})`);
+        const envSrc = getActiveEnvSource();
+        const envSrcLabel = envSrc === 'flag'
+            ? chalk.gray(' (this invocation, via --env)')
+            : envSrc === 'session'
+                ? chalk.gray(' (this session, via FAZEMOS_ENV)')
+                : '';
+        console.log(`  Env:     ${chalk.cyan(getActiveEnvName())}${envSrcLabel}`);
         const activeOrgId = getActiveOrgId() ?? data.activeOrgId;
         const activeOrg = data.orgs.find(o => o.id === activeOrgId);
         if (activeOrg) {
@@ -1229,6 +1261,39 @@ function projectOpts(opts) {
         allProjects: opts.allProjects,
     };
 }
+/**
+ * W-TOOL-3 — scope options for by-ID worksheet READ verbs (`ws show`,
+ * `ws report`, `oc list`, `ac list`, `cm list`).
+ *
+ * `GET /api/worksheets/:id` (and `/progress-board`) strictly scope the read
+ * to the caller's project: when an `X-Fazemos-Project-Id` header is present
+ * and does not equal the worksheet's `project_id`, the API returns 404 (an
+ * enumeration guard). Because `api()` always attaches the *active* project's
+ * header by default, an org steward reading a worksheet that lives in a
+ * sibling project gets a spurious 404 — which is exactly the raw-API drop
+ * Ollie reported.
+ *
+ *   --project <slug>  → send THAT project's header (resolves the sibling read)
+ *   --all-projects    → OMIT the project header entirely, so an owner/admin
+ *                       gets an org-wide read. The API only enforces the
+ *                       header/worksheet match when a header is present; with
+ *                       no header an owner/admin resolves any worksheet in the
+ *                       org, while a plain member still needs a
+ *                       `project_members` row for the worksheet's project
+ *                       (authorization is unchanged — only the accidental
+ *                       active-project pin is removed).
+ *
+ * Deliberately different from projectOpts(): on a LIST endpoint --all-projects
+ * appends ?view=all to widen the list; on a by-ID read there is no list to
+ * widen — the fix is to stop pinning the header to the active project.
+ */
+function readScopeOpts(opts) {
+    if (opts.allProjects)
+        return { noProjectHeader: true };
+    if (opts.project)
+        return { projectSlug: opts.project };
+    return {};
+}
 /**
  * Uniform error handler for scoped commands. When the API emits
  * MISSING_PROJECT_CONTEXT (§7.3.1), the api helper has already re-shaped
@@ -2383,15 +2448,18 @@ ws
 });
 ws
     .command('show')
-    .description('Show worksheet detail')
+    .description('Show worksheet detail. Pass --project <slug> (or --all-projects) to read a worksheet that lives in a sibling project.')
     .argument('<id>', 'Worksheet ID')
-    .action(async (id) => {
+    .option('--project <slug>', 'Read a worksheet in this project (resolves cross-project 404s)')
+    .option('--all-projects', 'Read org-wide without pinning to the active project', false)
+    .action(async (id, opts) => {
     try {
+        const scope = readScopeOpts(opts);
         // G4 (AC15): fetch enriched actions in parallel so we can display
         // linked_pipeline status chips next to bound actions.
         const [data, actionsResult] = await Promise.all([
-            api('GET', `/api/worksheets/${id}`),
-            api('GET', `/api/worksheets/${id}/actions`).catch(() => null),
+            api('GET', `/api/worksheets/${id}`, undefined, scope),
+            api('GET', `/api/worksheets/${id}/actions`, undefined, scope).catch(() => null),
         ]);
         const w = data.worksheet;
         // Build a lookup map from action id → linked_pipeline (from the enriched endpoint)
@@ -2455,6 +2523,110 @@ ws
         process.exit(1);
     }
 });
+// W-TOOL-2 — `ws report <id>`: one-call progress digest.
+//
+// Retires Ollie's manual Progress-Read / Check-in-Prep assembly, which today
+// stitches 3–4 separate `oc list` / `ac list` / `cm list` reads by hand. The
+// single GET /api/worksheets/:id already returns the full bundle (worksheet +
+// outcomes + actions + commitments + milestones), so the digest is composed
+// client-side from ONE call — no new endpoint required.
+//
+// (The existing /progress-board endpoint was evaluated first per the cheapest-
+// correct-implementation rule, but it omits actions entirely and caps outcomes
+// at 6, so it cannot render "action velocity" or a complete outcome scoreboard.
+// See the Test Implementation Brief for the API-aggregate follow-up flagged to
+// Atlas.)
+ws
+    .command('report')
+    .description('One-call progress digest for a worksheet: Purpose, outcome scoreboard (current/target + status), action velocity, and kept/missed/pending commitments. Composed from a single read. Pass --project <slug> (or --all-projects) for a sibling-project worksheet.')
+    .argument('<id>', 'Worksheet ID')
+    .option('--json', 'Print the assembled report as JSON (machine-readable)')
+    .option('--project <slug>', 'Read a worksheet in this project (resolves cross-project 404s)')
+    .option('--all-projects', 'Read org-wide without pinning to the active project', false)
+    .action(async (id, opts) => {
+    try {
+        const data = await api('GET', `/api/worksheets/${id}`, undefined, readScopeOpts(opts));
+        const w = data.worksheet;
+        const outcomes = data.outcomes || [];
+        const actions = data.actions || [];
+        const commitments = data.commitments || [];
+        // Commitment roll-up: a commitment is "missed" if it is persisted missed
+        // OR still open past its due date (mirrors the API's own progress-board
+        // math: `status = 'missed' OR (status = 'open' AND due_date < today)`).
+        const today = new Date().toISOString().slice(0, 10);
+        const isMissed = (c) => c.status === 'missed' || (c.status === 'open' && c.due_date && c.due_date < today);
+        const isKept = (c) => c.status === 'completed';
+        const isPending = (c) => c.status === 'open' && !isMissed(c);
+        const kept = commitments.filter(isKept);
+        const missed = commitments.filter(isMissed);
+        const pending = commitments.filter(isPending);
+        if (opts.json) {
+            console.log(JSON.stringify({
+                worksheet: { id: w.id, name: w.name, purpose: w.purpose, status: w.status },
+                outcomes: outcomes.map(o => ({
+                    id: o.id,
+                    name: o.name,
+                    currentValue: o.current_value ?? null,
+                    targetValue: o.target_value ?? null,
+                    status: o.status,
+                })),
+                actions: actions.map(a => ({
+                    id: a.id,
+                    description: a.description,
+                    currentValue: a.current_value ?? null,
+                    targetValue: a.target_value ?? null,
+                    member: a.member_name ?? null,
+                })),
+                commitments: {
+                    kept: kept.length,
+                    missed: missed.length,
+                    pending: pending.length,
+                    total: commitments.length,
+                    items: commitments.map(c => ({
+                        id: c.id,
+                        description: c.description,
+                        dueDate: c.due_date,
+                        status: isMissed(c) ? 'missed' : isKept(c) ? 'kept' : 'pending',
+                    })),
+                },
+            }, null, 2));
+            return;
+        }
+        console.log(chalk.cyan.bold(w.name) + chalk.gray(`  (${w.status})`));
+        console.log(`  Purpose: ${w.purpose || chalk.gray('(none)')}`);
+        console.log(chalk.cyan(`\n  Outcomes (${outcomes.length}):`));
+        if (outcomes.length === 0) {
+            console.log(chalk.gray('    (none)'));
+        }
+        else {
+            for (const o of outcomes) {
+                const progress = o.target_value != null ? ` ${o.current_value ?? 0}/${o.target_value}` : '';
+                const icon = o.status === 'achieved' ? chalk.green('✓') : '○';
+                console.log(`    ${icon} ${o.name}${progress} — ${chalk.yellow(o.status || 'unknown')}`);
+            }
+        }
+        console.log(chalk.cyan(`\n  Action velocity (${actions.length}):`));
+        if (actions.length === 0) {
+            console.log(chalk.gray('    (none)'));
+        }
+        else {
+            for (const a of actions) {
+                const progress = a.target_value != null ? ` ${a.current_value ?? 0}/${a.target_value}` : '';
+                console.log(`    ${a.description}${progress} — ${a.member_name || 'unassigned'}`);
+            }
+        }
+        console.log(chalk.cyan(`\n  Commitments: ${chalk.green(kept.length + ' kept')}, ${chalk.red(missed.length + ' missed')}, ${pending.length} pending (${commitments.length} total)`));
+        for (const c of commitments) {
+            const icon = isKept(c) ? chalk.green('✓') : isMissed(c) ? chalk.red('✗') : '○';
+            const label = isMissed(c) ? 'missed' : isKept(c) ? 'kept' : 'pending';
+            console.log(`    ${icon} ${c.description} — due ${c.due_date} (${label})`);
+        }
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
 // ── Outcomes ────────────────────────────────────────────────
 const outcomes = program.command('outcomes').alias('oc').description('Outcome commands');
 outcomes
@@ -2491,11 +2663,13 @@ outcomes
 });
 outcomes
     .command('list')
-    .description('List outcomes on a worksheet')
+    .description('List outcomes on a worksheet. Pass --project <slug> (or --all-projects) to read a worksheet in a sibling project.')
     .requiredOption('-w, --worksheet <id>', 'Worksheet ID')
+    .option('--project <slug>', 'Read a worksheet in this project (resolves cross-project 404s)')
+    .option('--all-projects', 'Read org-wide without pinning to the active project', false)
     .action(async (opts) => {
     try {
-        const data = await api('GET', `/api/worksheets/${opts.worksheet}`);
+        const data = await api('GET', `/api/worksheets/${opts.worksheet}`, undefined, readScopeOpts(opts));
         if (!data.outcomes?.length) {
             console.log(chalk.yellow('No outcomes'));
             return;
@@ -2555,7 +2729,7 @@ outcomes
     .option('-d, --description <desc>', 'New description')
     .option('-m, --measurement <method>', 'How it is measured (e.g., "Count of active users")')
     .option('-t, --target <value>', 'Target value (numeric)', parseNumber)
-    .option('-s, --status <status>', 'Status: active, achieved, or dropped')
+    .option('-s, --status <status>', 'Status: on_track, at_risk, behind, or achieved')
     .action(async (opts) => {
     try {
         const body = {};
@@ -2920,28 +3094,135 @@ members
 const actions = program.command('actions').alias('ac').description('Action (lead measure) commands');
 actions
     .command('add')
-    .description('Add an action to a worksheet')
+    .description('Add one or more actions to a worksheet.\n' +
+    '  Single:  ac add -w <id> -n "<desc>" [-m <measurement>] [-t <target>] [-c <current>] [-o <outcomeId>]\n' +
+    '  Batch:   ac add -w <id> --action "<desc>" --action "<desc>" ...   (repeatable, description-only)\n' +
+    '  Batch:   ac add -w <id> --file actions.json                       (JSON array of full action objects)\n' +
+    '  Preview: add --dry-run to print exactly what would be written without creating anything.')
     .requiredOption('-w, --worksheet <id>', 'Worksheet ID')
-    .requiredOption('-n, --name <name>', 'Action description')
-    .option('-o, --outcome <id>', 'Linked outcome ID')
-    .option('-m, --measurement <method>', 'How it is measured')
-    .option('-t, --target <value>', 'Target value', parseNumber)
-    .option('-c, --current <value>', 'Current value', parseNumber)
+    .option('-n, --name <name>', 'Action description (single-add form)')
+    .option('-o, --outcome <id>', 'Linked outcome ID (single-add form)')
+    .option('-m, --measurement <method>', 'How it is measured (single-add form)')
+    .option('-t, --target <value>', 'Target value (single-add form)', parseNumber)
+    .option('-c, --current <value>', 'Current value (single-add form)', parseNumber)
+    .option('--action <desc>', 'Batch: an action description (repeatable). Use --file for actions that need measurement/target.', (v, acc) => { const list = Array.isArray(acc) ? acc : []; list.push(v); return list; })
+    .option('--file <path>', 'Batch: path to a JSON array of action objects ({ description|name, measurement?, target?, current?, outcomeId? }). "@file.json" is also accepted.')
+    .option('--dry-run', 'Preview the action(s) that would be created without writing anything', false)
     .action(async (opts) => {
     try {
-        const body = { description: opts.name };
-        if (opts.outcome)
-            body.outcomeId = opts.outcome;
-        if (opts.measurement)
-            body.measurement = opts.measurement;
-        if (opts.target !== undefined)
-            body.targetValue = opts.target;
-        if (opts.current !== undefined)
-            body.currentValue = opts.current;
-        const data = await api('POST', `/api/worksheets/${opts.worksheet}/actions`, body);
-        const a = data.action;
-        console.log(chalk.green(`Added action: ${a.description}`));
-        console.log(`  ID: ${a.id}`);
+        // Normalize a raw item (from --file or a flag) into an API body.
+        const toBody = (item) => {
+            const description = item.description ?? item.name;
+            if (!description || typeof description !== 'string' || description.trim().length === 0) {
+                throw new Error('each action needs a non-empty "description" (or "name")');
+            }
+            const body = { description };
+            const outcomeId = item.outcomeId ?? item.outcome;
+            const measurement = item.measurement;
+            const target = item.targetValue ?? item.target;
+            const current = item.currentValue ?? item.current;
+            if (outcomeId != null)
+                body.outcomeId = outcomeId;
+            if (measurement != null)
+                body.measurement = measurement;
+            if (target != null)
+                body.targetValue = typeof target === 'number' ? target : parseNumber(String(target));
+            if (current != null)
+                body.currentValue = typeof current === 'number' ? current : parseNumber(String(current));
+            return body;
+        };
+        // Resolve the source of truth for what to create. Exactly one of:
+        //   --file  |  --action (repeatable)  |  -n/--name (single form)
+        const batchActions = opts.action;
+        let filePath = opts.file;
+        // Support the "@file.json" convention (a bare @-prefixed --file value).
+        if (filePath && filePath.startsWith('@'))
+            filePath = filePath.slice(1);
+        const sources = [
+            filePath ? 'file' : null,
+            batchActions && batchActions.length ? 'action' : null,
+            opts.name ? 'name' : null,
+        ].filter(Boolean);
+        if (sources.length === 0) {
+            console.error(chalk.red('Provide -n/--name (single), --action (repeatable), or --file (JSON batch).'));
+            process.exit(1);
+        }
+        if (sources.length > 1) {
+            console.error(chalk.red(`Choose one input form — got ${sources.join(' + ')}. Combine measurement/target with the --file form.`));
+            process.exit(1);
+        }
+        // Build the list of bodies.
+        let bodies;
+        if (filePath) {
+            let parsed;
+            try {
+                parsed = JSON.parse(readFileSync(resolve(filePath), 'utf-8'));
+            }
+            catch (e) {
+                console.error(chalk.red(`Could not read/parse ${filePath}: ${e.message}`));
+                process.exit(1);
+            }
+            const arr = Array.isArray(parsed) ? parsed : (Array.isArray(parsed?.actions) ? parsed.actions : null);
+            if (!arr) {
+                console.error(chalk.red('The --file must contain a JSON array of action objects (or an { "actions": [...] } wrapper).'));
+                process.exit(1);
+            }
+            if (arr.length === 0) {
+                console.error(chalk.red('The --file action array is empty.'));
+                process.exit(1);
+            }
+            bodies = arr.map(toBody);
+        }
+        else if (batchActions && batchActions.length) {
+            bodies = batchActions.map((desc) => toBody({ description: desc }));
+        }
+        else {
+            bodies = [toBody({ description: opts.name, outcome: opts.outcome, measurement: opts.measurement, target: opts.target, current: opts.current })];
+        }
+        // Dry-run preview — no network calls.
+        if (opts.dryRun) {
+            console.log(chalk.cyan(`Dry run — ${bodies.length} action(s) would be created on worksheet ${opts.worksheet}:`));
+            bodies.forEach((b, i) => {
+                const extras = [];
+                if (b.measurement)
+                    extras.push(`measurement="${b.measurement}"`);
+                if (b.targetValue != null)
+                    extras.push(`target=${b.targetValue}`);
+                if (b.currentValue != null)
+                    extras.push(`current=${b.currentValue}`);
+                if (b.outcomeId)
+                    extras.push(`outcome=${b.outcomeId}`);
+                const tail = extras.length ? chalk.gray(`  [${extras.join(', ')}]`) : '';
+                console.log(`  ${i + 1}. ${b.description}${tail}`);
+            });
+            console.log(chalk.gray('Nothing was written. Re-run without --dry-run to create these actions.'));
+            return;
+        }
+        // Real create. Single form keeps its original one-line success output;
+        // batch form reports each created ID and a final summary.
+        if (bodies.length === 1 && sources[0] === 'name') {
+            const data = await api('POST', `/api/worksheets/${opts.worksheet}/actions`, bodies[0]);
+            const a = data.action;
+            console.log(chalk.green(`Added action: ${a.description}`));
+            console.log(`  ID: ${a.id}`);
+            return;
+        }
+        let created = 0;
+        for (let i = 0; i < bodies.length; i++) {
+            const b = bodies[i];
+            try {
+                const data = await api('POST', `/api/worksheets/${opts.worksheet}/actions`, b);
+                const a = data.action;
+                created++;
+                console.log(chalk.green(`  ✓ [${i + 1}/${bodies.length}] ${a.description} — ${a.id}`));
+            }
+            catch (e) {
+                console.error(chalk.red(`  ✗ [${i + 1}/${bodies.length}] ${b.description} — ${e.message}`));
+                console.error(chalk.yellow(`Stopped after ${created} of ${bodies.length} created. Fix the failing item and re-run for the remainder.`));
+                process.exit(1);
+            }
+        }
+        console.log(chalk.green(`Created ${created} action(s).`));
     }
     catch (err) {
         console.error(chalk.red(err.message));
@@ -2950,11 +3231,13 @@ actions
 });
 actions
     .command('list')
-    .description('List actions on a worksheet')
+    .description('List actions on a worksheet. Pass --project <slug> (or --all-projects) to read a worksheet in a sibling project.')
     .requiredOption('-w, --worksheet <id>', 'Worksheet ID')
+    .option('--project <slug>', 'Read a worksheet in this project (resolves cross-project 404s)')
+    .option('--all-projects', 'Read org-wide without pinning to the active project', false)
     .action(async (opts) => {
     try {
-        const data = await api('GET', `/api/worksheets/${opts.worksheet}/actions`);
+        const data = await api('GET', `/api/worksheets/${opts.worksheet}/actions`, undefined, readScopeOpts(opts));
         if (!data.actions?.length) {
             console.log(chalk.yellow('No actions'));
             return;
@@ -3017,6 +3300,21 @@ actions
         process.exit(1);
     }
 });
+actions
+    .command('remove')
+    .description('Permanently delete an action from a worksheet. This cannot be undone. Use "ac list -w <id>" (or "ws show <id>") to find action IDs.')
+    .requiredOption('-w, --worksheet <id>', 'Worksheet ID')
+    .requiredOption('-a, --action <id>', 'Action ID (from "ac list" or "ws show" output)')
+    .action(async (opts) => {
+    try {
+        await api('DELETE', `/api/worksheets/${opts.worksheet}/actions/${opts.action}`);
+        console.log(chalk.green('Action deleted'));
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
 actions
     .command('execute')
     .description('Trigger an agent execution for an action. The API determines which agent to use based on the action\'s configuration. For more control over agent selection and parameters, use the top-level "execute" command instead.')
@@ -3061,11 +3359,13 @@ commitments
 });
 commitments
     .command('list')
-    .description('List commitments on a worksheet')
+    .description('List commitments on a worksheet. Pass --project <slug> (or --all-projects) to read a worksheet in a sibling project.')
     .requiredOption('-w, --worksheet <id>', 'Worksheet ID')
+    .option('--project <slug>', 'Read a worksheet in this project (resolves cross-project 404s)')
+    .option('--all-projects', 'Read org-wide without pinning to the active project', false)
     .action(async (opts) => {
     try {
-        const data = await api('GET', `/api/worksheets/${opts.worksheet}/commitments`);
+        const data = await api('GET', `/api/worksheets/${opts.worksheet}/commitments`, undefined, readScopeOpts(opts));
         if (!data.commitments?.length) {
             console.log(chalk.yellow('No commitments'));
             return;
@@ -4736,19 +5036,50 @@ templates
 });
 // ── Pipelines ──────────────────────────────────────────────
 const pipelines = program.command('pipelines').alias('pl').description('Pipeline instance commands');
+// Keep this in sync with the `pl list --status` help text below. A typo like
+// `--status runing` would otherwise pass straight through to the API, exact-
+// match nothing, and print "No pipeline instances" — reading as "nothing
+// running" rather than "you mistyped". We reject unknown values up front with
+// the same allow-list pattern used by `orgs members` / `orgs invites list`.
+const PL_LIST_STATUSES = [
+    'active',
+    'all',
+    'created',
+    'running',
+    'paused',
+    'completed',
+    'failed',
+    'cancelled',
+    'archived',
+];
 pipelines
     .command('list')
     .description('List pipeline instances in the active project (or all projects with --all-projects)')
-    .option('-s, --status <status>', 'Filter by status (active, completed, archived)', 'active')
+    .option('-s, --status <status>', 'Filter by status: active (created/running/paused, the default), running, created, paused, completed, failed, cancelled, archived, or all', 'active')
     .option('--search <term>', 'Search by name or ID')
     .option('--expand', 'Include steps inline (avoids N+1)')
     .option('--project <slug>', 'Override active project for this call')
     .option('--all-projects', 'List pipelines across every project in the active org', false)
     .action(async (opts) => {
     try {
+        const status = opts.status || 'active';
+        if (!PL_LIST_STATUSES.includes(status)) {
+            console.error(chalk.red(`Invalid --status "${status}". Allowed values: ${PL_LIST_STATUSES.join(', ')}`));
+            process.exit(1);
+        }
         const params = [];
-        if (opts.status)
-            params.push(`status=${opts.status}`);
+        // Status → API mapping. The API treats a bare `status` value as an exact
+        // DB status match, and omitting it entirely as the "active" group
+        // (created/running/paused). In-flight instances carry DB status `running`,
+        // which no literal `active` value would ever match — so `active` (and the
+        // default) must map to "omit the param" rather than `status=active`, or
+        // `pl list` reports "No instances" while pipelines are actually running.
+        // `all` → `status=all` (API disables the filter). Every real DB status
+        // (running, created, paused, completed, failed, cancelled, archived) is
+        // passed through verbatim.
+        if (status && status !== 'active') {
+            params.push(`status=${status}`);
+        }
         if (opts.search)
             params.push(`search=${encodeURIComponent(opts.search)}`);
         if (opts.expand)