feat: add --watch option to render command for polling until completion

Author: dazzatronus

README.md

@@ -50,11 +50,13 @@ SHOTSTACK_ENV=stage shotstack render template.json
 
 ### `shotstack render <file>`
 
-Submits a Shotstack Edit JSON to the render API. Returns a render ID.
+Submits a Shotstack Edit JSON to the render API. Returns a render ID. With `--watch`, polls until the render reaches a terminal state and prints the output URL — equivalent to `render` followed by `status --watch` but in one command.
 
 ```sh
 shotstack render my-template.json
 shotstack render my-template.json --output json
+shotstack render my-template.json --watch              # submit + poll until done
+shotstack render my-template.json --watch --output json
 ```
 
 ### `shotstack status <id>`

SKILL.md

@@ -32,13 +32,17 @@ Use `--env stage` for experimentation. Stage is free; v1 charges real credits. O
 ## Quickstart
 
 ```sh
-# Submit. Use --output json so the ID is parseable.
-shotstack render template.json --output json --env stage
+# Submit + poll in one command (most agent flows want this).
+shotstack render template.json --watch
+# → done  https://shotstack-api-v1-output.s3.amazonaws.com/.../01ja7-x8m2k-39rzv-cmvxve.mp4
+
+# Submit only (returns ID).
+shotstack render template.json --output json
 # → {"id":"01ja7-x8m2k-39rzv-cmvxve"}
 
-# Poll until terminal state.
-shotstack status 01ja7-x8m2k-39rzv-cmvxve --watch --env stage
-# → done  https://shotstack-api-stage-output.s3.amazonaws.com/.../01ja7-x8m2k-39rzv-cmvxve.mp4
+# Poll an existing render to terminal state.
+shotstack status 01ja7-x8m2k-39rzv-cmvxve --watch
+# → done  https://shotstack-api-v1-output.s3.amazonaws.com/.../01ja7-x8m2k-39rzv-cmvxve.mp4
 ```
 
 ## Hand-off to a human before rendering
@@ -57,11 +61,11 @@ Use `render` only when you're confident the JSON is final, or there's no human t
 
 ## Four CLI rules
 
-1. **Pipe → `--output json`.** Default output is human-readable. When parsing programmatically or piping to another command, always pass `--output json`. The text format is not stable across versions.
+1. **Pipe → `--output json`.** Default output is human-readable. When parsing programmatically or piping to another command, always pass `--output json`.
 
-2. **Use `--watch`, not a polling loop.** `shotstack status <id> --watch` exits when the render reaches `done` (exit 0) or `failed` (exit 1). Don't write `while true; do ...; sleep 3; done`.
+2. **Use `--watch`, not a polling loop.** `shotstack render <file> --watch` submits and polls in one shot; `shotstack status <id> --watch` polls an existing render. Both exit when terminal: `done` (exit 0) or `failed` (exit 1). Don't write `while true; do ...; sleep 3; done`.
 
-3. **Fetch the current docs before generating Edit JSON.** The Shotstack API evolves; LLM training data is often stale. Pull <https://shotstack.io/docs/guide/llms-full.txt> for the current schema and examples before composing an Edit from scratch.
+3. **Fetch the current schema and docs before generating Edit JSON.** The Shotstack API evolves; LLM training data is often stale. Pull <https://shotstack.io/docs/api/api.edit.json> and <https://shotstack.io/docs/guide/llms-full.txt> for the current schema and guides before composing an Edit from scratch.
 
 4. **Hand off to a human via `preview` when uncertain.** Don't burn render credits iterating. Generate JSON → `shotstack preview` → human reviews/tweaks → render only when right.
 

src/commands/render.ts

@@ -6,6 +6,7 @@ import { requireApiKey } from "../http/auth.ts";
 import { resolveEnv, ENV_NAMES } from "../http/env.ts";
 import { emit, parseOutputFormat } from "../output.ts";
 import { withRecording, commandArgv } from "../recorder.ts";
