@stigmer/cli 3.0.8

package/src/commands/run.ts

@@ -0,0 +1,276 @@
+// `stigmer run [agent-ref | <type> <reference>]` — execute an agent (or create a
+// workflow execution) and stream it. Thin handler: parse flags, resolve the
+// reference (smart 0/1/2-arg dispatch mirroring Go's run.go + run_picker.go),
+// then delegate to the shared run stack. Heavy modules (backend client, Ink,
+// the differ) load lazily inside the action so `--help` stays fast (DD-001).
+
+import type { Command } from "commander";
+import { ensureAuthenticated, resolveOrganization } from "../config/index.js";
+import { UsageError } from "../errors/index.js";
+import { interactiveBrowseEnabled } from "../resources/picker/tty.js";
+import { addAgentExecFlags, type AgentExecOptions } from "./agent-exec-flags.js";
+import { globalOrg } from "./shared.js";
+
+interface RunFlags extends AgentExecOptions {
+  json?: boolean;
+  download?: string;
+}
+
+export function registerRun(program: Command): void {
+  const run = program
+    .command("run [type] [reference]")
+    .description("execute an agent or workflow by reference");
+  addAgentExecFlags(run)
+    .option("--json", "stream events as newline-delimited JSON")
+    .option("--download <dir>", "download artifacts to directory when complete")
+    .action((type: string | undefined, reference: string | undefined, options: RunFlags, command: Command) =>
+      runRun(type, reference, options, command),
+    );
+}
+
+async function runRun(
+  type: string | undefined,
+  reference: string | undefined,
+  options: RunFlags,
+  command: Command,
+): Promise<void> {
+  const { connectBackend } = await import("../backend.js");
+  const client = connectBackend();
+  ensureAuthenticated(client.config);
+  const org = resolveOrganization(client.config, globalOrg(command));
+  if (org === "") {
+    throw new UsageError(
+      "organization not set\n\n" +
+        "Set it with one of:\n" +
+        "  stigmer config context set --org <org>\n" +
+        "  stigmer run --org <org> ...",
+    );
+  }
+
+  const outputMode = options.json === true ? "json" : "inline";
+
+  // 0 args → interactive agent picker on a TTY; otherwise actionable guidance.
+  if (type === undefined) {
+    if (interactiveBrowseEnabled(outputMode)) {
+      await browseAndRunAgent("", options, org, outputMode, client);
+      return;
+    }
+    throw browseUnavailableError("");
+  }
+  // 1 arg → smart resolution; 2 args → explicit "<type> <reference>".
+  if (reference === undefined) {
+    await runSmart(type, options, org, outputMode, client);
+    return;
+  }
+  await runExplicit(type, reference, options, org, outputMode, client);
+}
+
+// stigmer run <value>: classify the single argument and dispatch (Go's
+// executeRunSmart). Session IDs belong to `resume`; complete agent IDs resolve
+// directly; other resource IDs require the explicit two-arg form; bare text is
+// resolved as an agent slug.
+async function runSmart(
+  value: string,
+  options: RunFlags,
+  org: string,
+  outputMode: "inline" | "json",
+  client: import("../client/index.js").BackendClient,
+): Promise<void> {
+  const { isSessionId, hasResourceIdPrefix, isAgentId, validateResourceId } = await import("../resources/reference.js");
+
+  if (isSessionId(value)) {
+    throw new UsageError(
+      `Session IDs are handled by the resume command\n\nTo resume a session:\n  stigmer resume ${value}`,
+    );
+  }
+
+  if (hasResourceIdPrefix(value)) {
+    if (isAgentId(value)) {
+      if (validateResourceId(value) !== null) {
+        throw new UsageError(
+          `Incomplete agent ID: ${value}\n\nProvide the full agent ID (e.g. agt_01abc123xyz456789012345678)`,
+        );
+      }
+      await runAgent(value, options, org, outputMode, client);
+      return;
+    }
+    throw new UsageError(
+      `Cannot run resource ID "${value}" directly with the short form\n\nUse the explicit form:\n  stigmer run <type> <id>`,
+    );
+  }
+
+  // Bare text: try to resolve as an agent reference; on failure, fall back to
+  // the interactive picker (pre-filled with the typed text) on a TTY, otherwise
+  // guide the user.
+  const { resolveAgentRef } = await import("../resources/run/resolve.js");
+  let agent: import("@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb").Agent;
+  try {
+    agent = await resolveAgentRef(client.stigmer, value, org);
+  } catch {
+    if (interactiveBrowseEnabled(outputMode)) {
+      await browseAndRunAgent(value, options, org, outputMode, client);
+      return;
+    }
+    throw browseUnavailableError(value);
+  }
+  await runResolvedAgent(agent, options, org, outputMode, client);
+}
+
+// stigmer run <type> <reference>: explicit form (Go's executeRun + routeRun).
+async function runExplicit(
+  type: string,
+  reference: string,
+  options: RunFlags,
+  org: string,
+  outputMode: "inline" | "json",
+  client: import("../client/index.js").BackendClient,
+): Promise<void> {
+  const { defaultRegistry, Verb } = await import("../registry/index.js");
+  const { ApiResourceKind } = await import(
+    "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb"
+  );
+
+  const info = defaultRegistry().getByAlias(type);
+  if (info === undefined) {
+    throw new UsageError(`unknown resource type: ${type}\n\nAvailable types: agent, workflow`);
+  }
+  if (!info.supportedVerbs.has(Verb.Run)) {
+    throw new UsageError(`${info.displayName} does not support 'run'`);
+  }
+
+  if (info.kind === ApiResourceKind.workflow) {
+    await runWorkflow(reference, options, org, outputMode, client);
+    return;
+  }
+  const { resolveAgentRef } = await import("../resources/run/resolve.js");
+  const agent = await resolveAgentRef(client.stigmer, reference, org);
+  await runResolvedAgent(agent, options, org, outputMode, client);
+}
+
+// Resolve a complete agent ID, then run.
+async function runAgent(
+  agentId: string,
+  options: RunFlags,
+  org: string,
+  outputMode: "inline" | "json",
+  client: import("../client/index.js").BackendClient,
+): Promise<void> {
+  const { resolveAgentRef } = await import("../resources/run/resolve.js");
+  const agent = await resolveAgentRef(client.stigmer, agentId, org);
+  await runResolvedAgent(agent, options, org, outputMode, client);
+}
+
+async function runResolvedAgent(
+  agent: import("@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb").Agent,
+  options: RunFlags,
+  org: string,
+  outputMode: "inline" | "json",
+  client: import("../client/index.js").BackendClient,
+): Promise<void> {
+  const { prepareAgentExec } = await import("../resources/run/prepare.js");
+  const { executeResolvedAgent } = await import("../resources/run/agent-exec.js");
+  const { toAgentExecFlags } = await import("./agent-exec-flags.js");
+
+  const prepared = await prepareAgentExec(toAgentExecFlags(options), client.stigmer, org, stderrProgress());
+  await executeResolvedAgent({
+    agent,
+    prepared,
+    org,
+    downloadDir: options.download ?? "",
+    outputMode,
+    client,
+  });
+}
+
+// Workflow path: create the execution, then either detach (print IDs + return,
+// Go parity) or stream it live over the canonical event stream. Mirrors Go's
+// routeRun workflow branch's guards. `--json` now produces a real NDJSON event
+// stream (fix for D-WF-1: Go silently ignored run workflow --json).
+async function runWorkflow(
+  reference: string,
+  options: RunFlags,
+  org: string,
+  outputMode: "inline" | "json",
+  client: import("../client/index.js").BackendClient,
+): Promise<void> {
+  if (options.workspace.length > 0) {
+    throw new UsageError("--workspace is not supported for workflows (workspace is an agent-level concept)");
+  }
+  const [{ resolveWorkflowRef }, { createWorkflowExecution }, { loadAndMergeEnv }, { parseApprovalAction }] =
+    await Promise.all([
+      import("../resources/run/resolve.js"),
+      import("../resources/run/create.js"),
+      import("../resources/run/env.js"),
+      import("../resources/run/prepare.js"),
+    ]);
+
+  const workflow = await resolveWorkflowRef(client.stigmer, reference, org);
+  const runtimeEnv = loadAndMergeEnv({
+    envFlags: options.env,
+    secretFlags: options.secret,
+    envFiles: options.envFile,
+    secretFiles: options.secretFile,
+  });
+  if (runtimeEnv.STIGMER_ORG_ID === undefined && org !== "") {
+    runtimeEnv.STIGMER_ORG_ID = { value: org, isSecret: false };
+  }
+
+  const execution = await createWorkflowExecution(client.controller.bind(client), {
+    workflowId: workflow.metadata?.id ?? "",
+    orgId: org,
+    message: options.message ?? "",
+    runtimeEnv,
+  });
+  const id = execution.metadata?.id ?? "";
+
+  if (options.detach === true) {
+    process.stdout.write(`Workflow execution created: ${id}\n`);
+    process.stdout.write(`Track it with: stigmer execution logs ${id} --follow\n`);
+    return;
+  }
+
+  const { ApprovalAction } = await import("@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb");
+  const { streamWorkflowExecution } = await import("../resources/run/workflow-stream.js");
+  await streamWorkflowExecution({
+    client: client.stigmer,
+    executionId: id,
+    outputMode,
+    defaultAction: options.autoApprove === true ? ApprovalAction.APPROVE_ALL : parseApprovalAction(options.approveDefault ?? ""),
+  });
+}
+
+function stderrProgress(): (line: string) => void {
+  if (process.stderr.isTTY !== true) return () => {};
+  return (line) => void process.stderr.write(`${line}\n`);
+}
+
+// Mount the agent picker; on selection, run the chosen agent through the
+// existing resolved-agent stack. Cancel (Esc/Ctrl+C → undefined) returns
+// cleanly so the command exits 0. Loaded lazily to honor the DD-001 boundary.
+async function browseAndRunAgent(
+  initialQuery: string,
+  options: RunFlags,
+  org: string,
+  outputMode: "inline" | "json",
+  client: import("../client/index.js").BackendClient,
+): Promise<void> {
+  const { pickAgent } = await import("../resources/picker/ink.js");
+  const selected = await pickAgent({ client: client.stigmer, org, initialQuery });
+  if (selected === undefined) return;
+  await runAgent(selected.id, options, org, outputMode, client);
+}
+
+// Off a TTY (pipes, CI, --json), the interactive picker can't run, so 0-arg and
+// unresolved references produce actionable guidance instead of a browse UI.
+function browseUnavailableError(query: string): UsageError {
+  const head =
+    query === ""
+      ? "Interactive agent browsing requires an interactive terminal"
+      : `No agent found for "${query}"`;
+  return new UsageError(
+    `${head}\n\n` +
+      "Specify a full agent reference:\n" +
+      "  stigmer run <org/slug>\n" +
+      "  stigmer run <agent-id>",
+  );
+}

