@sitecoreai-labs/sitecoreai-cli 0.0.4 → 0.1.0

package/dist/cli.js

@@ -4,29 +4,21 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-const commander_1 = require("commander");
 const package_json_1 = __importDefault(require("../package.json"));
-const serialization_1 = require("./commands/serialization");
+const program_1 = require("./program");
 const shared_1 = require("./commands/shared");
-const status_1 = require("./commands/status");
-const login_1 = require("./commands/login");
-const deploy_1 = require("./commands/deploy");
-const history_1 = require("./commands/history");
-const init_1 = require("./commands/init");
-const logout_1 = require("./commands/logout");
-const shell_1 = require("./commands/shell");
-const history_2 = require("./shared/history");
+const history_1 = require("./shared/history");
 const style_1 = require("./shared/style");
 const logger_1 = require("./shared/logger");
 const telemetry_1 = require("./shared/telemetry");
 const output_1 = require("./shared/output");
 const redact_1 = require("./shared/redact");
 const errors_1 = require("./shared/errors");
-const config_1 = require("./commands/config");
-const telemetry_2 = require("./commands/telemetry");
-const config_2 = require("./config");
-const tasks_1 = require("./serialization/tasks");
+const root_config_1 = require("./config/root-config");
+const deploy_token_1 = require("./serialization/tasks/env/deploy-token");
+const init_1 = require("./serialization/tasks/env/init");
 const keychain_1 = require("./shared/keychain");
