@ishlabs/cli 0.8.1 → 0.8.2

package/dist/commands/iteration.js

@@ -1,13 +1,102 @@
 /**
- * ish iteration — Manage iterations (usually created via `simulation run`).
+ * ish iteration — Manage iterations of a study.
+ *
+ * An iteration carries the run-time details (URL for interactive,
+ * content/file for media). Create one before `ish study run` dispatches
+ * simulations against it.
  */
 import { withClient, resolveStudy } from "../lib/command-helpers.js";
 import { resolveId, tagAlias, ALIAS_PREFIX } from "../lib/alias-store.js";
 import { output, formatIterationList } from "../lib/output.js";
+import { resolveContentUrl, resolveContentUrls, resolveTextContent } from "../lib/upload.js";
+import { MEDIA_MODALITIES } from "../lib/types.js";
+function isMediaModality(modality) {
+    return !!modality && MEDIA_MODALITIES.includes(modality);
+}
+function buildCopyContent(opts) {
+    if (!opts.copyText)
+        return undefined;
+    return {
+        text: opts.copyText,
+        ...(opts.copyHtml && { html: opts.copyHtml }),
+        ...(opts.socialPlatform && { social_platform: opts.socialPlatform }),
+        ...(opts.copyPosition && { position: opts.copyPosition }),
+    };
+}
+function buildIterationDetails(modality, opts) {
+    switch (modality) {
+        case "text":
+            if (!opts.contentText) {
+                throw new Error("Text iterations require --content-text. Provide the text content to evaluate.");
+            }
+            return {
+                type: "text",
+                content_text: opts.contentText,
+                ...(opts.contentHtml && { content_html: opts.contentHtml }),
+                ...(opts.title && { title: opts.title }),
+                ...(opts.mimeType && { mime_type: opts.mimeType }),
+            };
+        case "video":
+        case "audio": {
+            if (!opts.contentUrl) {
+                throw new Error(`${modality} iterations require --content-url. Provide the URL or local file path.`);
+            }
+            const copy = buildCopyContent(opts);
+            return {
+                type: modality,
+                content_url: opts.contentUrl,
+                ...(opts.title && { title: opts.title }),
+                ...(opts.mimeType && { mime_type: opts.mimeType }),
+                ...(copy && { copy_content: copy }),
+            };
+        }
+        case "image": {
+            if (!opts.imageUrls) {
+                throw new Error("Image iterations require --image-urls. Provide comma-separated URLs or local file paths.");
+            }
+            const copy = buildCopyContent(opts);
+            return {
+                type: "image",
+                image_urls: opts.imageUrls.split(",").map((s) => s.trim()).filter(Boolean),
+                ...(opts.title && { title: opts.title }),
+                ...(opts.mimeType && { mime_type: opts.mimeType }),
+                ...(copy && { copy_content: copy }),
+            };
+        }
+        case "document":
+            if (!opts.contentUrl) {
+                throw new Error("Document iterations require --content-url. Provide the URL or local file path.");
+            }
+            return {
+                type: "document",
+                content_url: opts.contentUrl,
+                ...(opts.title && { title: opts.title }),
+                ...(opts.mimeType && { mime_type: opts.mimeType }),
+            };
+        default:
+            if (!opts.url) {
+                throw new Error("Interactive iterations require --url. Provide the URL to test.");
+            }
+            return {
+                type: "interactive",
+                platform: opts.platform || "browser",
+                url: opts.url,
+                screen_format: opts.screenFormat || "desktop",
+                ...(opts.locale && { locale: opts.locale }),
+            };
+    }
+}
 export function registerIterationCommands(program) {
     const iteration = program
         .command("iteration")
-        .description("Manage iterations (usually created via `simulation run`)");
+        .description("Manage iterations of a study (a study's run-time configuration)")
+        .addHelpText("after", `
+An iteration is one configured run of a study — it carries the URL (interactive) or
+media content (text/video/image/document). A study has 1..N iterations; \`ish study run\`
+defaults to the latest. Local file paths in --content-url / --image-urls are auto-uploaded.
+
+Concept pages: ish docs get-page concepts/iteration
+                ish docs get-page concepts/study`);
     iteration
         .command("list")
         .description("List iterations for a study")
@@ -16,53 +105,176 @@ export function registerIterationCommands(program) {
         .action(async (opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
             const data = await client.get(`/studies/${resolveStudy(opts.study)}/iterations`);
-            formatIterationList(data, globals.json);
+            const rows = data;
+            if (globals.json) {
+                // Legacy iterations come back with `name`, `description`, `details`
+                // set to null. The default lean-JSON pass strips nulls, which makes
+                // those keys disappear from the output and breaks consumers doing
+                // `it.details?.type` — the row would be missing the key entirely.
+                // Project to a stable, agent-friendly shape and bypass leanJson.
+                const projected = rows.map((it) => ({
+                    id: it.id ?? null,
+                    alias: it.id ? tagAlias(ALIAS_PREFIX.iteration, String(it.id)) : null,
+                    label: it.label ?? null,
+                    name: it.name ?? null,
+                    description: it.description ?? null,
+                    details: it.details ?? null,
+                    order_index: it.order_index ?? null,
+                    created_at: it.created_at ?? null,
+                }));
+                output(projected, true, { preProjected: true });
+                return;
+            }
+            formatIterationList(rows, globals.json);
         });
     });
     iteration
         .command("create")