package/src/commands/search.ts

@@ -0,0 +1,90 @@
+// `stigmer search <type> <query>` — relevance-ranked text search over agents and
+// workflows. Thin handler: validate type/verb/flags, delegate to the resource
+// layer, then append the pagination footer for human output.
+
+import type { Command } from "commander";
+import { ensureAuthenticated } from "../config/index.js";
+import { UsageError } from "../errors/index.js";
+import type { OutputFlags } from "../output/index.js";
+import { defaultRegistry, Verb } from "../registry/index.js";
+import { addReadFlags, globalOrg, readFormat } from "./shared.js";
+
+const DEFAULT_PAGE = 1;
+const DEFAULT_PAGE_SIZE = 20;
+const MAX_PAGE_SIZE = 100;
+
+interface SearchFlags extends OutputFlags {
+  excludePublic?: boolean;
+  page?: string;
+  pageSize?: string;
+}
+
+export function registerSearch(program: Command): void {
+  const search = program
+    .command("search <type> <query>")
+    .description("search resources by text query (supported types: agent, workflow)")
+    .option("--exclude-public", "exclude public/platform resources")
+    .option("--page <n>", "page number (1-indexed)", String(DEFAULT_PAGE))
+    .option("--page-size <n>", "results per page (max 100)", String(DEFAULT_PAGE_SIZE))
+    .action((type: string, query: string, options: SearchFlags, command: Command) =>
+      runSearch(type, query, options, command),
+    );
+  addReadFlags(search);
+}
+
+async function runSearch(type: string, query: string, options: SearchFlags, command: Command): Promise<void> {
+  const info = defaultRegistry().getByAlias(type);
+  if (info === undefined) {
+    throw new UsageError(`unknown resource type: ${type}\n\nAvailable types: agent, workflow`);
+  }
+  if (!info.supportedVerbs.has(Verb.Search)) {
+    throw new UsageError(`${info.displayName} does not support 'search'`);
+  }
+  if (query.trim() === "") {
+    throw new UsageError("search query is required");
+  }
+
+  const page = parsePositive(options.page, DEFAULT_PAGE, "--page");
+  const pageSize = parsePositive(options.pageSize, DEFAULT_PAGE_SIZE, "--page-size");
+  if (pageSize > MAX_PAGE_SIZE) {
+    throw new UsageError(`--page-size cannot exceed ${MAX_PAGE_SIZE}`);
+  }
+
+  const [{ connectBackend }, { searchResources }] = await Promise.all([
+    import("../backend.js"),
+    import("../resources/search.js"),
+  ]);
+
+  const client = connectBackend();
+  ensureAuthenticated(client.config);
+  // Search defaults to all accessible orgs; only an explicit --org scopes it
+  // (mirrors the Go CLI, which leaves the org empty unless overridden).
+  const org = globalOrg(command) ?? "";
+  const format = readFormat(options);
+
+  const outcome = await searchResources(client.stigmer, info.kind, query, {
+    org,
+    excludePublic: options.excludePublic === true,
+    page,
+    pageSize,
+  }, format);
+
+  process.stdout.write(outcome.rendered);
+
+  // Pagination footer is human-only: appending it to json/yaml would corrupt
+  // the machine-readable payload (a latent wart in the Go CLI we don't copy).
+  if (format !== "json" && format !== "yaml" && outcome.totalPages > 1) {
+    process.stdout.write(`\nPage ${outcome.page} of ${outcome.totalPages} (total: ${outcome.totalCount})\n`);
+    if (outcome.page < outcome.totalPages) {
+      process.stdout.write(`Use --page ${outcome.page + 1} to see more results\n`);
+    }
+  }
+}
+
+function parsePositive(raw: string | undefined, fallback: number, flag: string): number {
+  if (raw === undefined || raw === "") return fallback;
+  if (!/^\d+$/.test(raw)) throw new UsageError(`invalid ${flag} value "${raw}"`);
+  const value = Number.parseInt(raw, 10);
+  if (value < 1) throw new UsageError(`${flag} must be at least 1`);
+  return value;
+}