+import { pollStatus } from "./status.ts";
 
 interface RenderResponse {
   success: boolean;
@@ -17,8 +18,9 @@ export const renderCommand = new Command("render")
   .description("Submit a Shotstack Edit JSON to the render API")
   .argument("<file>", "Path to a Shotstack Edit JSON file")
   .option(`--env <name>`, `Environment: ${ENV_NAMES.join(" | ")}`)
+  .option("--watch", "After submitting, poll until the render reaches a terminal state")
   .option("--output <format>", "Output format: text | json", "text")
-  .action(async (file: string, options: { env?: string; output: string }) => {
+  .action(async (file: string, options: { env?: string; watch?: boolean; output: string }) => {
     await withRecording("render", commandArgv("render"), async () => {
       const format = parseOutputFormat(options.output);
       const apiKey = requireApiKey();
@@ -32,7 +34,13 @@ export const renderCommand = new Command("render")
       const result = await client.post<RenderResponse>("/render", template);
       const id = result.response.id;
 
-      emit(format, { id }, id);
-      return { renderId: id, response: result.response };
+      if (!options.watch) {
+        emit(format, { id }, id);
+        return { renderId: id, response: result.response };
+      }
+
+      const final = await pollStatus(client, id, format, true);
+      const exitCode = final.status === "failed" ? 1 : 0;
+      return { renderId: id, response: final, exitCode };
     });
   });

src/commands/status.ts

@@ -1,11 +1,11 @@
 import { Command } from "commander";
-import { createClient } from "../http/client.ts";
+import { createClient, type Client } from "../http/client.ts";
 import { requireApiKey } from "../http/auth.ts";
 import { resolveEnv, ENV_NAMES } from "../http/env.ts";
-import { emit, parseOutputFormat } from "../output.ts";
+import { emit, type OutputFormat, parseOutputFormat } from "../output.ts";
 import { withRecording, commandArgv } from "../recorder.ts";
 
-interface StatusResponse {
+export interface StatusResponse {
   success: boolean;
   message: string;
   response: {
@@ -18,6 +18,8 @@ interface StatusResponse {
   };
 }
 
+export type RenderStatus = StatusResponse["response"];
+
 const TERMINAL_STATES = new Set(["done", "failed"]);
 const POLL_INTERVAL_MS = 3000;
 
@@ -33,22 +35,24 @@ export const statusCommand = new Command("status")
       const apiKey = requireApiKey();
       const env = resolveEnv(options.env);
       const client = createClient({ apiKey, env });
-
-      while (true) {
-        const result = await client.get<StatusResponse>(`/render/${encodeURIComponent(id)}`);
-        const r = result.response;
-        emit(format, r, formatHuman(r));
-
-        if (!options.watch || TERMINAL_STATES.has(r.status)) {
-          const exitCode = r.status === "failed" ? 1 : 0;
-          return { renderId: r.id, response: r, exitCode };
-        }
-        await sleep(POLL_INTERVAL_MS);
-      }
+      const final = await pollStatus(client, id, format, options.watch === true);
+      const exitCode = final.status === "failed" ? 1 : 0;
+      return { renderId: final.id, response: final, exitCode };
     });
   });
 
-function formatHuman(r: StatusResponse["response"]): string {
+export async function pollStatus(client: Client, id: string, format: OutputFormat, watch: boolean): Promise<RenderStatus> {
+  while (true) {
+    const result = await client.get<StatusResponse>(`/render/${encodeURIComponent(id)}`);
+    const r = result.response;
+    emit(format, r, formatHuman(r));
+
+    if (!watch || TERMINAL_STATES.has(r.status)) return r;
+    await sleep(POLL_INTERVAL_MS);
+  }
+}
+
+function formatHuman(r: RenderStatus): string {
   const parts: string[] = [r.status];
   if (r.url) parts.push(r.url);
   if (r.error) parts.push(`error: ${r.error}`);

src/http/client.ts

@@ -21,6 +21,8 @@ export interface ClientOptions {
   env: ResolvedEnv;
 }
 
+export type Client = ReturnType<typeof createClient>;
+
 export function createClient(options: ClientOptions) {
   const baseUrl = options.env.baseUrl.replace(/\/$/, "");