@hs-x/cli 0.2.6 → 0.3.0

package/dist/commands/flags.js

@@ -2,15 +2,23 @@ import { readFile } from 'node:fs/promises';
 import * as Command from '@effect/cli/Command';
 import * as Options from '@effect/cli/Options';
 import { FileSystem } from '@effect/platform';
-import { Schema, schemas } from '@hs-x/types';
 import { RuntimeFlagAuthoringError, createFlagAuthoringClient, } from '@hs-x/runtime';
+import { Schema, schemas } from '@hs-x/types';
 import { Config, Effect, Option } from 'effect';
+import { activeSession } from '../account-store.js';
 import { CliError, exitWith } from '../cli-error.js';
-import { jsonOption, runHandler } from '../cli/kit.js';
+import { accountIdOption, controlPlaneUrlOption, jsonOption, runHandler, yesOption, } from '../cli/kit.js';
+import { DEFAULT_CONTROL_PLANE_URL } from '../config.js';
+import { isMachineOutput } from '../output-context.js';
+import { canDiscoverHubSpotAppIdFromTenantBindings, readLocalProjectContext, resolveHubSpotAppId, resolveHubSpotAppIdFromTenantBindings, resolveProjectId, resolveRuntimeOrigin, } from '../project-context.js';
+import { ProjectPickerCancelled, createControlPlaneFlagAuthoringClient, discoverProjectRuntimeBindings, discoverProjects, resolveAccountId, resolveProjectSelection, resolveRuntimeBinding, } from '../project-picker.js';
+import { BACK, isInteractive, promptConfirm, promptSelect, promptText, } from '../prompt.js';
 import { createReporter } from '../reporter/index.js';
-import { loadTenantStateStore } from '../tenant-state.js';
+import { AccountStore } from '../services/account-store.js';
+import { ControlPlaneClient } from '../services/control-plane.js';
 import { Cwd } from '../services/cwd.js';
 import { Reporter } from '../services/reporter.js';