package/src/commands/seedpack.ts

@@ -0,0 +1,94 @@
+// `stigmer seedpack apply|status` — manage the embedded system seedpack.
+//
+// The seedpack (system agents, skills, MCP servers, workflows under the
+// "stigmer" org) is applied automatically on `stigmer up` in local mode; these
+// commands bootstrap it explicitly against whatever backend is configured
+// (local or cloud). Apply is idempotent via a content-hash marker.
+//
+// Heavy modules load lazily inside the action so `--help` stays fast (DD-001).
+
+import type { Command } from "commander";
+import { configDir, dataDir, isCloudMode, load } from "../config/index.js";
+import { CommandResult, type OutputFlags, renderResult } from "../output/index.js";
+import { addResultFlags, resultFormat } from "./shared.js";
+
+interface ApplyFlags extends OutputFlags {
+  force?: boolean;
+}
+
+export function registerSeedpack(program: Command): void {
+  const seedpack = program.command("seedpack").description("manage the embedded system seedpack");
+
+  const apply = seedpack
+    .command("apply")
+    .description("apply the seedpack to the configured backend")
+    .option("--force", "re-apply even if the seedpack has not changed", false)
+    .action((options: ApplyFlags) => runApply(options));
+  addResultFlags(apply);
+
+  const status = seedpack
+    .command("status")
+    .description("show seedpack bootstrap status")
+    .action((options: OutputFlags) => runStatus(options));
+  addResultFlags(status);
+}
+
+async function runApply(flags: ApplyFlags): Promise<void> {
+  const [{ connectBackend }, { ensureAuthenticated }, { applySeedpack }] = await Promise.all([
+    import("../backend.js"),
+    import("../config/index.js"),
+    import("../local/seedpack/apply.js"),
+  ]);
+
+  const client = connectBackend();
+  ensureAuthenticated(client.config);
+
+  const result = await applySeedpack(
+    {
+      controller: client.controller,
+      stigmer: client.stigmer,
+      info: (line) => process.stderr.write(`${line}\n`),
+      warn: (line) => process.stderr.write(`${line}\n`),
+    },
+    { markerDir: markerDir(), force: flags.force === true },
+  );
+
+  const label = backendLabel();
+  const message = result.applied
+    ? `Seedpack applied to ${label} backend`
+    : `Seedpack already up to date on ${label} backend (use --force to re-apply)`;
+  renderResult(CommandResult.success(message), resultFormat(flags));
+}
+
+async function runStatus(flags: OutputFlags): Promise<void> {
+  const { seedpackContentHash } = await import("../local/seedpack/apply.js");
+  const { readMarker } = await import("../local/seedpack/content.js");
+
+  const hash = seedpackContentHash();
+  const stored = readMarker(markerDir());
+
+  const result = CommandResult.success("Seedpack status");
+  const section = result.addSection("");
+  section.field("Backend", backendLabel());
+  section.field("Embedded Hash", hash);
+  if (stored === null) {
+    section.field("Status", "Not applied (run 'stigmer seedpack apply')");
+  } else {
+    section.field("Applied Hash", stored);
+    section.field("Status", stored === hash ? "Up to date" : "Outdated (run 'stigmer seedpack apply' to update)");
+  }
+  renderResult(result, resultFormat(flags));
+}
+
+// Marker lives with the backend's state: the data dir for local, the config dir
+// for cloud (mirrors the Go CLI's resolveMarkerDir).
+function markerDir(): string {
+  return isCloudMode(load()) ? configDir() : dataDir();
+}
+
+function backendLabel(): string {
+  const config = load();
+  if (!isCloudMode(config)) return "local";
+  const endpoint = config.backend.cloud?.endpoint ?? "api.stigmer.ai:443";
+  return `cloud (${endpoint})`;
+}