+const transport_spinner_1 = require("./deploy/tasks/transport-spinner");
 const toBoolean = (value) => {
     if (!value) {
         return undefined;
@@ -40,15 +32,24 @@ const toBoolean = (value) => {
     }
     return undefined;
 };
+/**
+ * Decide whether the cached deploy token has expired, for the
+ * auto-wizard's re-login prompt. Per `docs/credentials.md` the token's
+ * freshness metadata (`deployTokenExpiresIn` / `deployTokenLastUpdated`)
+ * lives on the env profile in the config file — the config holds every
+ * credential's and token's non-secret metadata. Reads only those fields.
+ */
 const isDeployTokenExpired = (env) => {
-    if (!env?.deployTokenExpiresIn || !env.deployTokenLastUpdated) {
+    const expiresIn = env?.deployTokenExpiresIn;
+    const lastUpdatedRaw = env?.deployTokenLastUpdated;
+    if (!expiresIn || !lastUpdatedRaw) {
         return false;
     }
-    const lastUpdated = Date.parse(env.deployTokenLastUpdated);
+    const lastUpdated = Date.parse(lastUpdatedRaw);
     if (Number.isNaN(lastUpdated)) {
         return false;
     }
-    return Date.now() >= lastUpdated + env.deployTokenExpiresIn * 1000;
+    return Date.now() >= lastUpdated + expiresIn * 1000;
 };
 const resolveEnvironmentNameFromArgs = (args) => {
     const index = args.findIndex((arg) => arg === "--environment-name" || arg === "-n");
@@ -68,8 +69,22 @@ const shouldSkipAutoWizard = (args) => {
     if (args.some((arg) => ["--help", "-h", "--version", "-V"].includes(arg))) {
         return true;
     }
-    const commandName = args[0];
-    if (["init", "login", "logout", "telemetry", "config", "history"].includes(commandName)) {
+    // Commands that must not trigger auto-init/auto-login. Most now live
+    // under the `setup` and `cli` parents, so match the [parent, child]
+    // pair; `mcp` stayed top-level.
+    const [parent, child] = args;
+    if (parent === "mcp") {
+        return true;
+    }
+    // `policy` manages the workspace guardrails — it must not trigger
+    // auto-init/auto-login (e.g. `scai policy show` on an unconfigured dir).
+    if (parent === "policy") {
+        return true;
+    }
+    if (parent === "setup" && ["init", "login", "logout", "client"].includes(child)) {
+        return true;
+    }
+    if (parent === "cli" && ["telemetry", "config", "history"].includes(child)) {
         return true;
     }
     return false;
@@ -78,22 +93,22 @@ const resolveAutoWizardNeed = async (args, configBasePath) => {
     const envFromArgs = resolveEnvironmentNameFromArgs(args);
     let configFile = null;
     try {
-        configFile = (0, config_2.readRootConfigurationFile)(configBasePath);
+        configFile = (0, root_config_1.readRootConfigurationFile)(configBasePath);
     }
     catch (error) {
-        const cliError = (0, errors_1.toCliError)(error);
+        const cliError = (0, errors_1.toScaiError)(error);
         if (cliError.code === "CONFIG_NOT_FOUND") {
             return {
                 kind: "init",
                 envName: envFromArgs,
-                hint: "Run 'scai init' to create a configuration file.",
+                hint: "Run 'scai setup init' to create a configuration file.",
             };
         }
         if (cliError.code === "CONFIG_INVALID") {
             return {
                 kind: "init",
                 envName: envFromArgs,
-                hint: "Run 'scai init' to repair the configuration file.",
+                hint: "Run 'scai setup init' to repair the configuration file.",
             };
         }
         return null;
@@ -104,7 +119,7 @@ const resolveAutoWizardNeed = async (args, configBasePath) => {
         return {
             kind: "init",
             envName: envFromArgs,
-            hint: "Run 'scai init' to configure an environment.",
+            hint: "Run 'scai setup init' to configure an environment.",
         };
     }
     const envName = envFromArgs ??
@@ -114,21 +129,24 @@ const resolveAutoWizardNeed = async (args, configBasePath) => {
         return {
             kind: "init",
             envName,
-            hint: "Run 'scai init' to configure an environment.",
+            hint: "Run 'scai setup init' to configure an environment.",
         };
     }
+    // Resolve the full config once so a CONFIG_INVALID profile routes to
+    // the init-repair path, and so the env profile's deploy-token
+    // freshness metadata is available below.
     let resolvedEnv;
     try {
-        const root = (0, config_2.readRootConfiguration)(configBasePath, envName);
-        resolvedEnv = root.environments[envName] ?? envProfiles[envName];
+        const resolvedRoot = (0, root_config_1.readRootConfiguration)(configBasePath, envName);
+        resolvedEnv = resolvedRoot.environments[envName];
     }
     catch (error) {
-        const cliError = (0, errors_1.toCliError)(error);
+        const cliError = (0, errors_1.toScaiError)(error);
         if (cliError.code === "CONFIG_INVALID") {
             return {
                 kind: "init",
                 envName,
-                hint: "Run 'scai init' to repair the configuration file.",
+                hint: "Run 'scai setup init' to repair the configuration file.",
             };
         }
         return null;
@@ -142,7 +160,7 @@ const resolveAutoWizardNeed = async (args, configBasePath) => {
         return {
             kind: "login",
             envName,
-            hint: `Run 'scai login -n ${envName}' to authenticate.`,
+            hint: `Run 'scai setup login -n ${envName}' to authenticate.`,
         };
     }
     return null;
@@ -177,7 +195,7 @@ const runAutoWizardIfNeeded = async (args, configPath, outputOptions) => {
     }
     if (need.kind === "init") {
         logger.info("Launching setup wizard to configure SitecoreAI.", "cyan");
-        await (0, tasks_1.runInit)({
+        await (0, init_1.runInit)({
             config: configBasePath,
             environmentName: need.envName,
             wizard: true,
@@ -185,30 +203,7 @@ const runAutoWizardIfNeeded = async (args, configPath, outputOptions) => {
         return;
     }
     logger.info(`Authenticating environment '${need.envName}'.`, "cyan");
-    await (0, tasks_1.runDeployToken)({ config: configBasePath, environmentName: need.envName });
-};
-const createProgram = (runCli, options = {}) => {
-    const program = new commander_1.Command();
-    program
-        .name("scai")
-        .description("SitecoreAI Deploy & Sync CLI for serialization and deploy workflows")
-        .version(package_json_1.default.version, "-V, --version", "Display the CLI version");
-    program.addCommand((0, config_1.createConfigCommand)());
-    program.addCommand((0, deploy_1.createDeployCommand)());
-    program.addCommand((0, history_1.createHistoryCommand)());
-    program.addCommand((0, init_1.createInitCommand)());
-    program.addCommand((0, login_1.createLoginCommand)());
-    program.addCommand((0, logout_1.createLogoutCommand)());
-    program.addCommand((0, serialization_1.createSerializationCommand)());
-    program.addCommand((0, status_1.createStatusCommand)());
-    program.addCommand((0, telemetry_2.createTelemetryCommand)());
-    program.addCommand((0, shell_1.createShellCommand)(runCli));
-    program.showHelpAfterError(true);
-    program.showSuggestionAfterError(true);
-    if (options.shellMode) {
-        program.exitOverride();
-    }
-    return program;
+    await (0, deploy_token_1.runDeployToken)({ config: configBasePath, environmentName: need.envName });
 };
 const runCli = async (inputArgv, options = {}) => {
     const argv = (0, shared_1.normalizeArgs)(inputArgv);
@@ -234,15 +229,23 @@ const runCli = async (inputArgv, options = {}) => {
     if (args.includes("--trace") || args.includes("-t")) {
         process.env.SITECOREAI_TRACE_HTTP = "1";
     }
+    // Bridge `--verbose` to an env flag so layers without a Logger (e.g. the
+    // config loader) can surface diagnostics — see announceResolvedConfigPath.
+    if (args.includes("--verbose") || args.includes("-v")) {
+        process.env.SITECOREAI_VERBOSE = "1";
+    }
+    // The Deploy transport (`deployRequest`) stays silent for SDK
+    // consumers; this is the CLI opting in to a spinner + HTTP trace.
+    (0, transport_spinner_1.installDeployTransportSpinner)();
     if (!options.skipBanner) {
         (0, style_1.showBanner)(package_json_1.default.version);
     }
-    const program = createProgram(runCli, { shellMode: options.shellMode });
+    const program = (0, program_1.createProgram)(runCli, { shellMode: options.shellMode });
     try {
         await runAutoWizardIfNeeded(args, configPath, outputOptions);
-        await (0, telemetry_1.ensureTelemetryConsent)(telemetryConfigPath);
-        void Promise.resolve((0, history_2.ensureHistoryFile)()).catch(() => { });
-        void Promise.resolve((0, history_2.recordHistory)({
+        await (0, telemetry_1.ensureTelemetryNotice)(telemetryConfigPath);
+        void Promise.resolve((0, history_1.ensureHistoryFile)()).catch(() => { });
+        void Promise.resolve((0, history_1.recordHistory)({
             event: "start",
             command,
             args,
@@ -255,7 +258,7 @@ const runCli = async (inputArgv, options = {}) => {
             configPath: telemetryConfigPath,
         })).catch(() => { });
         await program.parseAsync(argv);
-        await (0, history_2.recordHistory)({
+        await (0, history_1.recordHistory)({
             event: "success",
             command,
             args,
@@ -283,7 +286,7 @@ const runCli = async (inputArgv, options = {}) => {
             process.exitCode = 0;
             return;
         }
-        void Promise.resolve((0, history_2.recordHistory)({
+        void Promise.resolve((0, history_1.recordHistory)({
             event: "error",
             command,
             args,
@@ -299,7 +302,7 @@ const runCli = async (inputArgv, options = {}) => {
             configPath: telemetryConfigPath,
         })).catch(() => { });
         const baseLogger = new logger_1.Logger(false, false, Boolean(outputOptions.json), Boolean(outputOptions.quiet), outputOptions.logFile ?? process.env.SITECOREAI_LOG_FILE);
-        const cliError = (0, errors_1.toCliError)(error);
+        const cliError = (0, errors_1.toScaiError)(error);
         const redactedMessage = (0, redact_1.redactSecrets)(cliError.message);
         const finalError = cliError;
         if (baseLogger.isJson()) {
@@ -308,6 +311,7 @@ const runCli = async (inputArgv, options = {}) => {
                 code: finalError.code,
                 hint: finalError.hint,
                 details: finalError.details,
+                remediation: finalError.remediation,
                 exitCode: finalError.exitCode,
             });
         }
@@ -321,6 +325,10 @@ const runCli = async (inputArgv, options = {}) => {
             if (finalError.hint) {
                 baseLogger.warn(`Hint: ${finalError.hint}`);
             }
+            if (finalError.remediation) {
+                const { actor, fix, detail } = finalError.remediation;
+                baseLogger.warn(`Fix (${actor}): ${fix}${detail ? ` — ${detail}` : ""}`);
+            }
         }
         process.exitCode = finalError.exitCode;
     }
@@ -340,7 +348,20 @@ const runCli = async (inputArgv, options = {}) => {
 // drive `runCli` directly, and `process.exit` inside a test worker
 // surfaces as an "Uncaught Exception" failure. `process.env.VITEST`
 // is set automatically by Vitest's runner.
-const shouldForceExit = !process.env.VITEST;
+//
+// Skipped for `scai mcp serve` (either transport): the MCP server is a
+// long-lived process — stdio holds stdin open, http holds a listener
+// open — so the natural exit path is the client hanging up or a
+// signal, never a force-exit the instant the command's promise
+// settles. Detected from argv: `installMcpStdoutDiscipline()` sets
+// `SITECOREAI_MCP_SERVE` inside the command action, which is too late
+// to be read at this module-eval point (it only lands in time when a
+// parent process — smoke / integration harness — exports it).
+const isMcpServeInvocation = (argv) => {
+    const positionals = argv.slice(2).filter((arg) => !arg.startsWith("-"));
+    return positionals[0] === "mcp" && positionals[1] === "serve";
+};
+const shouldForceExit = !process.env.VITEST && !process.env.SITECOREAI_MCP_SERVE && !isMcpServeInvocation(process.argv);
 const cliPromise = runCli(process.argv);
 if (shouldForceExit) {
     void cliPromise.finally(() => {

package/dist/commands/agents/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `scai agents …` — Sitecore Agentic Studio.
+ *
+ * The command tree is organized by resource: `agent`, `space`, `skill`,
+ * `widget`, `schema`, `mcp`, `html-template`, and `tool` are each a
+ * subcommand group, plus session management (`login` / `logout` /
+ * `status`) and the declarative `sync` path.
+ *
+ *   agents
+ *     login | logout | status
+ *     agent          {list, get, create, update, delete, duplicate, run}
+ *     space          {get, artifacts, update}
+ *     skill          {list, get, create, update, delete}
+ *     widget         {list, get, create, update, delete}
+ *     schema         {list, get, create, update, delete*}
+ *     mcp            {list, get, create, update*, delete}
+ *     html-template  {list, get, create, update*, delete*}
+ *     tool           {list}
+ *     sync           {pull, diff, push}
+ *
+ * Write support was verified live 2026-05-17 (agentic-studio-euw). `agent`,
+ * `skill`, and `widget` have full CRUD; `schema` adds `update` (a re-POST
+ * upsert); `mcp` adds `delete`. The starred ops (*) are UNVERIFIED — they
+ * return 405/404 and stay gated behind `--unverified` — see
+ * docs/agentic-studio-har-capture.md.
+ */
+import { Command } from "commander";
+export declare const createAgentsCommand: () => Command;

package/dist/commands/agents/index.js

@@ -0,0 +1,289 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAgentsCommand = void 0;
+/**
+ * `scai agents …` — Sitecore Agentic Studio.
+ *
+ * The command tree is organized by resource: `agent`, `space`, `skill`,
+ * `widget`, `schema`, `mcp`, `html-template`, and `tool` are each a
+ * subcommand group, plus session management (`login` / `logout` /
+ * `status`) and the declarative `sync` path.
+ *
+ *   agents
+ *     login | logout | status
+ *     agent          {list, get, create, update, delete, duplicate, run}
+ *     space          {get, artifacts, update}
+ *     skill          {list, get, create, update, delete}
+ *     widget         {list, get, create, update, delete}
+ *     schema         {list, get, create, update, delete*}
+ *     mcp            {list, get, create, update*, delete}
+ *     html-template  {list, get, create, update*, delete*}
+ *     tool           {list}
+ *     sync           {pull, diff, push}
+ *
+ * Write support was verified live 2026-05-17 (agentic-studio-euw). `agent`,
+ * `skill`, and `widget` have full CRUD; `schema` adds `update` (a re-POST
+ * upsert); `mcp` adds `delete`. The starred ops (*) are UNVERIFIED — they
+ * return 405/404 and stay gated behind `--unverified` — see
+ * docs/agentic-studio-har-capture.md.
+ */
+const commander_1 = require("commander");
+const tasks_1 = require("../../agents/tasks");
+const cli_tasks_1 = require("../../shared/cli-tasks");
+const shared_1 = require("../shared");
+const sync_1 = require("./sync");
+// ---- shared option helpers ------------------------------------------------
+/** Attach the env / config / verbosity options every `agents` command needs. */
+const addBaseOptions = (command) => {
+    (0, shared_1.addEnvironmentOption)(command);
+    (0, shared_1.addConfigOption)(command);
+    (0, shared_1.addVerbosityOptions)(command);
+    return command;
+};
+/** The opt-in flag for an UNVERIFIED write (update / delete on a Part-B kind). */
+const addUnverifiedOption = (command) => command.addOption(new commander_1.Option("--unverified", "Attempt this UNVERIFIED write — its endpoint is not confirmed (see docs/agentic-studio-har-capture.md)."));
+/** A `-f, --file` recipe-file option, mandatory. */
+const fileOption = (resource) => new commander_1.Option("-f, --file <path>", `Path to a ${resource} recipe file (YAML or JSON) — same format as \`scai agents sync\`.`).makeOptionMandatory(true);
+// ---- session --------------------------------------------------------------
+const createLoginCommand = () => {
+    const command = new commander_1.Command("login").description("Capture an Agentic Studio browser session for the environment (opens a browser).");
+    addBaseOptions(command);
+    command.addOption(new commander_1.Option("--region <region>", "Agentic Studio region (default: resolved from the environment's organization)"));
+    command.action(async (options) => {
+        await (0, tasks_1.runAgentsLogin)(options);
+    });
+    return command;
+};
+const createSessionCommand = (name, description, run) => {
+    const command = addBaseOptions(new commander_1.Command(name).description(description));
+    command.action(async (options) => {
+        await run(options);
+    });
+    return command;
+};
+// ---- agent group (full, verified CRUD) ------------------------------------
+const createAgentGroup = () => {
+    const group = new commander_1.Command("agent").description("Agentic Studio agents — full create / read / update / delete.");
+    const list = addBaseOptions(new commander_1.Command("list").description("List agents."));
+    list.action(async (options) => {
+        await (0, tasks_1.runAgentList)(options);
+    });
+    const get = addBaseOptions(new commander_1.Command("get").description("Show one agent.").argument("<idOrSlug>", "Agent id or slug"));
+    get.action(async (idOrSlug, options) => {
+        await (0, tasks_1.runAgentGet)({ ...options, idOrSlug });
+    });
+    const create = addBaseOptions(new commander_1.Command("create").description("Create an agent from a recipe file."));
+    create.addOption(fileOption("agent"));
+    (0, shared_1.addApplyOption)(create);
+    (0, shared_1.addWhatIfOption)(create);
+    create.action((0, shared_1.withApplyGate)(async (options) => {
+        await (0, tasks_1.runAgentCreate)(options);
+    }));
+    const update = addBaseOptions(new commander_1.Command("update")
+        .description("Update an agent from a recipe file (full-replacement of config).")
+        .argument("<idOrSlug>", "Agent id or slug"));
+    update.addOption(fileOption("agent"));
+    (0, shared_1.addApplyOption)(update);
+    (0, shared_1.addWhatIfOption)(update);
+    update.action(async (idOrSlug, options) => {
+        await (0, shared_1.withApplyGate)(async (opts) => {
+            await (0, tasks_1.runAgentUpdate)({ ...opts, idOrSlug });
+        })(options);
+    });
+    const duplicate = addBaseOptions(new commander_1.Command("duplicate")
+        .description("Duplicate an agent under a new name.")
+        .argument("<idOrSlug>", "Agent id or slug of the source")
+        .addOption(new commander_1.Option("--name <name>", "Name for the new agent").makeOptionMandatory(true)));
+    (0, shared_1.addApplyOption)(duplicate);
+    (0, shared_1.addWhatIfOption)(duplicate);
+    duplicate.action(async (idOrSlug, options) => {
+        await (0, shared_1.withApplyGate)(async (opts) => {
+            await (0, tasks_1.runAgentDuplicate)({ ...opts, idOrSlug });
+        })(options);
+    });
+    const del = addBaseOptions(new commander_1.Command("delete")
+        .description("Delete an agent. Requires --apply; non-TTY callers must also pass --force.")
+        .argument("<idOrSlug>", "Agent id or slug")
+        .addOption(new commander_1.Option("--force", "Skip the TTY confirmation prompt (required for non-TTY agents).")));
+    (0, shared_1.addApplyOption)(del);
+    (0, shared_1.addWhatIfOption)(del);
+    del.action(async (idOrSlug, options) => {
+        await (0, shared_1.withApplyGate)(async (opts) => {
+            if (!opts.whatIf) {
+                const confirmed = await (0, cli_tasks_1.confirmDestructive)(`Delete agent "${idOrSlug}"? This cannot be undone.`, opts.force);
+                if (!confirmed) {
+                    process.stderr.write("Aborted.\n");
+                    return;
+                }
+            }
+            await (0, tasks_1.runAgentDelete)({ ...opts, idOrSlug });
+        })(options);
+    });
+    const run = addBaseOptions(new commander_1.Command("run")
+        .description("Run an agent and stream its output.")
+        .argument("<agentSlug>", "Slug of the agent to run")
+        .requiredOption("-m, --message <text>", "Message to send to the agent"));
+    run.action(async (agentSlug, options) => {
+        await (0, tasks_1.runAgentRun)({ ...options, agentSlug, message: options.message });
+    });
+    group.addCommand(list, { isDefault: true });
+    group.addCommand(get);
+    group.addCommand(create);
+    group.addCommand(update);
+    group.addCommand(duplicate);
+    group.addCommand(del);
+    group.addCommand(run);
+    return group;
+};
+// ---- space group (run container — read + config update) -------------------
+/**
+ * `scai agents space` — a space is the container a run executes in. The
+ * BFF exposes no space list or delete, so the group is read + update:
+ * `get` (config), `artifacts` (structured run output), and `update`
+ * (rename / agents / context, by merging a patch into the live config).
+ */
+const createSpaceGroup = () => {
+    const group = new commander_1.Command("space").description("Agentic Studio spaces — the run container (read config + artifacts, update config).");
+    const get = addBaseOptions(new commander_1.Command("get").description("Show a space's config.").argument("<spaceId>", "Space id"));
+    get.action(async (spaceId, options) => {
+        await (0, tasks_1.runSpaceGet)({ ...options, spaceId });
+    });
+    const artifacts = addBaseOptions(new commander_1.Command("artifacts")
+        .description("Show a space's run artifacts — the structured output of its runs.")
+        .argument("<spaceId>", "Space id"));
+    artifacts.action(async (spaceId, options) => {
+        await (0, tasks_1.runSpaceArtifacts)({ ...options, spaceId });
+    });
+    const update = addBaseOptions(new commander_1.Command("update")
+        .description("Update a space's config — merges a JSON/YAML patch into the live config " +
+        "(rename via `spaceName`, change `agents` / `globalContext`).")
+        .argument("<spaceId>", "Space id"));
+    update.addOption(new commander_1.Option("-f, --file <path>", "Path to a JSON/YAML patch — only the keys to change").makeOptionMandatory(true));
+    (0, shared_1.addApplyOption)(update);
+    (0, shared_1.addWhatIfOption)(update);
+    update.action(async (spaceId, options) => {
+        await (0, shared_1.withApplyGate)(async (opts) => {
+            await (0, tasks_1.runSpaceUpdate)({ ...opts, spaceId });
+        })(options);
+    });
+    group.addCommand(get);
+    group.addCommand(artifacts);
+    group.addCommand(update);
+    return group;
+};
+// ---- non-agent resource groups --------------------------------------------
+/**
+ * Build a `{list, get, create, update, delete}` group for one of the
+ * non-agent resources. `update` / `delete` are gated behind `--unverified`
+ * unless the endpoint is confirmed against a live tenant — decided
+ * per-operation from `tasks.updateVerified` / `tasks.deleteVerified`.
+ */
+const createResourceGroup = (name, description, idLabel, tasks) => {
+    const group = new commander_1.Command(name).description(description);
+    const list = addBaseOptions(new commander_1.Command("list").description(`List ${name}s.`));
+    list.action(async (options) => {
+        await tasks.runList(options);
+    });
+    const get = addBaseOptions(new commander_1.Command("get").description(`Show one ${name}.`).argument("<idOrName>", idLabel));
+    get.action(async (idOrName, options) => {
+        await tasks.runGet({ ...options, idOrName });
+    });
+    const create = addBaseOptions(new commander_1.Command("create").description(`Create a ${name} from a recipe file.`));
+    create.addOption(fileOption(name));
+    (0, shared_1.addApplyOption)(create);
+    (0, shared_1.addWhatIfOption)(create);
+    create.action((0, shared_1.withApplyGate)(async (options) => {
+        await tasks.runCreate(options);
+    }));
+    const update = addBaseOptions(new commander_1.Command("update")
+        .description(tasks.updateVerified
+        ? `Update a ${name} from a recipe file.`
+        : `Update a ${name} from a recipe file. UNVERIFIED — requires ` +
+            `--unverified (see docs/agentic-studio-har-capture.md).`)
+        .argument("<idOrName>", idLabel));
+    update.addOption(fileOption(name));
+    if (!tasks.updateVerified)
+        addUnverifiedOption(update);
+    (0, shared_1.addApplyOption)(update);
+    (0, shared_1.addWhatIfOption)(update);
+    update.action(async (idOrName, options) => {
+        await (0, shared_1.withApplyGate)(async (opts) => {
+            await tasks.runUpdate({ ...opts, idOrName });
+        })(options);
+    });
+    const del = addBaseOptions(new commander_1.Command("delete")
+        .description(tasks.deleteVerified
+        ? `Delete a ${name}. Requires --apply; --force for non-TTY.`
+        : `Delete a ${name}. UNVERIFIED — requires --unverified ` +
+            `(see docs/agentic-studio-har-capture.md). Requires --apply; --force for non-TTY.`)
+        .argument("<idOrName>", idLabel)
+        .addOption(new commander_1.Option("--force", "Skip the TTY confirmation prompt (required for non-TTY agents).")));
+    if (!tasks.deleteVerified)
+        addUnverifiedOption(del);
+    (0, shared_1.addApplyOption)(del);
+    (0, shared_1.addWhatIfOption)(del);
+    del.action(async (idOrName, options) => {
+        await (0, shared_1.withApplyGate)(async (opts) => {
+            // Gate on `--unverified` before prompting, so the operator is not
+            // asked to confirm a delete that would only then be rejected.
+            if (!tasks.deleteVerified) {
+                (0, tasks_1.requireUnverified)(opts.unverified, name, "delete");
+            }
+            if (!opts.whatIf) {
+                const confirmed = await (0, cli_tasks_1.confirmDestructive)(`Delete ${name} "${idOrName}"? This cannot be undone.`, opts.force);
+                if (!confirmed) {
+                    process.stderr.write("Aborted.\n");
+                    return;
+                }
+            }
+            await tasks.runDelete({ ...opts, idOrName });
+        })(options);
+    });
+    group.addCommand(list, { isDefault: true });
+    group.addCommand(get);
+    group.addCommand(create);
+    group.addCommand(update);
+    group.addCommand(del);
+    return group;
+};
+/** `scai agents tool` — the tool catalog is read-only. */
+const createToolGroup = () => {
+    const group = new commander_1.Command("tool").description("Agentic Studio tool catalog (read-only — no write path).");
+    const list = addBaseOptions(new commander_1.Command("list").description("List the tool catalog."));
+    list.action(async (options) => {
+        await (0, tasks_1.runToolList)(options);
+    });
+    group.addCommand(list, { isDefault: true });
+    return group;
+};
+// ---- assembly -------------------------------------------------------------
+const createAgentsCommand = () => {
+    const command = new commander_1.Command("agents").description("Sitecore Agentic Studio — agents, skills, tools, widgets, schemas, custom MCPs.");
+    command.addCommand(createLoginCommand());
+    command.addCommand(createSessionCommand("logout", "Forget the stored Agentic Studio session.", tasks_1.runAgentsLogout));
+    command.addCommand(createSessionCommand("status", "Show the Agentic Studio session status.", tasks_1.runAgentsStatus));
+    command.addCommand(createAgentGroup());
+    command.addCommand(createSpaceGroup());
+    command.addCommand(createResourceGroup("skill", "Agentic Studio skills — reusable markdown guidance an agent attaches.", "Skill id, slug, or name", tasks_1.skillTasks));
+    command.addCommand(createResourceGroup("widget", "Agentic Studio widgets — configurable report/dashboard surfaces.", "Widget id or name", tasks_1.widgetTasks));
+    command.addCommand(createResourceGroup("schema", "Agentic Studio structured-output schemas.", "Schema id or name", tasks_1.schemaTasks));
+    command.addCommand(createResourceGroup("mcp", "Registered custom MCP servers.", "Custom MCP id or name", tasks_1.mcpTasks));
+    command.addCommand(createResourceGroup("html-template", "Agentic Studio HTML templates.", "HTML template id", tasks_1.htmlTemplateTasks));
+    command.addCommand(createToolGroup());
+    command.addCommand((0, sync_1.createAgentsSyncCommand)());
+    command.addHelpText("after", "\nExamples:\n" +
+        "  $ scai agents login -n agents\n" +
+        "  $ scai agents agent list -n agents\n" +
+        "  $ scai agents agent create -f research.agent.yaml -n agents --apply\n" +
+        "  $ scai agents agent run research-test -m 'Summarize the latest release' -n agents\n" +
+        "  $ scai agents agent delete research-test -n agents --apply --force\n" +
+        "  $ scai agents skill list -n agents\n" +
+        "  $ scai agents space artifacts <spaceId> -n agents\n" +
+        "\nVerified writes (2026-05-17): `agent`, `skill`, `widget` — full CRUD;\n" +
+        "`schema` — list/get/create/update; `mcp` — list/get/create/delete.\n" +
+        "`schema delete`, `mcp update`, and `html-template` writes are UNVERIFIED\n" +
+        "(405/404) and require `--unverified` — see docs/agentic-studio-har-capture.md.\n" +
+        "Declarative create/update across all kinds is also via `scai agents sync`.\n");
+    return command;
+};
+exports.createAgentsCommand = createAgentsCommand;

package/dist/commands/agents/sync.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `scai agents sync` — pull, diff, and push Agentic Studio resources as
+ * declarative recipes. `--kind` selects the resource (agent | skill |
+ * widget | custom-mcp); the recipe / sync model is shared with the other
+ * areas — see docs/recipe-sync-architecture.md.
+ *
+ *   pull  capture a live resource into a recipe file
+ *   diff  show the plan to converge a resource onto a recipe
+ *   push  apply that plan (dry-run unless --allow-write)
+ */
+import { Command } from "commander";
+/** `scai agents sync` — recipe pull / diff / push for Agentic Studio resources. */
+export declare const createAgentsSyncCommand: () => Command;