-        .description("Create a new iteration (low-level)")
-        .option("--study <id>", "Study ID")
-        .requiredOption("--name <name>", "Iteration name")
+        .description("Create a new iteration with run-time content/URL")
+        .option("--study <id>", "Study ID (or set via `ish study use`)")
+        .option("--name <name>", "Iteration name (auto-generated if omitted)")
         .option("--description <description>", "Iteration description")
-        .option("--details-json <json>", "Iteration details as JSON string")
+        // Interactive
+        .option("--platform <platform>", "Platform (browser, android, figma, code) — interactive only")
+        .option("--url <url>", "URL to test — interactive only")
+        .option("--screen-format <format>", "Screen format (mobile_portrait, desktop) — interactive only")
+        .option("--locale <locale>", "Locale code (e.g. en-US) — interactive only")
+        // Media text
+        .option("--content-text <text>", "Text content to evaluate, or @filepath to read from file — text modality")
+        .option("--content-html <html>", "HTML version of the text, or @filepath to read from file — text modality")
+        // Media video/audio/document
+        .option("--content-url <url>", "URL or local file path to media file — video, audio, document modalities")
+        // Media image
+        .option("--image-urls <urls>", "Comma-separated image URLs or local file paths — image modality")
+        // Shared media
+        .option("--title <title>", "Content title — media modalities")
+        .option("--mime-type <type>", "MIME type (e.g. video/mp4) — media modalities")
+        // Copy/caption
+        .option("--copy-text <text>", "Ad copy or social post caption (or @filepath) — ads & social posts")
+        .option("--copy-html <html>", "HTML version of copy text (or @filepath)")
+        .option("--social-platform <platform>", "Social platform (instagram, tiktok, facebook, linkedin, x)")
+        .option("--copy-position <pos>", "Copy position relative to media (before, after)", "after")
+        // Escape hatch
+        .option("--details-json <json>", "Raw iteration details JSON (overrides individual flags)")
         .addHelpText("after", `
+Note: --study is optional if set via \`ish study use <alias>\`. Local files
+  passed to --content-url, --image-urls, --content-text, etc. are uploaded
+  automatically. Use @filepath for text-style flags to read from a file.
+
 Examples:
-  # Interactive:
-  $ ish iteration create --study S --name "v1" \\
-    --details-json '{"type":"interactive","platform":"browser","url":"https://example.com","screen_format":"desktop"}'
+  # Interactive (URL):
+  $ ish iteration create --study s-b2c --url https://example.com
 
-  # Text/email:
-  $ ish iteration create --study S --name "v1" \\
-    --details-json '{"type":"text","content_text":"Your email content here","title":"Newsletter"}'
+  # Interactive on mobile:
+  $ ish iteration create --url https://example.com --screen-format mobile_portrait
 
-  # Video:
-  $ ish iteration create --study S --name "v1" \\
-    --details-json '{"type":"video","content_url":"https://cdn.example.com/video.mp4","mime_type":"video/mp4"}'
+  # Text/email (inline or @file):
+  $ ish iteration create --content-text "Your email content..."
+  $ ish iteration create --content-text @./email.html --title "Newsletter"
 
-  # Image:
-  $ ish iteration create --study S --name "v1" \\
-    --details-json '{"type":"image","image_urls":["https://cdn.example.com/a.png","https://cdn.example.com/b.png"]}'
+  # Video (URL or local file — local files auto-uploaded):
+  $ ish iteration create --content-url ./video.mp4
+
+  # Image set:
+  $ ish iteration create --image-urls "./a.png,./b.png"
 
   # Document (PDF):
-  $ ish iteration create --study S --name "v1" \\
-    --details-json '{"type":"document","content_url":"https://cdn.example.com/report.pdf","mime_type":"application/pdf"}'
+  $ ish iteration create --content-url ./report.pdf
+
+  # Video ad with copy text:
+  $ ish iteration create --content-url ./ad.mp4 --copy-text "Buy now — 50% off!"
+
+  # Social post with caption:
+  $ ish iteration create --image-urls ./post.png \\
+      --copy-text @./caption.txt --social-platform instagram
+
+  # Raw JSON escape hatch (overrides individual flags):
+  $ ish iteration create --study s-b2c --details-json \\
+      '{"type":"interactive","platform":"browser","url":"https://example.com","screen_format":"desktop"}'
+
+Local files passed to --content-url, --image-urls, etc. are uploaded to the
+workspace's public storage bucket. Validation now happens before upload.
 
-  Note: For local file uploads, use \`ish simulation run\` which automatically
-  uploads files and resolves URLs (e.g. --content-url ./video.mp4).`)
+Next: \`ish study run\` to dispatch simulations against this iteration.`)
         .action(async (opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
+            const studyId = resolveStudy(opts.study);
+            let details;
+            if (opts.detailsJson) {
+                try {
+                    details = JSON.parse(opts.detailsJson);
+                }
+                catch {
+                    throw new Error("Invalid --details-json: expected valid JSON string");
+                }
+            }
+            else {
+                // Need the study's modality to validate flags + shape details
+                const study = await client.get(`/studies/${studyId}`);
+                const modality = study.modality || "interactive";
+                const isMedia = isMediaModality(modality);
+                if (isMedia && opts.url) {
+                    throw new Error(`This study uses "${modality}" modality — --url is for interactive studies. Use --content-text, --content-url, or --image-urls instead.`);
+                }
+                if (!isMedia && (opts.contentText || opts.contentUrl || opts.imageUrls)) {
+                    throw new Error(`This study uses "interactive" modality — --content-text, --content-url, and --image-urls are for media studies. Use --url instead.`);
+                }
+                // Validate per-modality required flags BEFORE any upload so we don't
+                // orphan blobs in storage when the wrong flag is passed (e.g.
+                // --content-url to an image-modality study).
+                switch (modality) {
+                    case "text":
+                        if (!opts.contentText) {
+                            throw new Error("Text iterations require --content-text. Provide the text content to evaluate.");
+                        }
+                        break;
+                    case "video":
+                    case "audio":
+                        if (!opts.contentUrl) {
+                            throw new Error(`${modality} iterations require --content-url. Provide the URL or local file path.`);
+                        }
+                        break;
+                    case "image":
+                        if (!opts.imageUrls) {
+                            throw new Error("Image iterations require --image-urls. Provide comma-separated URLs or local file paths.");
+                        }
+                        break;
+                    case "document":
+                        if (!opts.contentUrl) {
+                            throw new Error("Document iterations require --content-url. Provide the URL or local file path.");
+                        }
+                        break;
+                    default:
+                        if (!opts.url) {
+                            throw new Error("Interactive iterations require --url. Provide the URL to test.");
+                        }
+                }
+                const resolved = { ...opts };
+                if (isMedia) {
+                    if (resolved.contentText)
+                        resolved.contentText = resolveTextContent(resolved.contentText);
+                    if (resolved.contentHtml)
+                        resolved.contentHtml = resolveTextContent(resolved.contentHtml);
+                    if (resolved.copyText)
+                        resolved.copyText = resolveTextContent(resolved.copyText);
+                    if (resolved.copyHtml)
+                        resolved.copyHtml = resolveTextContent(resolved.copyHtml);
+                    if (resolved.contentUrl) {
+                        resolved.contentUrl = await resolveContentUrl(client, studyId, resolved.contentUrl, { mimeTypeOverride: resolved.mimeType, quiet: globals.quiet });
+                    }
+                    if (resolved.imageUrls) {
+                        const urls = await resolveContentUrls(client, studyId, resolved.imageUrls, { mimeTypeOverride: resolved.mimeType, quiet: globals.quiet });
+                        resolved.imageUrls = urls.join(",");
+                    }
+                }
+                details = buildIterationDetails(modality, resolved);
+            }
             const body = {
-                name: opts.name,
+                name: opts.name || `CLI ${new Date().toISOString().slice(0, 16)}`,
                 ...(opts.description !== undefined && { description: opts.description }),
-                ...(opts.detailsJson && { details: (() => { try {
-                        return JSON.parse(opts.detailsJson);
-                    }
-                    catch {
-                        throw new Error("Invalid --details-json: expected valid JSON string");
-                    } })() }),
+                ...(details && { details }),
             };
-            const data = await client.post(`/studies/${resolveStudy(opts.study)}/iterations`, body);
+            const data = await client.post(`/studies/${studyId}/iterations`, body);
             const result = data;
             if (result.id)
                 result.alias = tagAlias(ALIAS_PREFIX.iteration, String(result.id));

package/dist/commands/profile.d.ts

@@ -0,0 +1,5 @@
+/**
+ * ish profile — Manage profiles, audience generation, and source uploads.
+ */
+import type { Command } from "commander";
+export declare function registerProfileCommands(program: Command): void;

package/dist/commands/profile.js

@@ -0,0 +1,313 @@
+/**
+ * ish profile — Manage profiles, audience generation, and source uploads.
+ */
+import { withClient, readJsonFileOrStdin, resolveWorkspace } from "../lib/command-helpers.js";
+import { resolveId, tagAlias, ALIAS_PREFIX } from "../lib/alias-store.js";
+import { formatTesterProfileList, formatGeneratedProfileList, output, } from "../lib/output.js";
+import { resolveTextContent } from "../lib/upload.js";
+import { isUuid, resolveSourceRef } from "../lib/profile-sources.js";
+function collect(value, prev) {
+    return prev.concat(value);
+}
+export function registerProfileCommands(program) {
+    const profile = program
+        .command("profile")
+        .alias("tester-profile")
+        .description("Manage profiles, audience generation, and source uploads")
+        .addHelpText("after", `
+A tester profile is a reusable audience persona scoped to a workspace.
+\`ish profile generate\` produces profiles from a written brief and/or sources
+(transcripts, audio, images, PDFs). Distinct from a "tester" (\`t-\`), which is one
+instance of a profile inside one iteration.
+
+Concept pages: ish docs get-page concepts/profile
+                ish docs get-page concepts/source
+                ish docs get-page concepts/audience`);
+    profile
+        .command("list")
+        .description("List profiles (defaults to simulatable AI profiles)")
+        .option("--workspace <id>", "Filter by workspace ID")
+        .option("--search <query>", "Free-text search (matches profile name and bio)")
+        .option("--type <type>", "Profile type: ai, human, all (default: ai)", "ai")
+        .option("--gender <gender>", "Filter by gender (repeatable)", collect, [])
+        .option("--country <country>", "Filter by country code, e.g. US (repeatable)", collect, [])
+        .option("--min-age <n>", "Minimum age")
+        .option("--max-age <n>", "Maximum age")
+        .option("--limit <n>", "Max results (default 50)", "50")
+        .option("--offset <n>", "Offset for pagination", "0")
+        .addHelpText("after", `
+Examples:
+  $ ish profile list
+  $ ish profile list --search "engineer" --country US
+  $ ish profile list --gender female --gender male --country US --country GB
+  $ ish profile list --type all --json`)
+        .action(async (opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const params = {
+                limit: opts.limit,
+                offset: opts.offset,
+            };
+            if (opts.workspace)
+                params.product_id = resolveWorkspace(opts.workspace);
+            if (opts.search)
+                params.search = opts.search;
+            if (opts.type !== "all")
+                params.type = opts.type;
+            if (opts.gender.length > 0)
+                params.gender = opts.gender;
+            if (opts.country.length > 0)
+                params.country = opts.country;
+            if (opts.minAge)
+                params.min_age = opts.minAge;
+            if (opts.maxAge)
+                params.max_age = opts.maxAge;
+            const data = await client.get("/tester-profiles", params);
+            formatTesterProfileList(data, globals.json, parseInt(opts.limit, 10));
+        });
+    });
+    profile
+        .command("create")
+        .description("Create a profile from an exact JSON spec (no LLM)")
+        .requiredOption("--file <path>", "JSON file with profile data")
+        .option("--workspace <id>", "Workspace (product) ID; falls back to active workspace")
+        .addHelpText("after", "\nExamples:\n  $ ish profile create --file profile.json\n\n  Expected JSON: { \"name\": \"...\", \"type\": \"ai\", \"gender\": \"female\", \"country\": \"US\", \"occupation\": \"...\", \"bio\": \"...\" }")
+        .action(async (opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const body = await readJsonFileOrStdin(opts.file);
+            if (opts.workspace)
+                body.product_id = resolveWorkspace(opts.workspace);
+            const data = await client.post("/tester-profiles", body);
+            const result = data;
+            if (result.id)
+                result.alias = tagAlias(ALIAS_PREFIX.testerProfile, String(result.id));
+            output(result, globals.json, { writePath: true });
+        });
+    });
+    profile
+        .command("generate")
+        .description("Generate one or many profiles via LLM (audience generation)")
+        .option("--description <text>", "Audience description (use @path to read from file)")
+        .option("--description-file <path>", "Read description from a file")
+        .option("--source <id-or-path>", "Source UUID or local file path; auto-uploads paths (repeatable)", collect, [])
+        .option("--source-description <text>", "Per-source context note (paired with --source by index, repeatable). Only applies to local-path sources — for already-uploaded aliases the description is whatever was set at upload time.", collect, [])
+        .option("--diarize", "Apply speaker diarization to audio sources (silently ignored for text/image)")
+        .option("--count <n>", "Number of profiles to generate (1-10). Omit to let the model propose")
+        .option("--propose-count", "Print the LLM's suggested audience size for a single processed source and exit (no generation)")
+        .option("--workspace <id>", "Workspace (product) ID; falls back to active workspace")
+        .option("--no-wait", "Don't poll source-processing status. Only relevant when --source is a local path (paths get auto-uploaded and processed).")
+        .option("--timeout <seconds>", "Source-processing poll timeout in seconds. Only relevant when --source is a local path.", "300")
+        .option("--include-simulation-config", "Include the full simulation_config (system prompt + model settings) on each generated profile in JSON output")
+        .addHelpText("after", `
+Examples:
+  # Generate 3 profiles from a description
+  $ ish profile generate --description "Tech-savvy millennials in the US who use mobile banking" --count 3
+
+  # Generate one profile from a transcript (auto-uploads the file)
+  $ ish profile generate --source ./interviews/sarah.txt --count 1
+
+  # Generate 5 profiles from an audio call + a written brief
+  $ ish profile generate --description "Voices behind support tickets" --source ./call.mp3 --diarize --count 5
+
+  # Use a previously-uploaded source by alias
+  $ ish profile generate --source tps-3a4 --count 2
+
+  # Ask the LLM how many profiles a processed source warrants (no generation)
+  $ ish profile generate --source tps-3a4 --propose-count`)
+        .action(async (opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const productId = resolveWorkspace(opts.workspace);
+            // --propose-count is a planning helper: requires exactly one already-uploaded
+            // source (UUID or alias), calls the propose-count endpoint, prints, and exits.
+            if (opts.proposeCount) {
+                if (opts.source.length !== 1) {
+                    throw new Error("--propose-count requires exactly one --source (a UUID or alias).");
+                }
+                if (opts.sourceDescription.length > 0) {
+                    throw new Error("--source-description doesn't apply to --propose-count: the source is already uploaded and its description is set at upload time. Drop --source-description, or set it at upload time via `ish source upload --description ...`.");
+                }
+                const raw = opts.source[0];
+                const id = isUuid(raw) ? raw : tryResolveSourceAlias(raw);
+                if (!id) {
+                    throw new Error("--propose-count expects an uploaded source ID or alias (e.g. tps-3a4). Upload first with `ish source upload`.");
+                }
+                const data = await client.post(`/tester-profiles/sources/${id}/propose-count`, undefined, { timeout: 60_000 });
+                output(data, globals.json);
+                return;
+            }
+            // Resolve description: explicit text, @path, or --description-file.
+            let description;
+            if (opts.description)
+                description = resolveTextContent(opts.description);
+            if (opts.descriptionFile) {
+                description = resolveTextContent(`@${opts.descriptionFile}`);
+            }
+            if (!description && opts.source.length === 0) {
+                throw new Error("Provide --description, --description-file, or at least one --source.");
+            }
+            const timeoutMs = Math.max(1, parseInt(opts.timeout, 10)) * 1000;
+            const wait = opts.wait !== false;
+            if (opts.sourceDescription.length > opts.source.length) {
+                throw new Error(`Got ${opts.sourceDescription.length} --source-description value(s) but only ${opts.source.length} --source value(s). Each --source-description is paired with --source by position; provide one --source per --source-description.`);
+            }
+            // Resolve every --source: UUIDs/aliases pass through; paths get uploaded.
+            const sourceIds = [];
+            for (let i = 0; i < opts.source.length; i++) {
+                const raw = opts.source[i];
+                const desc = opts.sourceDescription[i];
+                // Treat as alias if it matches our prefix pattern.
+                const candidate = isUuid(raw) ? raw : tryResolveSourceAlias(raw);
+                if (candidate) {
+                    // Already-uploaded source: the backend's GenerateAudienceRequest accepts
+                    // only source_upload_ids, no per-source description override. The
+                    // description set at upload time (ConfirmSourceUploadRequest.description)
+                    // is what the LLM sees. Silently dropping a CLI-supplied description here
+                    // is the M3 bug — error out instead so the user knows.
+                    if (desc !== undefined) {
+                        throw new Error(`--source-description for "${raw}" is ignored because that source is already uploaded — the description set at upload time is what generate uses.\n` +
+                            "Either:\n" +
+                            "  - Drop --source-description for this source, OR\n" +
+                            "  - Re-upload via path: --source <local-path> --source-description \"...\"");
+                    }
+                    sourceIds.push(candidate);
+                    continue;
+                }
+                const id = await resolveSourceRef(client, raw, {
+                    productId,
+                    description: desc,
+                    diarize: opts.diarize,
+                    wait,
+                    timeoutMs,
+                    quiet: globals.quiet,
+                });
+                sourceIds.push(id);
+            }
+            const body = {
+                product_id: productId,
+            };
+            if (description)
+                body.description = description;
+            if (sourceIds.length > 0)
+                body.source_upload_ids = sourceIds;
+            if (opts.count) {
+                const n = parseInt(opts.count, 10);
+                if (Number.isNaN(n) || n < 1 || n > 10) {
+                    throw new Error("--count must be an integer between 1 and 10.");
+                }
+                body.count = n;
+            }
+            // /generate is LLM-backed and slow.
+            const profiles = await client.post("/tester-profiles/generate", body, { timeout: 180_000 });
+            // simulation_config is the inlined system prompt + model settings — ~3.5KB
+            // of mostly-identical boilerplate per profile. Strip it from the default
+            // JSON output; users who need it can pass --include-simulation-config or
+            // fetch it later via `profile get --json`.
+            const trimmed = opts.includeSimulationConfig
+                ? profiles
+                : profiles.map((p) => {
+                    const { simulation_config: _drop, ...rest } = p;
+                    return rest;
+                });
+            formatGeneratedProfileList(trimmed, globals.json);
+        });
+    });
+    profile
+        .command("get")
+        .description("Get profile details")
+        .argument("<id>", "Profile ID")
+        .addHelpText("after", "\nExamples:\n  $ ish profile get <id>\n  $ ish profile get <id> --json")
+        .action(async (id, _opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const data = await client.get(`/tester-profiles/${resolveId(id)}`);
+            const result = data;
+            if (result.id)
+                result.alias = tagAlias(ALIAS_PREFIX.testerProfile, String(result.id));
+            output(result, globals.json);
+        });
+    });
+    profile
+        .command("update")
+        .description("Update a profile")
+        .argument("<id>", "Profile ID")
+        .option("--file <path>", "JSON file with update data (escape hatch for fields not covered by inline flags)")
+        .option("--name <text>", "Profile name")
+        .option("--description <text>", "Profile description")
+        .option("--bio <text>", "Profile bio")
+        .option("--occupation <text>", "Occupation")
+        .option("--country <code>", "Country code, e.g. US")
+        .option("--gender <g>", "Gender, e.g. female")
+        .option("--date-of-birth <YYYY-MM-DD>", "Date of birth")
+        .option("--tech-savviness <n>", "Tech savviness score")
+        .addHelpText("after", `
+Examples:
+  $ ish profile update <id> --bio "Edited bio"
+  $ ish profile update <id> --name "Alice" --country US --tech-savviness 8
+  $ ish profile update <id> --file updates.json
+
+Inline flags compose into the patch body. --file is an escape hatch when you
+need fields not covered by the inline flags. When both are provided, inline
+flags override values from --file.`)
+        .action(async (id, opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            let body = {};
+            if (opts.file) {
+                body = (await readJsonFileOrStdin(opts.file));
+            }
+            if (opts.name !== undefined)
+                body.name = opts.name;
+            if (opts.description !== undefined)
+                body.description = opts.description;
+            if (opts.bio !== undefined)
+                body.bio = opts.bio;
+            if (opts.occupation !== undefined)
+                body.occupation = opts.occupation;
+            if (opts.country !== undefined)
+                body.country = opts.country;
+            if (opts.gender !== undefined)
+                body.gender = opts.gender;
+            if (opts.dateOfBirth !== undefined)
+                body.date_of_birth = opts.dateOfBirth;
+            if (opts.techSavviness !== undefined) {
+                const n = parseInt(opts.techSavviness, 10);
+                if (Number.isNaN(n)) {
+                    throw new Error("--tech-savviness must be an integer.");
+                }
+                body.tech_savviness = n;
+            }
+            if (Object.keys(body).length === 0) {
+                throw new Error("Nothing to update. Provide --file or at least one inline flag (e.g. --bio).");
+            }
+            const data = await client.put(`/tester-profiles/${resolveId(id)}`, body);
+            const result = data;
+            if (result.id)
+                result.alias = tagAlias(ALIAS_PREFIX.testerProfile, String(result.id));
+            output(result, globals.json, { writePath: true });
+        });
+    });
+    profile
+        .command("delete")
+        .description("Delete a profile")
+        .argument("<id>", "Profile ID")
+        .addHelpText("after", "\nExamples:\n  $ ish profile delete <id>")
+        .action(async (id, _opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const rid = resolveId(id);
+            await client.del(`/tester-profiles/${rid}`);
+            output({ id: rid, alias: tagAlias(ALIAS_PREFIX.testerProfile, rid), message: "Profile deleted" }, globals.json, { writePath: true });
+        });
+    });
+}
+/**
+ * If the value matches the testerProfileSource alias pattern (e.g. "tps-3a4"),
+ * resolve it to the underlying UUID. Otherwise return undefined so the caller
+ * falls back to treating the value as a path.
+ */
+function tryResolveSourceAlias(value) {
+    if (!/^tps-[0-9a-f]{3,}$/.test(value))
+        return undefined;
+    try {
+        return resolveId(value);
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/commands/source.d.ts

@@ -0,0 +1,10 @@
+/**
+ * ish source — Upload and inspect audience-generation sources.
+ *
+ * Sources (transcripts, audio, images, PDFs) are inputs to `ish profile
+ * generate`. For one-shot generation, `profile generate --source <path>`
+ * auto-uploads. Use these commands to upload once and reuse across multiple
+ * generation runs, or to inspect processing status.
+ */
+import type { Command } from "commander";
+export declare function registerSourceCommands(program: Command): void;