package/src/commands/setup.ts

@@ -0,0 +1,71 @@
+// `stigmer setup` — configure the LLM provider used for agent execution.
+//
+// Two paths share one decision core (local/setup/wizard.ts): a non-interactive
+// flag path (`--provider`, `--api-key`, …) for scripts and CI, and an
+// interactive menu when no provider flag is given. Both write to
+// backend.local.llm, preserving every other config field.
+
+import type { Command } from "commander";
+import { homedir } from "node:os";
+import { type OutputFlags, CommandResult, renderResult } from "../output/index.js";
+import { addResultFlags, resultFormat } from "./shared.js";
+
+interface SetupFlags extends OutputFlags {
+  provider?: string;
+  model?: string;
+  apiKey?: string;
+  baseUrl?: string;
+}
+
+const PROVIDERS = ["anthropic", "openai", "ollama", "skip"] as const;
+
+export function registerSetup(program: Command): void {
+  const setup = program
+    .command("setup")
+    .description("configure the LLM provider for agent execution")
+    .option("--provider <name>", "provider: anthropic, openai, ollama, or skip (non-interactive)")
+    .option("--model <name>", "model name (defaults per provider)")
+    .option("--api-key <key>", "API key for a cloud provider")
+    .option("--base-url <url>", "custom base URL (e.g. an Ollama endpoint)")
+    .action((options: SetupFlags) => runSetup(options));
+  addResultFlags(setup);
+}
+
+async function runSetup(options: SetupFlags): Promise<void> {
+  const { load, save } = await import("../config/config.js");
+  const { applyChoice, runInteractiveWizard } = await import("../local/setup/wizard.js");
+  const { isRunning } = await import("../local/daemon/launch.js");
+  const { CliExitError } = await import("../errors/cli-exit-error.js");
+  const { ExitCode } = await import("../errors/exit-codes.js");
+
+  const config = load();
+
+  let updated: typeof config | null;
+  if (options.provider !== undefined) {
+    const provider = options.provider.toLowerCase();
+    if (!PROVIDERS.includes(provider as (typeof PROVIDERS)[number])) {
+      throw new CliExitError(`unknown provider: ${options.provider}`, ExitCode.Usage, [
+        `Valid providers: ${PROVIDERS.join(", ")}`,
+      ]);
+    }
+    updated = applyChoice(config, provider as (typeof PROVIDERS)[number], {
+      model: options.model,
+      apiKey: options.apiKey,
+      baseUrl: options.baseUrl,
+    });
+  } else {
+    updated = await runInteractiveWizard(config);
+    if (updated === null) {
+      renderResult(CommandResult.warning("Setup cancelled"), resultFormat(options));
+      return;
+    }
+  }
+
+  save(updated);
+
+  const result = CommandResult.success("LLM configuration saved");
+  if (await isRunning(homedir())) {
+    result.hint("Restart to apply: stigmer down && stigmer up");
+  }
+  renderResult(result, resultFormat(options));
+}

