@rigkit/cli 0.2.3 → 0.2.5

package/README.md

@@ -5,9 +5,9 @@ Global `rig` CLI.
 ```bash
 npm i -g @rigkit/cli
 rig init
-rig plan
+rig run plan
 rig ls
-rig plan github:owner/repo
+rig run plan github:owner/repo
 ```
 
 `rig init` asks for a project name, Freestyle API key, and package manager. It creates a project folder containing a workflow-based `rig.config.ts`, `.env`, `.env.example`, `package.json`, and local ignore rules.
@@ -16,7 +16,7 @@ Interactive terminals use Inquirer prompts and a chalk/log-update run timeline.
 
 Interactive providers can ask the CLI to open provider-owned URLs. For example, Freestyle terminal sessions are served by the Freestyle provider, while the CLI only opens the presented URL in a browser.
 
-Workspace-specific operations run as `rig <workspace>/<operation>`, for example `rig website-workspace/open-cmux` or `rig website-workspace/remove -y`.
+Workspace-specific operations run as `rig run <workspace>/<operation>`, for example `rig run website-workspace/open-cmux` or `rig run website-workspace/remove -y`.
 
 `rig ls` lists workspaces for the selected project. `rig ls snapshots` lists cached snapshot runs, and `rig ls config` shows the resolved project paths.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rigkit/cli",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "type": "module",
   "repository": {
     "type": "git",
@@ -25,9 +25,9 @@
     "log-symbols": "^7.0.1",
     "log-update": "^8.0.0",
     "ora": "^9.4.0",
-    "@rigkit/engine": "0.2.3",
-    "@rigkit/runtime-client": "0.2.3",
-    "@rigkit/provider-cmux": "0.2.3"
+    "@rigkit/engine": "0.2.5",
+    "@rigkit/runtime-client": "0.2.5",
+    "@rigkit/provider-cmux": "0.2.5"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/src/cli.test.ts

@@ -23,7 +23,7 @@ describe("CLI entrypoint", () => {
     expect(rootHelp.exitCode).toBe(0);
     expect(rootHelp.stderr).toBe("");
     expect(rootHelp.stdout).toContain("rig ");
-    expect(rootHelp.stdout).toContain("<operation> Run a project operation exposed by the runtime");
+    expect(rootHelp.stdout).toContain("run         Run a project operation exposed by the runtime");
 
     const version = await runCli(["version"]);
     expect(version.exitCode).toBe(0);
@@ -34,15 +34,15 @@ describe("CLI entrypoint", () => {
     expect(help.exitCode).toBe(0);
     expect(help.stderr).toBe("");
     expect(help.stdout).toContain("rig ");
-    expect(help.stdout).toContain("<operation> Run a project operation exposed by the runtime");
+    expect(help.stdout).toContain("run         Run a project operation exposed by the runtime");
   });
 
-  test("treats unknown root tokens as project operations", async () => {
+  test("rejects operation shorthand at the root", async () => {
     const result = await runCli(["unknown"]);
 
     expect(result.exitCode).toBe(1);
     expect(result.stdout).toBe("");
-    expect(result.stderr).toContain("No Rigkit config found");
+    expect(result.stderr).toContain("unknown command 'unknown'");
   });
 
   test("serves dynamic shell completion endpoint", async () => {
@@ -106,11 +106,23 @@ describe("CLI entrypoint", () => {
     });
   });
 
+  test("rejects workspace create names that are not shell-safe", async () => {
+    const projectDir = mkdtempSync(join(tmpdir(), "rigkit-cli-create-name-"));
+
+    await withWorkspaceRuntime({ projectDir }, async ({ env }) => {
+      const result = await runCli(["-C", projectDir, "run", "create", "--name", "some workspace", "--json"], { env });
+
+      expect(result.exitCode).toBe(1);
+      expect(result.stdout).toBe("");
+      expect(result.stderr).toContain('Invalid workspace name "some workspace"');
+    });
+  });
+
   test("requires discovered projects for operation --all", async () => {
     const cwd = mkdtempSync(join(tmpdir(), "rigkit-cli-run-all-"));
 
     try {
-      const result = await runCli(["plan", "--all", "--json"], { cwd });
+      const result = await runCli(["run", "plan", "--all", "--json"], { cwd });
 
       expect(result.exitCode).toBe(1);
       expect(result.stdout).toBe("");
@@ -128,7 +140,7 @@ describe("CLI entrypoint", () => {
     writeFileSync(join(cwd, "web", "rig.config.ts"), "export default {}\n");
 
     try {
-      const result = await runCli(["plan", "--discover", "--json"], { cwd });
+      const result = await runCli(["run", "plan", "--discover", "--json"], { cwd });
 
       expect(result.exitCode).toBe(1);
       expect(result.stdout).toBe("");
@@ -216,6 +228,30 @@ async function withWorkspaceRuntime(
           }],
         });
       }
+      if (pathname === "/operations") {
+        return runtimeJson({
+          operations: [{
+            id: "create",
+            kind: "command",
+            source: "core",
+            title: "Create",
+            description: "Create a workspace",
+            createsWorkspace: true,
+            cli: {
+              options: [{ name: "name", flag: "--name", required: true, type: "string" }],
+            },
+            inputSchema: {
+              type: "object",
+              additionalProperties: false,
+              properties: {
+                name: { type: "string", minLength: 1 },
+              },
+              required: ["name"],
+            },
+          }],
+          workspaceOperations: [],
+        });
+      }
       return runtimeJson({ error: { message: "Not found" } }, { status: 404 });
     },
   });

package/src/cli.ts

@@ -148,41 +148,10 @@ const CLI_HOST_CAPABILITIES: Array<{ id: string; schemaHash?: string }> = [
   ...(capability.schemaHash ? { schemaHash: capability.schemaHash } : {}),
 }));
 
-const MANAGEMENT_COMMANDS = new Set([
-  "completion",
-  "doctor",
-  "help",
-  "init",
-  "ls",
-  "projects",
-  "run",
-  "version",
-]);
-
-const GLOBAL_OPTIONS_WITH_VALUES = new Set(["-C", "--project", "--config", "--state"]);
-
 if (process.argv[2] === "__complete") {
   runCompletionEndpoint(process.argv.slice(3)).catch(handleCliError);
 } else {
-  runCli(normalizeOperationArgv(process.argv)).catch(handleCliError);
-}
-
-function normalizeOperationArgv(argv: string[]): string[] {
-  const args = argv.slice(2);
-  for (let index = 0; index < args.length; index += 1) {
-    const arg = args[index]!;
-    if (arg === "--") return argv;
-    if (GLOBAL_OPTIONS_WITH_VALUES.has(arg)) {
-      index += 1;
-      continue;
-    }
-    if ([...GLOBAL_OPTIONS_WITH_VALUES].some((option) => arg.startsWith(`${option}=`))) continue;
-    if (arg === "--json") continue;
-    if (arg.startsWith("-")) return argv;
-    if (MANAGEMENT_COMMANDS.has(arg)) return argv;
-    return [...argv.slice(0, 2), ...args.slice(0, index), "run", ...args.slice(index)];
-  }
-  return argv;
+  runCli(process.argv).catch(handleCliError);
 }
 
 async function runCli(argv: string[]): Promise<void> {
@@ -190,7 +159,7 @@ async function runCli(argv: string[]): Promise<void> {
   program
     .name("rig")
     .description("Rigkit workflow CLI")
-    .usage("[options] <command|operation>")
+    .usage("[options] <command>")
     .version(RIGKIT_CLI_VERSION, "-v, --version", "Show Rigkit CLI version")
     .showHelpAfterError()
     .exitOverride()
@@ -228,7 +197,7 @@ async function runCli(argv: string[]): Promise<void> {
     });
 
   program
-    .command("run <operation> [args...]", { hidden: true })
+    .command("run <operation> [args...]")
     .description("Run a project operation exposed by the runtime")
     .allowUnknownOption(true)
     .option("--all", "Run against every discovered project")
@@ -405,29 +374,29 @@ async function runInit(invocation: CliInvocation, options: InitOptions): Promise
 async function resolveInitAnswers(
   options: InitOptions,
   jsonMode: boolean,
-): Promise<{ name: string; apiKey: string; packageManager: PackageManager }> {
-  if (jsonMode && (options.name === undefined || !options.apiKey?.trim())) {
-    throw new Error(`rig init --json requires --name and --api-key`);
+): Promise<{ name: string; apiKey?: string; packageManager: PackageManager }> {
+  if (jsonMode && options.name === undefined) {
+    throw new Error(`rig init --json requires --name`);
   }
 
   if (jsonMode && options.packageManager && options.packageManager !== "skip") {
     throw new Error(`rig init --json only supports --package-manager skip`);
   }
 
-  if (options.name === undefined || !options.apiKey) {
+  if (options.name === undefined) {
     assertInteractiveInit();
   }
 
   if (!jsonMode) {
     console.log(chalk.bold("Initialize Rigkit"));
-    console.log(chalk.dim("This creates a project folder with rig.config.ts, .env, package.json, and local ignore rules."));
+    console.log(chalk.dim("This creates a project folder with rig.config.ts, package.json, and local ignore rules."));
     console.log("");
   }
 
   const name = options.name !== undefined
     ? normalizeMachineName(options.name)
     : await promptName();
-  const apiKey = options.apiKey?.trim() || await promptRequiredSecret("Freestyle API key");
+  const apiKey = options.apiKey?.trim();
   const packageManager = options.packageManager ?? (jsonMode || !canPrompt() ? "skip" : await promptPackageManager("skip"));
 
   return {
@@ -439,7 +408,7 @@ async function resolveInitAnswers(
 
 function assertInteractiveInit(): void {
   if (canPrompt()) return;
-  throw new Error(`rig init needs --name and --api-key when not running in an interactive terminal`);
+  throw new Error(`rig init needs --name when not running in an interactive terminal`);
 }
 
 function canPrompt(): boolean {
@@ -478,14 +447,6 @@ async function promptName(): Promise<string> {
   return answers.name;
 }
 
-async function promptRequiredSecret(label: string): Promise<string> {
-  for (;;) {
-    const value = (await promptSecret(label)).trim();
-    if (value) return value;
-    console.log(chalk.red(`${label} is required.`));
-  }
-}
-
 async function promptPackageManager(defaultValue: PackageManager): Promise<PackageManager> {
   const choices: Array<{ value: PackageManager; label: string; hint: string }> = [
     { value: "npm", label: "npm", hint: "npm install" },
@@ -507,14 +468,50 @@ async function promptPackageManager(defaultValue: PackageManager): Promise<Packa
   return answers.packageManager;
 }
 
-async function promptSecret(label: string): Promise<string> {
-  const answers = await inquirer.prompt<{ value: string }>([{
-    type: "password",
-    name: "value",
-    message: `${label}:`,
-    mask: "*",
+async function promptWorkspaceName(): Promise<string> {
+  const answers = await inquirer.prompt<{ name: string }>([{
+    type: "input",
+    name: "name",
+    message: "Workspace name:",
+    validate(value: string) {
+      return validateWorkspaceName(value.trim());
+    },
+    filter: (value: string) => value.trim(),
   }]);
-  return answers.value;
+  return answers.name;
+}
+
+const workspaceNamePattern = /^(?!-)[A-Za-z0-9._-]+$/;
+
+function validateWorkspaceName(value: string): true | string {
+  if (!value) return "Workspace name is required.";
+  if (!workspaceNamePattern.test(value)) {
+    return 'Use only letters, numbers, ".", "_", and "-", and do not start with "-".';
+  }
+  return true;
+}
+
+function assertValidWorkspaceName(value: unknown): void {
+  if (typeof value !== "string") throw new Error(`Workspace name must be a string`);
+  const valid = validateWorkspaceName(value);
+  if (valid !== true) throw new Error(`Invalid workspace name "${value}". ${valid}`);
+}
+
+async function promptWorkspaceOperation(
+  workspace: string,
+  operations: RuntimeOperationDefinition[],
+): Promise<string> {
+  const answers = await inquirer.prompt<{ operation: string }>([{
+    type: "select",
+    name: "operation",
+    message: `Operation for ${workspace}:`,
+    choices: operations.map((operation) => ({
+      name: operation.id,
+      value: operation.id,
+      description: operation.description || operation.title || "workspace operation",
+    })),
+  }]);
+  return answers.operation;
 }
 
 async function runPackageManagerInstall(
@@ -598,7 +595,7 @@ function printInitResult(result: InitProjectResult, install: InitInstallResult):
   if (install.skipped) {
     console.log(`  ${detectInstallCommand(result.packageJsonPath)}`);
   }
-  console.log("  rig plan");
+  console.log("  rig run plan");
 }
 
 function displayProjectDir(projectDir: string): string {
@@ -667,6 +664,7 @@ async function runProjectOperation(
   }
 
   await renderOperationResult(operation, result, parsed.hostOptions);
+  printInteractiveOutputGap(invocation);
 }
 
 async function runDiscoveredProjectOperation(
@@ -722,6 +720,7 @@ async function runDiscoveredProjectOperation(
         console.log(chalk.bold(displayProjectDir(project.projectDir)));
       }
       await renderOperationResult(operation, result, parsed.hostOptions);
+      printInteractiveOutputGap(invocation);
     }
   }
 
@@ -792,13 +791,13 @@ async function executeRuntimeOperation(
   result: unknown;
 }> {
   const manifest = await readRuntimeOperations(runtime);
-  const resolved = findRuntimeOperation(manifest, requestedOperation);
+  const resolved = await resolveRequestedRuntimeOperation(invocation, runtime, manifest, requestedOperation);
   if (!resolved) {
     throw new Error(`This project does not define a Rigkit operation named "${requestedOperation}".`);
   }
   const { operation, runOperation } = resolved;
 
-  const parsed = parseOperationArgs(operation, args);
+  const parsed = await parseOperationArgsWithPrompts(invocation, operation, args);
   enforceHostOnlyBooleanGuards(operation, parsed);
 
   const result = await runRuntimeOperation<unknown>(
@@ -811,6 +810,28 @@ async function executeRuntimeOperation(
   return { operation, parsed, result };
 }
 
+async function resolveRequestedRuntimeOperation(
+  invocation: CliInvocation,
+  runtime: RuntimeClient,
+  manifest: RuntimeOperationManifest,
+  requestedOperation: string,
+): Promise<{ operation: RuntimeOperationDefinition; runOperation: string } | undefined> {
+  const resolved = findRuntimeOperation(manifest, requestedOperation);
+  if (resolved) return resolved;
+
+  if (requestedOperation.includes("/") || wantsJson(invocation) || !canPrompt()) return undefined;
+
+  const workspaces = await runtime.control.workspaces()
+    .then((response) => response.workspaces as WorkspaceRecord[])
+    .catch(() => []);
+  const workspace = workspaces.find((item) => item.name === requestedOperation);
+  if (!workspace || (manifest.workspaceOperations ?? []).length === 0) return undefined;
+
+  const operationId = await promptWorkspaceOperation(workspace.name, manifest.workspaceOperations ?? []);
+  const operation = (manifest.workspaceOperations ?? []).find((item) => item.id === operationId);
+  return operation ? { operation, runOperation: `${workspace.name}/${operation.id}` } : undefined;
+}
+
 function findRuntimeOperation(
   manifest: RuntimeOperationManifest,
   requestedOperation: string,
@@ -836,7 +857,36 @@ function parseWorkspaceOperationId(value: string): { workspace: string; operatio
   };
 }
 
-function parseOperationArgs(operation: RuntimeOperationDefinition, args: string[]): ParsedOperationInput {
+async function parseOperationArgsWithPrompts(
+  invocation: CliInvocation,
+  operation: RuntimeOperationDefinition,
+  args: string[],
+): Promise<ParsedOperationInput> {
+  const parsed = parseOperationArgs(operation, args, {
+    allowMissingRequired: !wantsJson(invocation) && canPrompt(),
+  });
+
+  if (
+    operation.createsWorkspace &&
+    parsed.input.name === undefined &&
+    !wantsJson(invocation) &&
+    canPrompt()
+  ) {
+    parsed.input.name = await promptWorkspaceName();
+  }
+  if (operation.createsWorkspace && parsed.input.name !== undefined) {
+    assertValidWorkspaceName(parsed.input.name);
+  }
+
+  enforceRequiredOperationInputs(operation, parsed);
+  return parsed;
+}
+
+function parseOperationArgs(
+  operation: RuntimeOperationDefinition,
+  args: string[],
+  options: { allowMissingRequired?: boolean } = {},
+): ParsedOperationInput {
   const cli = inferCliMetadata(operation);
   const input: Record<string, unknown> = {};
   const hostOptions: Record<string, unknown> = {};
@@ -875,19 +925,27 @@ function parseOperationArgs(operation: RuntimeOperationDefinition, args: string[
     assignPositional(positionals, positionalIndex++, arg, input);
   }
 
+  if (!options.allowMissingRequired) enforceRequiredOperationInputs(operation, { input, hostOptions });
+
+  return { input, hostOptions };
+}
+
+function enforceRequiredOperationInputs(
+  operation: RuntimeOperationDefinition,
+  parsed: ParsedOperationInput,
+): void {
+  const cli = inferCliMetadata(operation);
   for (const option of cli.options ?? []) {
-    if (option.required && input[option.name] === undefined && hostOptions[option.name] === undefined) {
+    if (option.required && parsed.input[option.name] === undefined && parsed.hostOptions[option.name] === undefined) {
       throw new Error(`Operation ${operation.id} requires ${option.flag}`);
     }
   }
 
   for (const name of operation.inputSchema?.required ?? []) {
-    if (input[name] === undefined) {
+    if (parsed.input[name] === undefined) {
       throw new Error(`Operation ${operation.id} requires ${name}`);
     }
   }
-
-  return { input, hostOptions };
 }
 
 function enforceHostOnlyBooleanGuards(
@@ -1090,7 +1148,7 @@ async function runHelp(invocation: CliInvocation): Promise<void> {
       commands: [
         { name: "help", description: "Show Rigkit CLI help" },
         { name: "init", description: "Initialize a Rigkit project" },
-        { name: "<operation>", description: "Run a project operation exposed by the runtime" },
+        { name: "run", description: "Run a project operation exposed by the runtime" },
         { name: "ls", description: "List project workspaces" },
         { name: "projects", description: "Discover Rigkit projects below the current directory" },
         { name: "doctor", description: "Show Rigkit runtime diagnostics" },
@@ -1104,12 +1162,12 @@ async function runHelp(invocation: CliInvocation): Promise<void> {
     `rig ${RIGKIT_CLI_VERSION}`,
     "",
     "Usage:",
-    "  rig [options] <command|operation>",
+    "  rig [options] <command>",
     "",
     "Commands:",
     "  help        Show Rigkit CLI help",
     "  init        Initialize a Rigkit project",
-    "  <operation> Run a project operation exposed by the runtime",
+    "  run         Run a project operation exposed by the runtime",
     "  ls          List project workspaces",
     "  projects    Discover Rigkit projects below the current directory",
     "  doctor      Show Rigkit runtime diagnostics",
@@ -1214,10 +1272,12 @@ async function runRuntimeOperation<T>(
       return;
     }
     if (isHostCapabilityRequestEvent(event)) {
-      presenter?.pause();
+      const suspendPresenter = hostCapabilityNeedsTerminal(event);
+      const logger = createHostCapabilityLogger(event, presenter);
+      if (suspendPresenter) presenter?.pause();
       try {
         if (sendSession) {
-          await answerHostCapabilityRequestOverSession(sendSession, event);
+          await answerHostCapabilityRequestOverSession(sendSession, event, { logger });
         } else if (respond) {
           await answerHostCapabilityRequestOverSession((message) => {
             if (isRecord(message) && message.type === "response") {
@@ -1225,12 +1285,12 @@ async function runRuntimeOperation<T>(
               if (id) return respond(id, "error" in message ? { error: message.error } : { result: message.result });
             }
             throw new Error(`Session response channel cannot send ${String(isRecord(message) ? message.type : typeof message)}`);
-          }, event);
+          }, event, { logger });
         } else {
-          await answerHostCapabilityRequest(runtime, event);
+          await answerHostCapabilityRequest(runtime, event, { logger });
         }
       } finally {
-        presenter?.resume();
+        if (suspendPresenter) presenter?.resume();
       }
       return;
     }
@@ -1352,6 +1412,7 @@ type HostCapabilityRequestEvent = {
   type: "host.capability.request";
   requestId?: string;
   id?: string;
+  nodePath?: string;
   capability: string;
   params: unknown;
 };
@@ -1360,6 +1421,15 @@ type HostRequestHandlingOptions = {
   quietOpen?: boolean;
 };
 
+type HostCapabilityLogOptions = {
+  stream?: "stdout" | "stderr" | "info";
+  label?: string;
+};
+
+type HostCapabilityRequestHandlingOptions = {
+  logger?: (data: string, options?: HostCapabilityLogOptions) => void;
+};
+
 class UnsupportedHostCapabilityError extends Error {
   constructor(capability: string) {
     super(
@@ -1407,11 +1477,15 @@ async function answerHostRequestOverSession(
   }
 }
 
-async function answerHostCapabilityRequest(runtime: RuntimeClient, event: HostCapabilityRequestEvent): Promise<void> {
+async function answerHostCapabilityRequest(
+  runtime: RuntimeClient,
+  event: HostCapabilityRequestEvent,
+  options: HostCapabilityRequestHandlingOptions = {},
+): Promise<void> {
   const requestId = event.requestId ?? event.id;
   if (!requestId) throw new Error(`Host capability request is missing requestId`);
   try {
-    const handled = await handleHostCapabilityRequest(event.capability, event.params);
+    const handled = await handleHostCapabilityRequest(event.capability, event.params, options);
     await runtime.control.hostResponse(requestId, { result: handled.result });
   } catch (error) {
     await runtime.control.hostResponse(requestId, {
@@ -1423,11 +1497,12 @@ async function answerHostCapabilityRequest(runtime: RuntimeClient, event: HostCa
 async function answerHostCapabilityRequestOverSession(
   send: (message: unknown) => void | Promise<void>,
   event: HostCapabilityRequestEvent,
+  options: HostCapabilityRequestHandlingOptions = {},
 ): Promise<void> {
   const id = event.id ?? event.requestId;
   if (!id) throw new Error(`Host capability request is missing id`);
   try {
-    const handled = await handleHostCapabilityRequest(event.capability, event.params);
+    const handled = await handleHostCapabilityRequest(event.capability, event.params, options);
     await send({ type: "response", id, result: handled.result });
     if (handled.closed) reportHostCapabilityClosed(send, id, handled.closed);
   } catch (error) {
@@ -1473,6 +1548,34 @@ function hostRequestNeedsTerminal(event: HostRequestEvent): boolean {
   }
 }
 
+function hostCapabilityNeedsTerminal(event: HostCapabilityRequestEvent): boolean {
+  switch (event.capability) {
+    case "cmux.open":
+      return false;
+    default:
+      return true;
+  }
+}
+
+function createHostCapabilityLogger(
+  event: HostCapabilityRequestEvent,
+  presenter: RunPresenter | undefined,
+): (data: string, options?: HostCapabilityLogOptions) => void {
+  return (data, options = {}) => {
+    if (presenter) {
+      presenter.render({
+        type: "log.output",
+        nodePath: event.nodePath ?? "runtime",
+        stream: options.stream ?? "info",
+        label: options.label ?? event.capability,
+        data,
+      });
+      return;
+    }
+    console.error(data);
+  };
+}
+
 function isTrustedCaptureHostCommand(params: unknown): boolean {
   return process.env.RIGKIT_TRUST_HOST_COMMANDS === "1" &&
     isRecord(params) &&
@@ -1484,12 +1587,18 @@ type HandledHostCapability = {
   closed?: Promise<void>;
 };
 
-async function handleHostCapabilityRequest(capability: string, params: unknown): Promise<HandledHostCapability> {
+async function handleHostCapabilityRequest(
+  capability: string,
+  params: unknown,
+  options: HostCapabilityRequestHandlingOptions = {},
+): Promise<HandledHostCapability> {
   const handler = CLI_HOST_CAPABILITY_HANDLERS.get(capability);
   if (!handler) {
     throw new UnsupportedHostCapabilityError(capability);
   }
-  return normalizeHostCapabilityResult(await handler.handle(params));
+  return normalizeHostCapabilityResult(await handler.handle(params, {
+    log: (data, logOptions) => options.logger?.(data, logOptions),
+  }));
 }
 
 function normalizeHostCapabilityResult(value: unknown): HandledHostCapability {
@@ -1685,6 +1794,7 @@ function isHostCapabilityRequestEvent(value: unknown): value is HostCapabilityRe
   return isRecord(value) &&
     value.type === "host.capability.request" &&
     (typeof value.requestId === "string" || typeof value.id === "string") &&
+    (value.nodePath === undefined || typeof value.nodePath === "string") &&
     typeof value.capability === "string";
 }
 
@@ -1739,6 +1849,11 @@ function printJson(value: unknown): void {
   console.log(JSON.stringify(value, null, 2));
 }
 
+function printInteractiveOutputGap(invocation: CliInvocation): void {
+  if (wantsJson(invocation) || !process.stdout.isTTY) return;
+  console.log("");
+}
+
 function printPlan(plan: WorkflowPlan): void {
   console.log(`${plan.workflow}: ${plan.cachedNodeCount}/${plan.nodeCount} nodes cached`);
 
@@ -1760,15 +1875,35 @@ function printWorkspaces(
   }
 
   printTable(
-    ["name", "workflow", "created"],
+    ["name", "workflow", "created", "age"],
     workspaces.map((workspace) => [
       workspace.name,
       workspace.workflow,
       workspace.createdAt,
+      formatWorkspaceAge(workspace.createdAt),
     ]),
   );
 }
 
+function formatWorkspaceAge(createdAt: string): string {
+  const createdTime = Date.parse(createdAt);
+  if (Number.isNaN(createdTime)) return chalk.dim("unknown");
+
+  const ageMs = Math.max(0, Date.now() - createdTime);
+  const minute = 60 * 1000;
+  const hour = 60 * minute;
+  const day = 24 * hour;
+  const label = ageMs < hour
+    ? `${Math.max(1, Math.floor(ageMs / minute))}m`
+    : ageMs < day
+      ? `${Math.floor(ageMs / hour)}h`
+      : `${Math.floor(ageMs / day)}d`;
+
+  if (ageMs < day) return chalk.green(label);
+  if (ageMs <= 3 * day) return chalk.yellow(label);
+  return chalk.red(label);
+}
+
 function printSnapshots(snapshots: SnapshotRecord[]): void {
   if (snapshots.length === 0) {
     console.log("No snapshots.");

package/src/completion.test.ts

@@ -11,8 +11,8 @@ describe("CLI completion", () => {
     await withWorkspaceRuntime({ projectDir }, async () => {
       const items = await completeRig({
         cwd: projectDir,
-        words: ["rig", "ssh", ""],
-        currentIndex: 2,
+        words: ["rig", "run", "ssh", ""],
+        currentIndex: 3,
       });
 
       expect(items.map((item) => item.value)).toEqual(["api", "web"]);
@@ -25,8 +25,8 @@ describe("CLI completion", () => {
     await withWorkspaceRuntime({ projectDir }, async () => {
       const items = await completeRig({
         cwd: projectDir,
-        words: ["rig", "ssh", "vm-"],
-        currentIndex: 2,
+        words: ["rig", "run", "ssh", "vm-"],
+        currentIndex: 3,
       });
 
       expect(items).toEqual([]);
@@ -39,8 +39,8 @@ describe("CLI completion", () => {
     await withWorkspaceRuntime({ projectDir, cleanupDir: parentDir }, async () => {
       const items = await completeRig({
         cwd: parentDir,
-        words: ["rig", "-C", "project", "ssh", ""],
-        currentIndex: 4,
+        words: ["rig", "-C", "project", "run", "ssh", ""],
+        currentIndex: 5,
       });
 
       expect(items.map((item) => item.value)).toEqual(["api", "web"]);
@@ -55,15 +55,42 @@ describe("CLI completion", () => {
         words: ["rig", "run", ""],
         currentIndex: 2,
       });
-      expect(roots.map((item) => item.value)).toContain("api/");
+      expect(roots.map((item) => item.value)).toContain("api");
       expect(roots.map((item) => item.value)).toContain("ssh");
 
-      const operations = await completeRig({
+      const exactWorkspace = await completeRig({
+        cwd: projectDir,
+        words: ["rig", "run", "api"],
+        currentIndex: 2,
+      });
+      expect(exactWorkspace.map((item) => item.value)).toEqual(["api/remove", "api/open-cmux"]);
+
+      const workspaceAfterSpace = await completeRig({
+        cwd: projectDir,
+        words: ["rig", "run", "api", ""],
+        currentIndex: 3,
+      });
+      expect(workspaceAfterSpace.map((item) => item.value)).toEqual(["api/remove", "api/open-cmux"]);
+
+      const slashWorkspace = await completeRig({
         cwd: projectDir,
         words: ["rig", "run", "api/"],
         currentIndex: 2,
       });
-      expect(operations.map((item) => item.value)).toEqual(["api/remove", "api/open-cmux"]);
+      expect(slashWorkspace.map((item) => item.value)).toEqual(["api/remove", "api/open-cmux"]);
+    });
+  });
+
+  test("does not complete runtime operations at the root command position", async () => {
+    const projectDir = mkdtempSync(join(tmpdir(), "rigkit-completion-"));
+    await withWorkspaceRuntime({ projectDir }, async () => {
+      const items = await completeRig({
+        cwd: projectDir,
+        words: ["rig", "s"],
+        currentIndex: 1,
+      });
+
+      expect(items.map((item) => item.value)).not.toContain("ssh");
     });
   });
 
@@ -72,7 +99,10 @@ describe("CLI completion", () => {
 
     expect(formatCompletionItems(items, "bash")).toBe("api");
     expect(formatCompletionItems(items, "zsh")).toBe("api\tvm-api");
+    expect(formatCompletionItems([{ value: "api", description: "workspace smoke", noSpace: true }], "zsh"))
+      .toBe("api\tworkspace smoke\tnospace");
     expect(renderCompletionScript("zsh")).toContain("rig __complete");
+    expect(renderCompletionScript("zsh")).toContain("compadd -S ''");
   });
 
   test("completes ls targets", async () => {

package/src/completion.ts

@@ -6,6 +6,7 @@ export type CompletionShell = "bash" | "fish" | "zsh";
 export type CompletionItem = {
   value: string;
   description?: string;
+  noSpace?: boolean;
 };
 
 type CompleteRigInput = {
@@ -102,31 +103,10 @@ export async function completeRig(input: CompleteRigInput): Promise<CompletionIt
   if (expectsOptionValue(before)) return [];
 
   if (!command) {
-    const rootOperation = parseRootOperation(before);
-    if (rootOperation.operation) {
-      if (current.startsWith("-")) {
-        const operation = await safeResolveRuntimeOperation(resolveProjectDir(words, cwd), rootOperation.operation);
-        return filterItems([
-          ...(operation?.cli?.options ?? []).flatMap((option) => [
-            { value: option.flag, description: option.name },
-            ...(option.aliases ?? []).map((alias) => ({ value: alias, description: option.name })),
-          ]),
-          ...COMMAND_OPTIONS.operation,
-          ...GLOBAL_OPTIONS,
-        ], current);
-      }
-      const operation = await safeResolveRuntimeOperation(resolveProjectDir(words, cwd), rootOperation.operation);
-      const operationPositionalCount = countRunOperationPositionals(rootOperation.args);
-      const positional = operation?.cli?.positionals?.find((item) => item.index === operationPositionalCount);
-      if (positional && /workspace|vm/i.test(positional.name)) {
-        return filterItems(await workspaceTargets(resolveProjectDir(words, cwd), current, /vm/i.test(positional.name)), current);
-      }
-      return [];
-    }
     return filterItems(
       current.startsWith("-")
         ? GLOBAL_OPTIONS
-        : [...COMMANDS, ...await safeOperationTargets(resolveProjectDir(words, cwd), current), ...GLOBAL_OPTIONS],
+        : [...COMMANDS, ...GLOBAL_OPTIONS],
       current,
     );
   }
@@ -157,6 +137,9 @@ export async function completeRig(input: CompleteRigInput): Promise<CompletionIt
       return filterItems(await safeOperationTargets(resolveProjectDir(words, cwd), current), current);
     }
     const operation = await safeResolveRuntimeOperation(resolveProjectDir(words, cwd), run.operation);
+    if (!operation && run.args.length === 0) {
+      return filterItems(await safeWorkspaceOperationTargets(resolveProjectDir(words, cwd), run.operation), current);
+    }
     const operationPositionalCount = countRunOperationPositionals(run.args);
     const positional = operation?.cli?.positionals?.find((item) => item.index === operationPositionalCount);
     if (positional && /workspace|vm/i.test(positional.name)) {
@@ -178,6 +161,9 @@ export async function completeRig(input: CompleteRigInput): Promise<CompletionIt
 export function formatCompletionItems(items: CompletionItem[], shell: CompletionShell): string {
   const lines = items.map((item) => {
     if (shell === "bash") return item.value;
+    if (shell === "zsh" && item.noSpace) {
+      return `${item.value}\t${item.description ?? ""}\tnospace`;
+    }
     return item.description ? `${item.value}\t${item.description}` : item.value;
   });
   return lines.join("\n");
@@ -217,22 +203,33 @@ complete -c rig -f -a "(__rig_complete)"
 `;
   }
 
-  return `#compdef rig
+return `#compdef rig
 # rig zsh completion
 _rig() {
-  local -a raw completions
-  local line value description
+  local -a raw values descriptions nospace_values nospace_descriptions
+  local line value description rest marker
   raw=("\${(@f)$(command rig __complete --shell zsh --index $((CURRENT - 1)) -- "\${words[@]}" 2>/dev/null)}")
   for line in "\${raw[@]}"; do
     value="\${line%%$'\\t'*}"
+    description=""
+    marker=""
     if [[ "$line" == *$'\\t'* ]]; then
-      description="\${line#*$'\\t'}"
-      completions+=("\${value}:\${description}")
+      rest="\${line#*$'\\t'}"
+      description="\${rest%%$'\\t'*}"
+      if [[ "$rest" == *$'\\t'* ]]; then
+        marker="\${rest#*$'\\t'}"
+      fi
+    fi
+    if [[ "$marker" == "nospace" ]]; then
+      nospace_values+=("\${value}")
+      nospace_descriptions+=("\${description}")
     else
-      completions+=("\${value}")
+      values+=("\${value}")
+      descriptions+=("\${description}")
     fi
   done
-  _describe 'rig' completions
+  (( \${#nospace_values} )) && compadd -S '' -d nospace_descriptions -a nospace_values
+  (( \${#values} )) && compadd -d descriptions -a values
 }
 compdef _rig rig
 `;
@@ -298,21 +295,6 @@ function parseRunCommand(words: string[]): { operation?: string; args: string[]
   return { operation: args[0], args: args.slice(1) };
 }
 
-function parseRootOperation(words: string[]): { operation?: string; args: string[] } {
-  const args: string[] = [];
-  for (let index = 0; index < words.length; index += 1) {
-    const word = words[index]!;
-    if (OPTIONS_WITH_VALUES.has(word)) {
-      index += 1;
-      continue;
-    }
-    if (word.startsWith("--") && word.includes("=")) continue;
-    if (word.startsWith("-")) continue;
-    args.push(word);
-  }
-  return { operation: args[0], args: args.slice(1) };
-}
-
 function countRunOperationPositionals(args: string[]): number {
   let count = 0;
   for (let index = 0; index < args.length; index += 1) {
@@ -392,15 +374,35 @@ async function operationTargets(
     return workspaceOperationTargets(manifest, current);
   }
   const workspaces = await readWorkspaces(paths).catch(() => []);
+  if (workspaces.some((workspace) => workspace.name === current)) {
+    return workspaceOperationTargets(manifest, `${current}/`);
+  }
   return manifest.operations.flatMap((operation) => [
     { value: operation.id, description: operation.description },
     ...(operation.aliases ?? []).map((alias) => ({ value: alias, description: operation.description })),
   ]).concat(workspaces.map((workspace) => ({
-    value: `${workspace.name}/`,
+    value: workspace.name,
     description: `workspace ${workspace.workflow}`,
+    noSpace: true,
   })));
 }
 
+async function safeWorkspaceOperationTargets(
+  paths: { projectDir: string; configPath: string },
+  workspace: string,
+): Promise<CompletionItem[]> {
+  try {
+    const [manifest, workspaces] = await Promise.all([
+      readOperations(paths),
+      readWorkspaces(paths),
+    ]);
+    if (!workspaces.some((item) => item.name === workspace)) return [];
+    return workspaceOperationTargets(manifest, `${workspace}/`);
+  } catch {
+    return [];
+  }
+}
+
 function workspaceOperationTargets(manifest: RuntimeOperationManifest, current: string): CompletionItem[] {
   const slash = current.indexOf("/");
   if (slash < 0) return [];

package/src/init.test.ts

@@ -3,7 +3,12 @@ import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { initProject, normalizeMachineName } from "./init.ts";
-import { FREESTYLE_PROVIDER_PACKAGE_NAME, PROJECT_PACKAGE_NAME } from "./project.ts";
+import {
+  FREESTYLE_PROVIDER_PACKAGE_NAME,
+  FREESTYLE_SDK_PACKAGE_NAME,
+  FREESTYLE_SDK_PACKAGE_VERSION,
+  PROJECT_PACKAGE_NAME,
+} from "./project.ts";
 import { RIGKIT_CLI_VERSION } from "./version.ts";
 
 describe("initProject", () => {
@@ -14,7 +19,6 @@ describe("initProject", () => {
       projectDir,
       configPath: join(projectDir, "rig.config.ts"),
       name: "Platform API",
-      apiKey: "fs_test_123",
     });
 
     expect(result.name).toBe("platform-api");
@@ -22,24 +26,27 @@ describe("initProject", () => {
     expect(existsSync(projectDir)).toBe(true);
     expect(result.created).toEqual({
       config: true,
-      env: true,
-      envExample: true,
+      env: false,
+      envExample: false,
       gitignore: true,
       packageJson: true,
     });
 
     expect(readFileSync(join(projectDir, "rig.config.ts"), "utf8")).toContain('sequence("platform-api"');
     expect(readFileSync(join(projectDir, "rig.config.ts"), "utf8")).toContain("defineConfig({");
-    expect(readFileSync(join(projectDir, ".env"), "utf8")).toBe("FREESTYLE_API_KEY=fs_test_123\n");
-    expect(readFileSync(join(projectDir, ".env.example"), "utf8")).toBe("FREESTYLE_API_KEY=\n");
+    expect(readFileSync(join(projectDir, "rig.config.ts"), "utf8")).toContain("new VmSpec()");
+    expect(readFileSync(join(projectDir, "rig.config.ts"), "utf8")).not.toContain("FREESTYLE_API_KEY");
+    expect(existsSync(join(projectDir, ".env"))).toBe(false);
+    expect(existsSync(join(projectDir, ".env.example"))).toBe(false);
     expect(readFileSync(join(projectDir, ".gitignore"), "utf8")).toContain(".env\n.rigkit/\n");
 
     const pkg = JSON.parse(readFileSync(join(projectDir, "package.json"), "utf8"));
     expect(pkg.name).toBe("platform-api");
-    expect(pkg.scripts.plan).toBe("rig plan");
-    expect(pkg.scripts.apply).toBe("rig apply");
+    expect(pkg.scripts.plan).toBe("rig run plan");
+    expect(pkg.scripts.apply).toBe("rig run apply");
     expect(pkg.devDependencies[PROJECT_PACKAGE_NAME]).toBe(RIGKIT_CLI_VERSION);
     expect(pkg.devDependencies[FREESTYLE_PROVIDER_PACKAGE_NAME]).toBe(RIGKIT_CLI_VERSION);
+    expect(pkg.devDependencies[FREESTYLE_SDK_PACKAGE_NAME]).toBe(FREESTYLE_SDK_PACKAGE_VERSION);
   });
 
   test("updates existing project files without replacing package metadata", () => {
@@ -67,7 +74,7 @@ describe("initProject", () => {
     const pkg = JSON.parse(readFileSync(join(projectDir, "package.json"), "utf8"));
     expect(pkg.name).toBe("existing");
     expect(pkg.scripts.test).toBe("bun test");
-    expect(pkg.scripts.plan).toBe("rig plan");
+    expect(pkg.scripts.plan).toBe("rig run plan");
   });
 });
 

package/src/init.ts

@@ -1,13 +1,18 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { RIGKIT_CLI_VERSION } from "./version.ts";
-import { FREESTYLE_PROVIDER_PACKAGE_NAME, PROJECT_PACKAGE_NAME } from "./project.ts";
+import {
+  FREESTYLE_PROVIDER_PACKAGE_NAME,
+  FREESTYLE_SDK_PACKAGE_NAME,
+  FREESTYLE_SDK_PACKAGE_VERSION,
+  PROJECT_PACKAGE_NAME,
+} from "./project.ts";
 
 export type InitProjectInput = {
   projectDir: string;
   configPath: string;
   name: string;
-  apiKey: string;
+  apiKey?: string;
   force?: boolean;
 };
 
@@ -47,11 +52,14 @@ export function initProject(input: InitProjectInput): InitProjectResult {
     writeFileSync(input.configPath, starterConfig(name));
   }
 
+  const apiKey = input.apiKey?.trim();
   const envPath = join(input.projectDir, ".env");
-  const env = writeEnvFile(envPath, input.apiKey);
+  const env = apiKey
+    ? writeEnvFile(envPath, apiKey)
+    : { created: false, updated: false };
 
   const envExamplePath = join(input.projectDir, ".env.example");
-  const wroteEnvExample = !existsSync(envExamplePath);
+  const wroteEnvExample = Boolean(apiKey) && !existsSync(envExamplePath);
   if (wroteEnvExample) {
     writeFileSync(envExamplePath, "FREESTYLE_API_KEY=\n");
   }
@@ -94,32 +102,46 @@ export function normalizeMachineName(value: string): string {
 export function starterConfig(name: string): string {
   const workflowName = JSON.stringify(normalizeMachineName(name));
 
-  return `import { defineConfig, env, sequence } from "@rigkit/sdk";
-import { freestyle } from "@rigkit/provider-freestyle";
+  return `import { defineConfig, sequence } from "@rigkit/sdk";
+import { freestyle, VmBaseImage, VmSpec } from "@rigkit/provider-freestyle";
 
-const freestyleProvider = freestyle.provider({
-  apiKey: () => env.secret("FREESTYLE_API_KEY"),
-  image: "node-22",
-});
+const vmIdleTimeoutSeconds = 3600;
+const vmSpec = new VmSpec()
+  .baseImage(new VmBaseImage("FROM node:22"))
+  .idleTimeoutSeconds(vmIdleTimeoutSeconds);
+
+const freestyleProvider = freestyle.provider();
 
 const dev = sequence(${workflowName})
-  .step("verify-node-22", async ({ providers }) => {
-    const vm = await providers.freestyle.vms.create();
-    const result = await vm.probe("node --version", { name: "node is v22" });
-    if (!result.ok || !result.stdout.trim().startsWith("v22.")) {
-      throw new Error(\`Expected Node.js v22, got: \${result.stdout}\${result.stderr}\`);
+  .step("verify-node-22", async ({ providers, step }) => {
+    const { vm, vmId } = await providers.freestyle.client.vms.create({
+      spec: vmSpec,
+      logger: step.log,
+    });
+    try {
+      const result = await vm.exec("node --version");
+      if ((result.statusCode ?? 0) !== 0 || !result.stdout.trim().startsWith("v22.")) {
+        throw new Error(\`Expected Node.js v22, got: \${result.stdout}\${result.stderr}\`);
+      }
+      const snapshot = await vm.snapshot();
+      return { ctx: { snapshotId: snapshot.snapshotId } };
+    } finally {
+      await providers.freestyle.client.vms.delete({ vmId });
     }
-    return { vm: await vm.snapshotRef() };
   })
   .workspace({
-    create: async ({ workflow, providers }) => {
-      const vm = await providers.freestyle.vms.fromSnapshot(workflow.ctx.vm);
+    create: async ({ workflow, providers, step }) => {
+      const { vmId } = await providers.freestyle.client.vms.create({
+        snapshotId: workflow.ctx.snapshotId,
+        idleTimeoutSeconds: vmIdleTimeoutSeconds,
+        logger: step.log,
+      });
       return {
-        vmId: vm.vmId,
+        vmId,
       };
     },
     remove: async ({ providers, workspace }) => {
-      await providers.freestyle.vms.delete(workspace.ctx.vmId);
+      await providers.freestyle.client.vms.delete({ vmId: workspace.ctx.vmId });
     },
   });
 
@@ -207,7 +229,7 @@ function ensureProjectPackageJson(
   }
 
   const scripts = pkg.scripts as Record<string, string>;
-  for (const [key, value] of Object.entries({ plan: "rig plan", apply: "rig apply" })) {
+  for (const [key, value] of Object.entries({ plan: "rig run plan", apply: "rig run apply" })) {
     if (scripts[key] !== value) {
       scripts[key] = value;
       updated = true;
@@ -218,11 +240,13 @@ function ensureProjectPackageJson(
   const devDependencies = isRecord(pkg.devDependencies) ? pkg.devDependencies : {};
   const sdkDependencyChanged =
     devDependencies[PROJECT_PACKAGE_NAME] !== RIGKIT_CLI_VERSION ||
-    devDependencies[FREESTYLE_PROVIDER_PACKAGE_NAME] !== RIGKIT_CLI_VERSION;
+    devDependencies[FREESTYLE_PROVIDER_PACKAGE_NAME] !== RIGKIT_CLI_VERSION ||
+    devDependencies[FREESTYLE_SDK_PACKAGE_NAME] !== FREESTYLE_SDK_PACKAGE_VERSION;
   if (sdkDependencyChanged) {
     delete devDependencies["@rigkit/runtime"];
     devDependencies[PROJECT_PACKAGE_NAME] = RIGKIT_CLI_VERSION;
     devDependencies[FREESTYLE_PROVIDER_PACKAGE_NAME] = RIGKIT_CLI_VERSION;
+    devDependencies[FREESTYLE_SDK_PACKAGE_NAME] = FREESTYLE_SDK_PACKAGE_VERSION;
     updated = true;
   }
   pkg.devDependencies = sortObject(devDependencies);

package/src/project.ts

@@ -4,6 +4,8 @@ import { existsSync, readdirSync } from "node:fs";
 export const DEFAULT_CONFIG_FILE = "rig.config.ts";
 export const PROJECT_PACKAGE_NAME = "@rigkit/sdk";
 export const FREESTYLE_PROVIDER_PACKAGE_NAME = "@rigkit/provider-freestyle";
+export const FREESTYLE_SDK_PACKAGE_NAME = "freestyle";
+export const FREESTYLE_SDK_PACKAGE_VERSION = "^0.1.51";
 
 export type ConfigPathOptions = {
   project?: string;

package/src/version.ts

@@ -1 +1 @@
-export const RIGKIT_CLI_VERSION = "0.2.3";
+export const RIGKIT_CLI_VERSION = "0.2.5";