+import { loadTenantStateStore } from '../tenant-state.js';
 const SUBCOMMANDS = new Set(['list', 'create', 'define', 'enable', 'disable', 'archive']);
 function resolveFlag(argv, flag) {
     for (let index = 0; index < argv.length; index += 1) {
@@ -31,12 +39,191 @@ function fail(reporter, json, message) {
     }
     return { exitCode: 1 };
 }
+const liveFlagsPrompts = {
+    isInteractive,
+    select: promptSelect,
+    text: promptText,
+    confirm: promptConfirm,
+};
+class FlagsPromptCancelled extends Error {
+    constructor() {
+        super('Cancelled.');
+    }
+}
+const DEPLOY_REQUIRED = 'No deployed flag context was found. Run `hs-x deploy` in this checkout first.';
+/**
+ * Resolve the deployed flag scope without ever asking for opaque identifiers.
+ * Explicit options win over environment, then checkout bindings, then the
+ * discoverable tenant state. Ambiguity is selectable only in an interactive
+ * invocation; automation receives a deterministic pass-the-option error.
+ */
+export async function resolveFlagsContext(input) {
+    const prompts = input.prompts ?? liveFlagsPrompts;
+    const choose = async (opts) => {
+        const selected = await prompts.select(opts);
+        if (selected === undefined)
+            throw new FlagsPromptCancelled();
+        return selected;
+    };
+    let projectId = resolveProjectId({
+        explicit: input.explicitProjectId,
+        env: input.envProjectId,
+        local: input.local,
+    })?.value;
+    if (!projectId) {
+        const projects = await input.stateStore.listProjects();
+        if (projects.length === 0)
+            throw new Error(DEPLOY_REQUIRED);
+        if (projects.length === 1) {
+            projectId = projects[0];
+        }
+        else if (input.allowPrompt) {
+            const rows = await Promise.all(projects.map(async (id) => {
+                const deploys = await input.stateStore.listDeploys({ projectId: id });
+                const environments = [...new Set(deploys.map((deploy) => deploy.environment))];
+                return {
+                    value: id,
+                    label: id,
+                    description: `${deploys.length} deploy${deploys.length === 1 ? '' : 's'}${environments.length > 0 ? ` · ${environments.join(', ')}` : ''}`,
+                };
+            }));
+            projectId = await choose({ message: 'Which deployed project?', options: rows });
+        }
+        else {
+            throw new Error(`Multiple deployed projects are available (${projects.join(', ')}). Pass --project-id to choose one.`);
+        }
+    }
+    const deploys = await input.stateStore.listDeploys({ projectId });
+    let environment = input.explicitEnvironment ?? input.envEnvironment;
+    if (!environment) {
+        const environments = [...new Set(deploys.map((deploy) => deploy.environment))].sort();
+        if (environments.length === 0)
+            throw new Error(DEPLOY_REQUIRED);
+        if (environments.length === 1) {
+            environment = environments[0];
+        }
+        else if (input.allowPrompt) {
+            environment = await choose({
+                message: 'Which environment?',
+                options: environments.map((value) => {
+                    const matches = deploys.filter((deploy) => deploy.environment === value);
+                    const latest = matches[0];
+                    return {
+                        value,
+                        label: value,
+                        description: `${matches.length} deploy${matches.length === 1 ? '' : 's'}${latest ? ` · latest ${latest.createdAt}` : ''}`,
+                    };
+                }),
+            });
+        }
+        else {
+            throw new Error(`Multiple environments are deployed for ${projectId} (${environments.join(', ')}). Pass --environment to choose one.`);
+        }
+    }
+    const appInput = {
+        explicit: input.explicitAppId,
+        env: input.envAppId,
+        compatibilityEnv: input.compatibilityEnvAppId,
+        local: input.local,
+    };
+    let hubSpotAppId = resolveHubSpotAppId(appInput)?.value;
+    let bindings;
+    if (hubSpotAppId === undefined) {
+        if (input.explicitAppId !== undefined ||
+            input.envAppId ||
+            input.compatibilityEnvAppId ||
+            !canDiscoverHubSpotAppIdFromTenantBindings(appInput)) {
+            throw new Error('Require a valid integer --app-id (or HSX_APP_ID).');
+        }
+        bindings = await input.stateStore.listBindings({ projectId, environment });
+        const appIds = [
+            ...new Set(bindings
+                .map((binding) => Number(binding.hubSpotAppId))
+                .filter((appId) => Number.isInteger(appId) && appId > 0)),
+        ];
+        if (appIds.length === 0) {
+            throw new Error(`No HubSpot app binding is deployed for ${projectId}/${environment}. Run \`hs-x deploy\` to provision flag authoring.`);
+        }
+        if (appIds.length === 1) {
+            hubSpotAppId = appIds[0];
+        }
+        else if (input.allowPrompt) {
+            const selected = await choose({
+                message: 'Which HubSpot app?',
+                options: appIds.map((appId) => {
+                    const binding = bindings?.find((candidate) => Number(candidate.hubSpotAppId) === appId);
+                    const ready = Boolean(binding?.syncGrantSecretValue && binding.tenantScopeAccountId);
+                    return {
+                        value: String(appId),
+                        label: `HubSpot app ${appId}`,
+                        description: `${projectId}/${environment} · ${ready ? 'flag authoring ready' : 'needs redeploy'}`,
+                    };
+                }),
+            });
+            hubSpotAppId = Number(selected);
+        }
+        else {
+            throw new Error(`Multiple tenant bindings match ${projectId}/${environment} (apps ${appIds.join(', ')}). Pass --app-id to choose one.`);
+        }
+    }
+    const binding = bindings?.find((candidate) => Number(candidate.hubSpotAppId) === hubSpotAppId) ??
+        (await input.stateStore.getBinding({
+            projectId,
+            environment,
+            hubSpotAppId: hubSpotAppId,
+        }));
+    if (!binding?.syncGrantSecretValue || !binding.tenantScopeAccountId) {
+        throw new Error(`No flag-authoring credentials for ${projectId}/${environment} (app ${hubSpotAppId}). Re-deploy as a linked project to provision the tenant data plane.`);
+    }
+    let runtimeBaseUrl = input.explicitRuntimeOrigin ?? input.envRuntimeOrigin;
+    if (!runtimeBaseUrl) {
+        const active = await input.stateStore.getActive({ projectId, environment });
+        const activeDeploy = active
+            ? await input.stateStore.getDeploy({ projectId, deployId: active.deployId })
+            : undefined;
+        const candidates = [
+            ...new Map((activeDeploy
+                ? [activeDeploy]
+                : deploys.filter((deploy) => deploy.environment === environment))
+                .filter((deploy) => deploy.status === 'deployed')
+                .flatMap((deploy) => deploy.workerUrls
+                .filter((url) => url.trim().length > 0)
+                .map((url) => [url, { url, deploy }]))).values(),
+        ];
+        if (candidates.length === 0)
+            throw new Error(DEPLOY_REQUIRED);
+        if (candidates.length === 1) {
+            runtimeBaseUrl = candidates[0]?.url;
+        }
+        else if (input.allowPrompt) {
+            runtimeBaseUrl = await choose({
+                message: 'Which deployed runtime?',
+                options: candidates.map(({ url, deploy }) => ({
+                    value: url,
+                    label: url,
+                    description: `${deploy.deployId} · ${deploy.createdAt}`,
+                })),
+            });
+        }
+        else {
+            throw new Error(`Multiple deployed runtimes match ${projectId}/${environment}. Pass --runtime-origin to choose one.`);
+        }
+    }
+    if (!runtimeBaseUrl)
+        throw new Error(DEPLOY_REQUIRED);
+    return {
+        projectId: projectId,
+        environment: environment,
+        hubSpotAppId: hubSpotAppId,
+        runtimeBaseUrl,
+        binding: binding,
+    };
+}
 /**
- * ADR-015 §5 `hs-x flags` — the leaveable, direct-to-tenant flag authoring CLI.
- * It reads the per-install grant secret + InstallationKey scope a linked deploy
- * stashed in local state, then signs and POSTs to the deployed Worker's
- * `/_hsx/flags/define` and `/_hsx/flags/list` via {@link createFlagAuthoringClient}.
- * The control plane is never on this path.
+ * ADR-015 §5 `hs-x flags` flag authoring CLI. The native command discovers
+ * account-scoped projects and redacted runtime bindings through the control
+ * plane, then uses its flag conduit. This legacy entry point retains the
+ * direct-to-tenant local-state transport for compatibility.
  *
  *   hs-x flags list                       [--limit N]
  *   hs-x flags create --file flag.json     (identity is stamped from the scope)
@@ -54,23 +241,52 @@ export async function flagsCommand(input) {
     if (!subcommand || !SUBCOMMANDS.has(subcommand)) {
         return fail(reporter, json, `Usage: hs-x flags <${[...SUBCOMMANDS].join('|')}> [options]`);
     }
-    const projectId = resolveFlag(argv, '--project-id') ?? process.env.HSX_PROJECT_ID;
+    const local = await readLocalProjectContext(root);
+    const projectId = resolveProjectId({
+        explicit: resolveFlag(argv, '--project-id'),
+        env: process.env.HSX_PROJECT_ID,
+        local,
+    })?.value;
     const environment = resolveFlag(argv, '--environment') ?? resolveFlag(argv, '--env') ?? 'production';
-    const appIdRaw = resolveFlag(argv, '--app-id') ?? process.env.HSX_APP_ID;
-    const hubSpotAppId = appIdRaw ? Number(appIdRaw) : undefined;
+    const explicitAppId = resolveFlag(argv, '--app-id');
+    const appIdInput = {
+        ...(explicitAppId === undefined ? {} : { explicit: Number(explicitAppId) }),
+        env: process.env.HSX_APP_ID,
+        compatibilityEnv: process.env.HSX_HUBSPOT_APP_ID,
+        local,
+    };
+    let hubSpotAppId = resolveHubSpotAppId(appIdInput)?.value;
     if (!projectId)
         return fail(reporter, json, 'Require --project-id (or HSX_PROJECT_ID).');
-    if (hubSpotAppId === undefined || !Number.isInteger(hubSpotAppId)) {
-        return fail(reporter, json, 'Require an integer --app-id (or HSX_APP_ID).');
-    }
-    const runtimeBaseUrl = resolveFlag(argv, '--runtime-origin') ?? process.env.HSX_RUNTIME_BASE_URL;
-    if (!runtimeBaseUrl) {
-        return fail(reporter, json, 'Require --runtime-origin (or HSX_RUNTIME_BASE_URL) — the deployed Worker URL.');
-    }
     const context = await loadTenantStateStore({ argv, root });
     if (!context) {
         return fail(reporter, json, 'No .hs-x/cloudflare.json found. Deploy this project first with `hs-x deploy`.');
     }
+    if (hubSpotAppId === undefined && canDiscoverHubSpotAppIdFromTenantBindings(appIdInput)) {
+        try {
+            hubSpotAppId = (await resolveHubSpotAppIdFromTenantBindings({
+                stateStore: context.stateStore,
+                projectId,
+                environment,
+            }))?.value;
+        }
+        catch (error) {
+            return fail(reporter, json, error instanceof Error ? error.message : String(error));
+        }
+    }
+    if (hubSpotAppId === undefined) {
+        return fail(reporter, json, 'Require an integer --app-id (or HSX_APP_ID).');
+    }
+    const runtimeBaseUrl = (await resolveRuntimeOrigin({
+        explicit: resolveFlag(argv, '--runtime-origin'),
+        env: process.env.HSX_RUNTIME_BASE_URL,
+        stateStore: context.stateStore,
+        projectId,
+        environment,
+    }))?.value;
+    if (!runtimeBaseUrl) {
+        return fail(reporter, json, 'Require --runtime-origin (or HSX_RUNTIME_BASE_URL) — no active deploy Worker URL was found.');
+    }
     const binding = await context.stateStore.getBinding({
         projectId,
         environment,
@@ -131,7 +347,7 @@ async function runList(input) {
     }
     return { exitCode: 0 };
 }
-async function runCreate(input) {
+export async function runCreate(input) {
     const file = resolveFlag(input.argv, '--file');
     if (!file)
         return fail(input.reporter, input.json, 'Require --file <flag-definition.json> for `flags create`.');
@@ -170,13 +386,526 @@ async function runCreate(input) {
     }
     return { exitCode: 0 };
 }
-async function runSetState(input) {
-    const key = resolveFlag(input.argv, '--key');
-    if (!key)
+/** Dependency-injected action seam used by the bare `hs-x flags` TTY flow. */
+export async function selectFlagsAction(prompts = liveFlagsPrompts) {
+    const action = await prompts.select({
+        message: 'What would you like to do?',
+        options: [
+            { value: 'list', label: 'List flags', description: 'Show flags in this deployed runtime' },
+            {
+                value: 'create',
+                label: 'Create or update a flag',
+                description: 'Guided typed flag definition with exact-match targeting',
+            },
+            { value: 'enable', label: 'Enable a flag', description: 'Choose a legal transition' },
+            { value: 'disable', label: 'Disable a flag', description: 'Choose a legal transition' },
+            { value: 'archive', label: 'Archive a flag', description: 'Permanent lifecycle transition' },
+            { value: 'cancel', label: 'Cancel' },
+        ],
+    });
+    return action === undefined || action === 'cancel' ? undefined : action;
+}
+const MAX_GUIDED_VARIATIONS = 20;
+const MAX_GUIDED_RULES = 10;
+async function wizardText(prompts, opts) {
+    for (;;) {
+        const answer = await prompts.text(opts);
+        if (answer === undefined || answer === BACK)
+            return answer;
+        const value = answer.trim();
+        if (!opts.validate || opts.validate(value) === undefined)
+            return value;
+    }
+}
+function variationValueText(type) {
+    switch (type) {
+        case 'string':
+            return 'String value';
+        case 'number':
+            return 'Number value';
+        case 'json':
+            return 'JSON value';
+        case 'boolean':
+            return 'Boolean value';
+    }
+}
+function parseVariationValue(type, source) {
+    switch (type) {
+        case 'string':
+            return { type, value: source };
+        case 'number': {
+            const value = Number(source);
+            return source.length > 0 && Number.isFinite(value) ? { type, value } : undefined;
+        }
+        case 'json':
+            try {
+                return { type, value: JSON.parse(source) };
+            }
+            catch {
+                return undefined;
+            }
+    }
+}
+async function buildVariations(prompts, type) {
+    if (type === 'boolean') {
+        return [
+            { name: 'off', label: 'Off', value: { type: 'boolean', value: false } },
+            { name: 'on', label: 'On', value: { type: 'boolean', value: true } },
+        ];
+    }
+    const variations = [];
+    while (variations.length < MAX_GUIDED_VARIATIONS) {
+        const name = await wizardText(prompts, {
+            message: `Variation ${variations.length + 1} key`,
+            allowBack: true,
+            validate: (value) => {
+                if (value.length === 0)
+                    return 'Enter a variation key.';
+                if (variations.some((variation) => variation.name === value)) {
+                    return 'Variation keys must be unique.';
+                }
+                return undefined;
+            },
+        });
+        if (name === undefined)
+            return undefined;
+        if (name === BACK) {
+            if (variations.length === 0)
+                return BACK;
+            variations.pop();
+            continue;
+        }
+        const label = await wizardText(prompts, {
+            message: `Label for variation "${name}"`,
+            default: name,
+            allowBack: true,
+            validate: (value) => (value.length === 0 ? 'Enter a variation label.' : undefined),
+        });
+        if (label === undefined)
+            return undefined;
+        if (label === BACK)
+            continue;
+        let value;
+        for (;;) {
+            const source = await wizardText(prompts, {
+                message: variationValueText(type),
+                allowBack: true,
+                validate: (raw) => parseVariationValue(type, raw) === undefined
+                    ? type === 'number'
+                        ? 'Enter a finite number.'
+                        : 'Enter valid JSON.'
+                    : undefined,
+            });
+            if (source === undefined)
+                return undefined;
+            if (source === BACK)
+                break;
+            value = parseVariationValue(type, source);
+            if (value !== undefined)
+                break;
+        }
+        if (value === undefined)
+            continue;
+        variations.push({ name, label, value });
+        if (variations.length === MAX_GUIDED_VARIATIONS)
+            break;
+        const another = await prompts.confirm({
+            message: 'Add another variation?',
+            default: variations.length < 2,
+            allowBack: true,
+        });
+        if (another === undefined)
+            return undefined;
+        if (another === BACK) {
+            variations.pop();
+            continue;
+        }
+        if (!another)
+            break;
+    }
+    return variations;
+}
+async function buildRules(prompts, variations) {
+    const addFirst = await prompts.confirm({
+        message: 'Add a targeting rule?',
+        default: false,
+        allowBack: true,
+    });
+    if (addFirst === undefined || addFirst === BACK)
+        return addFirst;
+    if (!addFirst)
+        return [];
+    const rules = [];
+    while (rules.length < MAX_GUIDED_RULES) {
+        const level = await prompts.select({
+            message: `Rule ${rules.length + 1} property`,
+            options: [
+                {
+                    value: 'installed_portal',
+                    label: 'Installed portal ID',
+                    description: 'Match portalId or installId',
+                },
+                {
+                    value: 'company',
+                    label: 'Company portal/install ID',
+                    description: 'Company allow-lists resolve to portal identity',
+                },
+                {
+                    value: 'contact',
+                    label: 'Contact identity',
+                    description: 'Match email or HubSpot user ID',
+                },
+                {
+                    value: 'actor',
+                    label: 'Actor identity',
+                    description: 'Match targeting key, email, or HubSpot user ID',
+                },
+            ],
+            allowBack: true,
+        });
+        if (level === undefined)
+            return undefined;
+        if (level === BACK) {
+            if (rules.length === 0)
+                return BACK;
+            rules.pop();
+            continue;
+        }
+        const operator = await prompts.select({
+            message: 'Targeting operator',
+            options: [
+                {
+                    value: 'is',
+                    label: 'is',
+                    description: 'Exact identity match (the bounded schema-supported operator)',
+                },
+            ],
+            default: 'is',
+            allowBack: true,
+        });
+        if (operator === undefined)
+            return undefined;
+        if (operator === BACK)
+            continue;
+        const matchKey = await wizardText(prompts, {
+            message: 'Target value',
+            allowBack: true,
+            validate: (value) => (value.length === 0 ? 'Enter a target value.' : undefined),
+        });
+        if (matchKey === undefined)
+            return undefined;
+        if (matchKey === BACK)
+            continue;
+        const served = await prompts.select({
+            message: 'Served variation',
+            options: variations.map((variation) => ({
+                value: variation.name,
+                label: `${variation.label} (${variation.name})`,
+            })),
+            allowBack: true,
+        });
+        if (served === undefined)
+            return undefined;
+        if (served === BACK)
+            continue;
+        rules.push({
+            id: `rule-${rules.length + 1}`,
+            level,
+            matchKeys: [matchKey],
+            variation: served,
+        });
+        if (rules.length === MAX_GUIDED_RULES)
+            break;
+        const another = await prompts.confirm({
+            message: 'Add another targeting rule?',
+            default: false,
+            allowBack: true,
+        });
+        if (another === undefined)
+            return undefined;
+        if (another === BACK) {
+            rules.pop();
+            continue;
+        }
+        if (!another)
+            break;
+    }
+    return rules;
+}
+function validateWizardReferences(definition) {
+    const names = definition.variations.map((variation) => variation.name);
+    if (names.length === 0)
+        return 'Define at least one variation.';
+    if (new Set(names).size !== names.length)
+        return 'Variation keys must be unique.';
+    if (!names.includes(definition.defaultVariation)) {
+        return 'The default variation must reference a defined variation.';
+    }
+    for (const rule of definition.rules) {
+        if (!rule.matchKeys || rule.matchKeys.length === 0)
+            return `Rule ${rule.id} needs a target value.`;
+        if (!rule.variation || !names.includes(rule.variation)) {
+            return `Rule ${rule.id} must reference a defined variation.`;
+        }
+    }
+    return undefined;
+}
+/** Build and submit a bounded typed definition using only schema-supported exact-match rules. */
+export async function runCreateWizard(input) {
+    const prompts = input.prompts ?? liveFlagsPrompts;
+    if (!prompts.isInteractive() || isMachineOutput()) {
+        return fail(input.reporter, false, 'Require --file <flag-definition.json> outside an interactive terminal.');
+    }
+    let key;
+    let label;
+    let type;
+    let state;
+    let variations;
+    let defaultVariation;
+    let rules;
+    let step = 0;
+    while (step < 7) {
+        if (step === 0) {
+            const answer = await wizardText(prompts, {
+                message: 'Flag key',
+                validate: (value) => /^[a-z0-9][a-z0-9-_]*$/.test(value)
+                    ? undefined
+                    : 'Use lowercase letters, numbers, hyphens, or underscores.',
+            });
+            if (answer === undefined || answer === BACK)
+                return cancelled(input.reporter);
+            key = answer;
+            step += 1;
+            continue;
+        }
+        if (step === 1) {
+            const answer = await wizardText(prompts, {
+                message: 'Flag label',
+                default: key
+                    .split(/[-_]/)
+                    .filter(Boolean)
+                    .map((part) => `${part[0]?.toUpperCase() ?? ''}${part.slice(1)}`)
+                    .join(' '),
+                allowBack: true,
+                validate: (value) => (value.length > 0 ? undefined : 'Enter a label.'),
+            });
+            if (answer === undefined)
+                return cancelled(input.reporter);
+            if (answer === BACK) {
+                step -= 1;
+                continue;
+            }
+            label = answer;
+            step += 1;
+            continue;
+        }
+        if (step === 2) {
+            const answer = await prompts.select({
+                message: 'Flag type',
+                options: [
+                    { value: 'boolean', label: 'Boolean' },
+                    { value: 'string', label: 'String' },
+                    { value: 'number', label: 'Number' },
+                    { value: 'json', label: 'JSON' },
+                ],
+                default: type ?? 'boolean',
+                allowBack: true,
+            });
+            if (answer === undefined)
+                return cancelled(input.reporter);
+            if (answer === BACK) {
+                step -= 1;
+                continue;
+            }
+            if (type !== answer) {
+                variations = undefined;
+                defaultVariation = undefined;
+                rules = undefined;
+            }
+            type = answer;
+            step += 1;
+            continue;
+        }
+        if (step === 3) {
+            const answer = await prompts.select({
+                message: 'Initial state',
+                options: [
+                    { value: 'disabled', label: 'Disabled', description: 'Serve the default variation' },
+                    { value: 'enabled', label: 'Enabled', description: 'Ready for evaluation' },
+                ],
+                default: state ?? 'disabled',
+                allowBack: true,
+            });
+            if (answer === undefined)
+                return cancelled(input.reporter);
+            if (answer === BACK) {
+                step -= 1;
+                continue;
+            }
+            state = answer;
+            step += 1;
+            continue;
+        }
+        if (step === 4) {
+            const answer = await buildVariations(prompts, type);
+            if (answer === undefined)
+                return cancelled(input.reporter);
+            if (answer === BACK) {
+                step -= 1;
+                continue;
+            }
+            variations = answer;
+            defaultVariation = undefined;
+            rules = undefined;
+            step += 1;
+            continue;
+        }
+        if (step === 5) {
+            const answer = await prompts.select({
+                message: 'Default variation',
+                options: (variations ?? []).map((variation) => ({
+                    value: variation.name,
+                    label: `${variation.label} (${variation.name})`,
+                })),
+                default: (defaultVariation ?? variations?.[0]?.name),
+                allowBack: true,
+            });
+            if (answer === undefined)
+                return cancelled(input.reporter);
+            if (answer === BACK) {
+                step -= 1;
+                continue;
+            }
+            defaultVariation = answer;
+            step += 1;
+            continue;
+        }
+        const answer = await buildRules(prompts, variations ?? []);
+        if (answer === undefined)
+            return cancelled(input.reporter);
+        if (answer === BACK) {
+            step -= 1;
+            continue;
+        }
+        rules = answer;
+        step += 1;
+    }
+    const updatedAt = (input.now ?? (() => new Date()))().toISOString();
+    let definition;
+    for (;;) {
+        const candidate = {
+            accountId: input.scope.accountId,
+            projectId: input.scope.projectId,
+            environment: input.scope.environment,
+            hubSpotAppId: input.scope.hubSpotAppId,
+            key,
+            label,
+            type,
+            state,
+            variations,
+            defaultVariation,
+            rules,
+            version: 1,
+            updatedAt,
+        };
+        const decoded = Schema.decodeUnknownEither(schemas.FlagDefinition)(candidate);
+        if (decoded._tag === 'Left') {
+            return fail(input.reporter, false, `Invalid flag definition: ${String(decoded.left)}`);
+        }
+        const referenceError = validateWizardReferences(decoded.right);
+        if (referenceError)
+            return fail(input.reporter, false, referenceError);
+        input.reporter.raw(`\nFlag definition preview\n${JSON.stringify(decoded.right, null, 2)}\n\nPercentage rollouts are available through --file only.\n\n`);
+        if (input.yes) {
+            definition = decoded.right;
+            break;
+        }
+        const confirmed = await prompts.confirm({
+            message: `Create or update flag "${decoded.right.key}"?`,
+            default: false,
+            allowBack: true,
+        });
+        if (confirmed === undefined || confirmed === false)
+            return cancelled(input.reporter);
+        if (confirmed === true) {
+            definition = decoded.right;
+            break;
+        }
+        // Esc from the final confirmation returns to the immediately preceding
+        // targeting-rule step without discarding the rest of the draft.
+        const revisedRules = await buildRules(prompts, variations ?? []);
+        if (revisedRules === undefined)
+            return cancelled(input.reporter);
+        if (revisedRules !== BACK)
+            rules = revisedRules;
+    }
+    const result = await input.client.defineFlag(definition);
+    input.reporter.raw(`Defined "${result.flag.key}" [${result.flag.type}, ${result.flag.state}, v${result.flag.version}] — synced ${result.syncedSnapshots} snapshot(s).\n`);
+    return { exitCode: 0 };
+}
+function cancelled(reporter) {
+    reporter.rawErr('Cancelled.\n');
+    return { exitCode: 130 };
+}
+const liveFlagMutationPrompts = {
+    isInteractive,
+    select: promptSelect,
+    confirm: promptConfirm,
+};
+export async function runSetState(input) {
+    const prompts = input.prompts ?? liveFlagMutationPrompts;
+    let key = resolveFlag(input.argv, '--key');
+    const canPrompt = !input.json && !isMachineOutput() && prompts.isInteractive();
+    // Deterministic machine/non-interactive validation must not touch the tenant
+    // transport merely to discover that a required mutation key is absent.
+    if (!key && !canPrompt) {
+        return fail(input.reporter, input.json, `Require --key <flagKey> to ${input.state} a flag.`);
+    }
+    const flags = await input.client.listFlags();
+    const candidates = flags.filter((flag) => flag.state !== 'archived' && flag.state !== input.state);
+    if (!key && canPrompt) {
+        if (candidates.length === 0) {
+            return fail(input.reporter, input.json, `No flags can be ${input.state}.`);
+        }
+        key = await prompts.select({
+            message: `Which flag should be ${input.state}?`,
+            options: candidates.map((flag) => ({
+                value: flag.key,
+                label: flag.label ? `${flag.label} (${flag.key})` : flag.key,
+                description: `${flag.type} · ${flag.state} · v${flag.version}`,
+            })),
+        });
+        if (!key) {
+            input.reporter.rawErr('Cancelled.\n');
+            return { exitCode: 130 };
+        }
+    }
+    if (!key) {
         return fail(input.reporter, input.json, `Require --key <flagKey> to ${input.state} a flag.`);
-    const existing = (await input.client.listFlags()).find((flag) => flag.key === key);
+    }
+    const existing = flags.find((flag) => flag.key === key);
     if (!existing)
         return fail(input.reporter, input.json, `Flag "${key}" not found.`);
+    if (existing.state === 'archived') {
+        return fail(input.reporter, input.json, `Flag "${key}" is archived and cannot transition.`);
+    }
+    if (existing.state === input.state) {
+        return fail(input.reporter, input.json, `Flag "${key}" is already ${input.state}.`);
+    }
+    if (input.state === 'archived' &&
+        !input.json &&
+        !input.yes &&
+        !isMachineOutput() &&
+        prompts.isInteractive()) {
+        const confirmed = await prompts.confirm({
+            message: `Archive flag "${key}"?`,
+            default: false,
+        });
+        if (confirmed !== true) {
+            input.reporter.rawErr('Cancelled.\n');
+            return { exitCode: 130 };
+        }
+    }
     const updated = {
         ...existing,
         state: input.state,
@@ -209,7 +938,7 @@ async function runSetState(input) {
 // and the handler fails with a silent `exitWith(1)` so `runHandler` does not
 // re-render. TODO(phase-5): reconcile these payloads with the standard envelope
 // once the dispatch swap lets the fixtures move in lockstep.
-const projectIdOption = Options.text('project-id').pipe(Options.optional);
+const projectIdOption = Options.text('project-id').pipe(Options.withAlias('project'), Options.optional);
 const appIdOption = Options.integer('app-id').pipe(Options.optional);
 const environmentOption = Options.text('environment').pipe(Options.optional);
 const envOption = Options.text('env').pipe(Options.optional);
@@ -220,6 +949,8 @@ const fileOption = Options.text('file').pipe(Options.optional);
 const keyOption = Options.text('key').pipe(Options.optional);
 const identityOptions = {
     json: jsonOption,
+    controlPlaneUrl: controlPlaneUrlOption,
+    accountId: accountIdOption,
     projectId: projectIdOption,
     appId: appIdOption,
     environment: environmentOption,
@@ -240,6 +971,13 @@ function failEff(json, message) {
         return yield* Effect.fail(exitWith(1));
     });
 }
+function cancelEff() {
+    return Effect.gen(function* () {
+        const reporter = yield* Reporter;
+        yield* reporter.rawErr('Cancelled.\n');
+        return yield* Effect.fail(exitWith(130));
+    });
+}
 /**
  * Synchronous reporter sink for the shared `runList`/`runCreate`/`runSetState`
  * bodies on the native path. These helpers emit verbatim bytes (the bespoke
@@ -247,40 +985,35 @@ function failEff(json, message) {
  * sanctioned I/O edge, instead of `process.std*`. Mode is derived solely from
  * `--json` so the produced bytes match the legacy path exactly.
  */
-const syncReporter = (json) => Effect.sync(() => createReporter({ command: 'flags', argv: json ? ['--json'] : [] }));
+const syncReporter = Effect.gen(function* () {
+    const reporter = yield* Reporter;
+    return reporter.implementation;
+});
 /**
- * Resolve the {@link FlagAuthoringClient} from options + env (mirrors the legacy
- * preamble). Reuses `loadTenantStateStore`/`createFlagAuthoringClient`; identity
- * env fallbacks are read through `Config`. Cloudflare creds resolve from
- * `--cloudflare-api-token` (reconstructed into a minimal argv) or env.
+ * Resolve the compatibility direct-to-tenant client. The CP-backed resolver
+ * below uses this only when no login is available or an explicit direct-mode
+ * runtime/Cloudflare option requests the legacy path.
  */
-function resolveClient(opts) {
+function resolveDirectClient(opts, config = {}) {
     return Effect.gen(function* () {
         const json = opts.json;
         const root = yield* Cwd;
         const envProjectId = yield* Config.string('HSX_PROJECT_ID')
             .pipe(Config.withDefault(''))
             .pipe(Effect.orDie);
-        const envAppId = yield* Config.string('HSX_APP_ID').pipe(Config.withDefault('')).pipe(Effect.orDie);
+        const envAppId = yield* Config.string('HSX_APP_ID')
+            .pipe(Config.withDefault(''))
+            .pipe(Effect.orDie);
+        const envHubSpotAppId = yield* Config.string('HSX_HUBSPOT_APP_ID')
+            .pipe(Config.withDefault(''))
+            .pipe(Effect.orDie);
         const envRuntimeBaseUrl = yield* Config.string('HSX_RUNTIME_BASE_URL')
             .pipe(Config.withDefault(''))
             .pipe(Effect.orDie);
-        const projectId = Option.getOrElse(opts.projectId, () => (envProjectId.length > 0 ? envProjectId : undefined));
-        const environment = Option.getOrElse(opts.environment, () => Option.getOrElse(opts.env, () => 'production'));
-        const appIdRaw = Option.match(opts.appId, {
-            onNone: () => (envAppId.length > 0 ? Number(envAppId) : undefined),
-            onSome: (value) => value,
-        });
-        const runtimeBaseUrl = Option.getOrElse(opts.runtimeOrigin, () => envRuntimeBaseUrl.length > 0 ? envRuntimeBaseUrl : undefined);
-        if (!projectId)
-            return yield* failEff(json, 'Require --project-id (or HSX_PROJECT_ID).');
-        if (appIdRaw === undefined || !Number.isInteger(appIdRaw)) {
-            return yield* failEff(json, 'Require an integer --app-id (or HSX_APP_ID).');
-        }
-        const hubSpotAppId = appIdRaw;
-        if (!runtimeBaseUrl) {
-            return yield* failEff(json, 'Require --runtime-origin (or HSX_RUNTIME_BASE_URL) — the deployed Worker URL.');
-        }
+        const envEnvironment = yield* Config.string('HSX_ENVIRONMENT')
+            .pipe(Config.withDefault(''))
+            .pipe(Effect.orDie);
+        const local = yield* Effect.promise(() => readLocalProjectContext(root));
         // loadTenantStateStore reads Cloudflare creds from argv-style flags or env;
         // forward an explicit --cloudflare-api-token when provided, else rely on env.
         const argv = Option.match(opts.cloudflareApiToken, {
@@ -292,33 +1025,171 @@ function resolveClient(opts) {
             catch: (cause) => cause,
         }).pipe(Effect.catchAll((cause) => failEff(json, cause instanceof Error ? cause.message : String(cause))));
         if (!context) {
-            return yield* failEff(json, 'No .hs-x/cloudflare.json found. Deploy this project first with `hs-x deploy`.');
+            return yield* failEff(json, 'No .hs-x/cloudflare.json found. Run `hs-x deploy` in this checkout first.');
         }
-        const binding = yield* Effect.tryPromise({
-            try: () => context.stateStore.getBinding({
-                projectId,
-                environment,
-                hubSpotAppId: hubSpotAppId,
+        const resolved = yield* Effect.tryPromise({
+            try: () => resolveFlagsContext({
+                stateStore: context.stateStore,
+                local,
+                explicitProjectId: Option.getOrUndefined(opts.projectId),
+                envProjectId: envProjectId || undefined,
+                explicitEnvironment: Option.getOrUndefined(opts.environment) ?? Option.getOrUndefined(opts.env),
+                envEnvironment: envEnvironment || undefined,
+                explicitAppId: Option.getOrUndefined(opts.appId),
+                envAppId: envAppId || undefined,
+                compatibilityEnvAppId: envHubSpotAppId || undefined,
+                explicitRuntimeOrigin: Option.getOrUndefined(opts.runtimeOrigin),
+                envRuntimeOrigin: envRuntimeBaseUrl || undefined,
+                allowPrompt: config.allowPrompt !== false && !json && !isMachineOutput() && isInteractive(),
             }),
             catch: (cause) => cause,
-        }).pipe(Effect.catchAll((cause) => failEff(json, cause instanceof Error ? cause.message : String(cause))));
-        if (!binding?.syncGrantSecretValue || !binding.tenantScopeAccountId) {
-            return yield* failEff(json, `No flag-authoring credentials for ${projectId}/${environment} (app ${hubSpotAppId}). Re-deploy as a linked project to provision the tenant data plane.`);
-        }
+        }).pipe(Effect.catchAll((cause) => cause instanceof FlagsPromptCancelled
+            ? cancelEff()
+            : failEff(json, cause instanceof Error ? cause.message : String(cause))));
         const scope = {
-            accountId: binding.tenantScopeAccountId,
-            projectId,
-            environment,
-            hubSpotAppId,
+            accountId: resolved.binding.tenantScopeAccountId,
+            projectId: resolved.projectId,
+            environment: resolved.environment,
+            hubSpotAppId: resolved.hubSpotAppId,
         };
         const client = createFlagAuthoringClient({
-            runtimeBaseUrl,
-            grantSecret: binding.syncGrantSecretValue,
+            runtimeBaseUrl: resolved.runtimeBaseUrl,
+            grantSecret: resolved.binding.syncGrantSecretValue,
             scope,
         });
         return { client, scope };
     });
 }
+/**
+ * CP-first context discovery. A stored login selects the authoritative account
+ * project catalog and redacted runtime-binding collection; the returned client
+ * writes only through the existing control-plane flag conduit.
+ */
+function resolveClient(opts, config = {}) {
+    return Effect.gen(function* () {
+        const root = yield* Cwd;
+        const local = yield* Effect.promise(() => readLocalProjectContext(root));
+        const accounts = yield* AccountStore;
+        const stored = yield* accounts.load;
+        const envAccountId = yield* Config.string('HSX_ACCOUNT_ID')
+            .pipe(Config.withDefault(''))
+            .pipe(Effect.orDie);
+        const envProjectId = yield* Config.string('HSX_PROJECT_ID')
+            .pipe(Config.withDefault(''))
+            .pipe(Effect.orDie);
+        const envEnvironment = yield* Config.string('HSX_ENVIRONMENT')
+            .pipe(Config.withDefault(''))
+            .pipe(Effect.orDie);
+        const envAppId = yield* Config.string('HSX_APP_ID')
+            .pipe(Config.withDefault(''))
+            .pipe(Effect.orDie);
+        const compatibilityEnvAppId = yield* Config.string('HSX_HUBSPOT_APP_ID')
+            .pipe(Config.withDefault(''))
+            .pipe(Effect.orDie);
+        const envRuntimeOrigin = yield* Config.string('HSX_RUNTIME_BASE_URL')
+            .pipe(Config.withDefault(''))
+            .pipe(Effect.orDie);
+        const envControlPlaneUrl = yield* Config.string('HSX_CONTROL_PLANE_URL')
+            .pipe(Config.withDefault(''))
+            .pipe(Effect.orDie);
+        const forceDirect = Option.isSome(opts.runtimeOrigin) ||
+            Option.isSome(opts.cloudflareApiToken) ||
+            envRuntimeOrigin.length > 0;
+        const session = activeSession(stored);
+        if (forceDirect || !session)
+            return yield* resolveDirectClient(opts, config);
+        const explicitAccountId = Option.getOrUndefined(opts.accountId);
+        const accountId = resolveAccountId({
+            ...(explicitAccountId ? { explicitAccountId } : {}),
+            ...(envAccountId ? { envAccountId } : {}),
+            ...(local.projectBinding?.accountId
+                ? { localAccountId: local.projectBinding.accountId }
+                : {}),
+            ...(stored.defaultAccountId ? { defaultAccountId: stored.defaultAccountId } : {}),
+        });
+        if (!accountId) {
+            return yield* failEff(opts.json, 'Flags require an HS-X account: run `hs-x login`, or pass --account-id / HSX_ACCOUNT_ID.');
+        }
+        const controlPlaneUrl = Option.getOrUndefined(opts.controlPlaneUrl) ??
+            (envControlPlaneUrl || DEFAULT_CONTROL_PLANE_URL);
+        const cp = yield* ControlPlaneClient;
+        const controlPlane = {
+            request: (request) => Effect.runPromise(cp.fetch({
+                controlPlaneUrl,
+                path: request.path,
+                ...(request.method ? { method: request.method } : {}),
+                ...(request.body === undefined ? {} : { body: request.body }),
+            })),
+        };
+        const allowPrompt = config.allowPrompt !== false && !opts.json && !isMachineOutput() && isInteractive();
+        const resolved = yield* Effect.tryPromise({
+            try: async () => {
+                const explicitProjectId = Option.getOrUndefined(opts.projectId) ?? (envProjectId || undefined);
+                const projects = await discoverProjects({ accountId, controlPlane });
+                const project = await resolveProjectSelection({
+                    accountId,
+                    projects,
+                    ...(explicitProjectId ? { explicitProjectId } : {}),
+                    ...(local.projectBinding?.projectId
+                        ? { localProjectId: local.projectBinding.projectId }
+                        : {}),
+                    allowPrompt,
+                    prompts: liveFlagsPrompts,
+                    message: 'Which project do you want to manage flags for?',
+                });
+                const bindings = await discoverProjectRuntimeBindings({
+                    accountId,
+                    projectId: project.id,
+                    controlPlane,
+                });
+                const appIdRaw = envAppId || compatibilityEnvAppId || undefined;
+                const explicitAppId = Option.getOrUndefined(opts.appId) ??
+                    (appIdRaw === undefined ? undefined : Number(appIdRaw));
+                if (explicitAppId !== undefined &&
+                    (!Number.isInteger(explicitAppId) || explicitAppId <= 0)) {
+                    throw new Error('Require a valid integer --app-id (or HSX_APP_ID).');
+                }
+                const binding = await resolveRuntimeBinding({
+                    project,
+                    bindings,
+                    ...((Option.getOrUndefined(opts.environment) ??
+                        Option.getOrUndefined(opts.env) ??
+                        (envEnvironment || undefined))
+                        ? {
+                            explicitEnvironment: Option.getOrUndefined(opts.environment) ??
+                                Option.getOrUndefined(opts.env) ??
+                                envEnvironment,
+                        }
+                        : {}),
+                    ...(explicitAppId === undefined ? {} : { explicitAppId }),
+                    ...(local.hubSpotBinding?.appId ? { localAppId: local.hubSpotBinding.appId } : {}),
+                    allowPrompt,
+                    prompts: liveFlagsPrompts,
+                });
+                const scope = {
+                    accountId,
+                    projectId: project.id,
+                    environment: binding.environment,
+                    hubSpotAppId: binding.hubSpotAppId,
+                };
+                return {
+                    client: createControlPlaneFlagAuthoringClient({
+                        accountId,
+                        projectId: project.id,
+                        environment: binding.environment,
+                        hubSpotAppId: binding.hubSpotAppId,
+                        controlPlane,
+                    }),
+                    scope,
+                };
+            },
+            catch: (cause) => cause,
+        }).pipe(Effect.catchAll((cause) => cause instanceof ProjectPickerCancelled
+            ? cancelEff()
+            : failEff(opts.json, cause instanceof Error ? cause.message : String(cause))));
+        return resolved;
+    });
+}
 /**
  * Map a thrown `RuntimeFlagAuthoringError`/`Error` to the legacy bespoke
  * failure. A `CliError` (an already-rendered `failEff`) is re-raised untouched;
@@ -333,11 +1204,13 @@ function withClientErrors(json, body) {
 }
 const flagsListCmd = Command.make('list', { ...identityOptions, limit: limitOption }, (opts) => runHandler('flags', { json: opts.json }, Effect.gen(function* () {
     const { client } = yield* resolveClient(opts);
-    const reporter = yield* syncReporter(opts.json);
+    const reporter = yield* syncReporter;
     const limit = Option.getOrUndefined(opts.limit);
     yield* withClientErrors(opts.json, Effect.tryPromise({
         try: () => runList({
-            argv: limit !== undefined ? ['flags', 'list', '--limit', String(limit)] : ['flags', 'list'],
+            argv: limit !== undefined
+                ? ['flags', 'list', '--limit', String(limit)]
+                : ['flags', 'list'],
             json: opts.json,
             client,
             reporter,
@@ -346,11 +1219,22 @@ const flagsListCmd = Command.make('list', { ...identityOptions, limit: limitOpti
     }).pipe(Effect.asVoid));
 })));
 function makeCreateCmd(name) {
-    return Command.make(name, { ...identityOptions, file: fileOption }, (opts) => runHandler('flags', { json: opts.json }, Effect.gen(function* () {
-        const { client, scope } = yield* resolveClient(opts);
+    return Command.make(name, { ...identityOptions, file: fileOption, yes: yesOption }, (opts) => runHandler('flags', { json: opts.json }, Effect.gen(function* () {
         const file = Option.getOrUndefined(opts.file);
+        const wizardAllowed = !opts.json && !isMachineOutput() && isInteractive();
+        if (!file && !wizardAllowed) {
+            return yield* failEff(opts.json, 'Require --file <flag-definition.json> for `flags create` outside an interactive terminal.');
+        }
+        // A definition file is authoritative and never opens context/wizard
+        // pickers. If its scope is ambiguous, report the required identity flag.
+        const { client, scope } = yield* resolveClient(opts, { allowPrompt: !file });
+        const reporter = yield* syncReporter;
         if (!file) {
-            return yield* failEff(opts.json, 'Require --file <flag-definition.json> for `flags create`.');
+            yield* withClientErrors(opts.json, Effect.tryPromise({
+                try: () => runCreateWizard({ client, scope, reporter, yes: opts.yes }),
+                catch: (cause) => cause,
+            }).pipe(Effect.flatMap((result) => result.exitCode === 0 ? Effect.void : Effect.fail(exitWith(result.exitCode)))));
+            return;
         }
         // Read via FileSystem (no node:fs); a read failure mirrors the legacy
         // "could not read/parse" bespoke failure.
@@ -359,17 +1243,26 @@ function makeCreateCmd(name) {
         if (source._tag === 'Left') {
             return yield* failEff(opts.json, `Could not read/parse ${file}: ${String(source.left.cause)}`);
         }
-        const reporter = yield* syncReporter(opts.json);
-        yield* withClientErrors(opts.json, runCreateFromSource({ source: source.right, file, json: opts.json, client, scope, reporter }));
+        yield* withClientErrors(opts.json, runCreateFromSource({
+            source: source.right,
+            file,
+            json: opts.json,
+            client,
+            scope,
+            reporter,
+        }));
     })));
 }
 const flagsCreateCmd = makeCreateCmd('create');
 const flagsDefineCmd = makeCreateCmd('define');
 function makeSetStateCmd(name, state) {
-    return Command.make(name, { ...identityOptions, key: keyOption }, (opts) => runHandler('flags', { json: opts.json }, Effect.gen(function* () {
-        const { client } = yield* resolveClient(opts);
-        const reporter = yield* syncReporter(opts.json);
+    return Command.make(name, { ...identityOptions, key: keyOption, yes: yesOption }, (opts) => runHandler('flags', { json: opts.json }, Effect.gen(function* () {
         const key = Option.getOrUndefined(opts.key);
+        if (key === undefined && (isMachineOutput() || !isInteractive())) {
+            return yield* failEff(opts.json, `Require --key <flagKey> to ${state} a flag.`);
+        }
+        const { client } = yield* resolveClient(opts);
+        const reporter = yield* syncReporter;
         yield* withClientErrors(opts.json, Effect.tryPromise({
             try: () => runSetState({
                 argv: key !== undefined ? ['flags', name, '--key', key] : ['flags', name],
@@ -377,15 +1270,43 @@ function makeSetStateCmd(name, state) {
                 client,
                 state,
                 reporter,
+                yes: opts.yes,
             }),
             catch: (cause) => cause,
-        }).pipe(Effect.asVoid));
+        }).pipe(Effect.flatMap((result) => result.exitCode === 0 ? Effect.void : Effect.fail(exitWith(result.exitCode)))));
     })));
 }
 const flagsEnableCmd = makeSetStateCmd('enable', 'enabled');
 const flagsDisableCmd = makeSetStateCmd('disable', 'disabled');
 const flagsArchiveCmd = makeSetStateCmd('archive', 'archived');
-export const flagsCmd = Command.make('flags').pipe(Command.withSubcommands([
+const bareFlagsCmd = Command.make('flags', { ...identityOptions, yes: yesOption }, (opts) => runHandler('flags', { json: opts.json }, Effect.gen(function* () {
+    if (opts.json || isMachineOutput() || !isInteractive()) {
+        return yield* failEff(opts.json, 'Bare `hs-x flags` requires an interactive terminal. Choose list, create, enable, disable, or archive.');
+    }
+    const action = yield* Effect.promise(() => selectFlagsAction());
+    if (action === undefined)
+        return yield* cancelEff();
+    const { client, scope } = yield* resolveClient(opts);
+    const reporter = yield* syncReporter;
+    const operation = action === 'list'
+        ? () => runList({ argv: ['flags', 'list'], json: false, client, reporter })
+        : action === 'create'
+            ? () => runCreateWizard({ client, scope, reporter, yes: opts.yes })
+            : () => runSetState({
+                argv: ['flags', action],
+                json: false,
+                client,
+                state: action === 'enable'
+                    ? 'enabled'
+                    : action === 'disable'
+                        ? 'disabled'
+                        : 'archived',
+                reporter,
+                yes: opts.yes,
+            });
+    yield* withClientErrors(false, Effect.tryPromise({ try: operation, catch: (cause) => cause }).pipe(Effect.flatMap((result) => result.exitCode === 0 ? Effect.void : Effect.fail(exitWith(result.exitCode)))));
+})));
+export const flagsCmd = bareFlagsCmd.pipe(Command.withSubcommands([
     flagsListCmd,
     flagsCreateCmd,
     flagsDefineCmd,