package/src/commands/shared.ts

@@ -0,0 +1,41 @@
+// Shared commander wiring for output flags. Keeps the unified output model
+// (src/output/format.ts) consistent across every command and out of the
+// individual handlers.
+
+import type { Command } from "commander";
+import { type CommandClass, type OutputFlags, type OutputFormat, resolveFormat } from "../output/index.js";
+
+/** Add read-verb output flags: `-o/--output {table,json,yaml}` plus `--json`. */
+export function addReadFlags(command: Command): Command {
+  return command
+    .option("-o, --output <format>", "output format: table, json, or yaml")
+    .option("--json", "shorthand for --output json");
+}
+
+/** Add mutating-command output flags: `--json` and `--quiet`. */
+export function addResultFlags(command: Command): Command {
+  return command
+    .option("--json", "emit the result as JSON")
+    .option("--quiet", "print only the status line");
+}
+
+/** Resolve the output format for a read verb from parsed options. */
+export function readFormat(options: OutputFlags): OutputFormat {
+  return resolveFormat(options, "read");
+}
+
+/** Resolve the output format for a mutating command from parsed options. */
+export function resultFormat(options: OutputFlags): OutputFormat {
+  return resolveFormat(options, "mutating");
+}
+
+/** Resolve any command class's format (escape hatch for non-standard verbs). */
+export function formatFor(options: OutputFlags, commandClass: CommandClass): OutputFormat {
+  return resolveFormat(options, commandClass);
+}
+
+/** Read the inherited global `--org` flag from within a subcommand action. */
+export function globalOrg(command: Command): string | undefined {
+  const value = command.optsWithGlobals().org;
+  return typeof value === "string" && value !== "" ? value : undefined;
+}

package/src/commands/status.ts

@@ -0,0 +1,20 @@
+// `stigmer status` — show the local stack's health (daemon, Temporal, server,
+// runner, web console) plus the effective LLM configuration.
+//
+// Thin handler: build the structured result in the local subsystem and render
+// it. The local module loads lazily so `--help` stays fast (DD-001).
+
+import type { Command } from "commander";
+import { type OutputFlags, renderResult } from "../output/index.js";
+import { addResultFlags, resultFormat } from "./shared.js";
+
+export function registerStatus(program: Command): void {
+  const status = program
+    .command("status")
+    .description("show the status of the local Stigmer stack")
+    .action(async (options: OutputFlags) => {
+      const { buildStatusResult } = await import("../local/status.js");
+      renderResult(await buildStatusResult(), resultFormat(options));
+    });
+  addResultFlags(status);
+}

package/src/commands/tag.ts

@@ -0,0 +1,31 @@
+// `stigmer tag <type> <org/slug> <hash> <tag>` — assign a tag to a resource
+// version. Thin handler: resolve credentials/org, delegate to the resource
+// layer, render the result. Heavy modules are lazy-imported (DD-001).
+
+import type { Command } from "commander";
+import { ensureAuthenticated, resolveOrganization } from "../config/index.js";
+import { globalOrg } from "./shared.js";
+
+export function registerTag(program: Command): void {
+  program
+    .command("tag <type> <org/slug> <hash> <tag>")
+    .description("assign a tag to a resource version (supported types: workflow)")
+    .action((type: string, ref: string, hash: string, tag: string, _options: unknown, command: Command) =>
+      runTag(type, ref, hash, tag, command),
+    );
+}
+
+async function runTag(type: string, ref: string, hash: string, tag: string, command: Command): Promise<void> {
+  const [{ connectBackend }, { tagVersion }, { renderResult }] = await Promise.all([
+    import("../backend.js"),
+    import("../resources/tag.js"),
+    import("../output/command-result.js"),
+  ]);
+
+  const client = connectBackend();
+  ensureAuthenticated(client.config);
+  const org = resolveOrganization(client.config, globalOrg(command));
+
+  const result = await tagVersion(client.stigmer, type, ref, hash, tag, org);
+  renderResult(result, "human");
+}

package/src/commands/up.ts

@@ -0,0 +1,51 @@
+// `stigmer up [server]` — start the local Stigmer stack (managed Temporal, the
+// control-plane server, and the unified runner) as a supervised background
+// daemon. `up server` brings up only the control plane.
+//
+// Thin handler: parse flags, delegate to the local daemon launcher, render the
+// outcome. The launcher (and the heavy resolvers it pulls in) load lazily so
+// `--help` stays fast (DD-001).
+
+import type { Command } from "commander";
+import { CommandResult, type OutputFlags, renderResult } from "../output/index.js";
+import { SERVER_PORT } from "../local/constants.js";
+import { addResultFlags, resultFormat } from "./shared.js";
+
+interface UpFlags extends OutputFlags {
+  serverOnly?: boolean;
+  web?: boolean; // false when --no-web is passed
+}
+
+export function registerUp(program: Command): void {
+  const up = program
+    .command("up")
+    .description("start the local Stigmer stack (server, runner, Temporal)")
+    .option("--server-only", "start only the control plane (no runners)")
+    // Accepted for compatibility with the Go CLI; this CLI does not bundle a
+    // local web console, so the stack is headless either way (use the cloud
+    // console at app.stigmer.ai for a UI).
+    .option("--no-web", "no-op: this CLI does not serve a local web console")
+    .action((options: UpFlags) =>
+      runUp({ serverOnly: options.serverOnly === true, noWeb: options.web === false }, options),
+    );
+  addResultFlags(up);
+
+  const server = up
+    .command("server")
+    .description("start only the control plane (no runners)")
+    .option("--no-web", "no-op: this CLI does not serve a local web console")
+    .action((options: UpFlags) => runUp({ serverOnly: true, noWeb: options.web === false }, options));
+  addResultFlags(server);
+}
+
+async function runUp(opts: { serverOnly: boolean; noWeb: boolean }, flags: OutputFlags): Promise<void> {
+  process.stderr.write("Starting Stigmer local stack… (first run may take a moment)\n");
+  const { up } = await import("../local/daemon/launch.js");
+  await up(opts);
+
+  const result = CommandResult.success(opts.serverOnly ? "Stigmer control plane is up" : "Stigmer local stack is up");
+  const section = result.addSection("Endpoints");
+  section.field("server", `http://localhost:${SERVER_PORT}`);
+  result.hint("Check status with: stigmer status").hint("Stop it with:    stigmer down");
+  renderResult(result, resultFormat(flags));
+}