@sixb/cli-core 0.1.8 → 0.1.9

package/dist/index.js

@@ -11,6 +11,7 @@ import { pipeline } from "stream/promises";
 var INSTANCE_CLI_VERSION = "1";
 var EXIT_USAGE = 2;
 var EXIT_API = 3;
+var EXIT_AWAITING_APPROVAL = 4;
 
 class CliError extends Error {
   body;
@@ -29,12 +30,29 @@ function writeJson(value) {
   process.stdout.write(`${JSON.stringify(value)}
 `);
 }
+
+class CliExit extends Error {
+  exitCode;
+  constructor(exitCode) {
+    super(`The Sixb CLI exited with code ${exitCode}.`);
+    this.exitCode = exitCode;
+    this.name = "CliExit";
+  }
+}
+function writeRequestResult(value) {
+  writeJson(value);
+  const status = typeof value === "object" && value !== null ? Reflect.get(value, "status") : null;
+  if (status === "awaiting_approval")
+    throw new CliExit(EXIT_AWAITING_APPROVAL);
+}
 function writeText(value) {
   process.stdout.write(value.endsWith(`
 `) ? value : `${value}
 `);
 }
 function reportError(error) {
+  if (error instanceof CliExit)
+    return error.exitCode;
   const cliError = error instanceof CliError ? error : new CliError({
     code: "internal_error",
     message: error instanceof Error ? error.message : "The Sixb CLI failed unexpectedly."
@@ -70,9 +88,10 @@ class ApiClient {
       ...options.signal ? { signal: options.signal } : {}
     });
   }
-  async upload(path, source, logicalPath) {
+  async upload(path, source, logicalPath, mediaType) {
     const form = new FormData;
-    form.append("file", new Blob([new Uint8Array(await readFile(source))]), basename(source));
+    const bytes = new Uint8Array(await readFile(source));
+    form.append("file", new Blob([bytes], mediaType ? { type: mediaType } : undefined), basename(source));
     if (logicalPath)
       form.append("logicalPath", logicalPath);
     return this.json(this.url(path), { method: "POST", body: form });
@@ -193,8 +212,9 @@ function parseCommandArgs(args, kinds, command, positionalCount = 0) {
     const flag = equals < 0 ? argument : argument.slice(0, equals);
     if (!Object.hasOwn(kinds, flag))
       fail(`Unknown ${command} option '${flag}'.`);
-    if (Object.hasOwn(options, flag))
+    if (Object.hasOwn(options, flag) && kinds[flag] !== "strings") {
       fail(`${flag} may only be provided once.`);
+    }
     if (kinds[flag] === "boolean") {
       if (equals >= 0)
         fail(`${flag} does not accept a value.`);
@@ -204,7 +224,8 @@ function parseCommandArgs(args, kinds, command, positionalCount = 0) {
       if (!value || equals < 0 && value.startsWith("--")) {
         fail(`${flag} requires a value.`);
       }
-      options[flag] = value;
+      const previous = options[flag];
+      options[flag] = kinds[flag] === "strings" ? [...Array.isArray(previous) ? previous : [], value] : value;
     }
   }
   const [minimum, maximum] = typeof positionalCount === "number" ? [positionalCount, positionalCount] : positionalCount;
@@ -282,6 +303,7 @@ var CLI_LIMITS = {
   vectorSearchText: { maximum: 8000 },
   telemetryHistory: { default: 100, maximum: 1000 },
   linkPage: { default: 100, maximum: 1000 },
+  users: { default: 20, maximum: 200 },
   inspect: {
     depth: { default: 2, maximum: 3 },
     objects: { default: 20, maximum: 100 },
@@ -317,6 +339,8 @@ Objects:
   sixb objects inspect <type> <id>    Inspect an object and its related graph in one command
   sixb objects list [options]         Browse materialized objects
   sixb objects get <type> <id>...     Exact lookup through opaque object references
+  sixb objects get-by <type> <property> <value>
+                                      The object holding a value of a unique property
   sixb objects search <text>          Search visible objects by id prefix and full text
   sixb objects search <text> --type <type>
                                       Semantic search through the type's vector profile
@@ -340,6 +364,13 @@ Actions and workflows:
 Files:
   sixb files upload|download ...
 
+Members:
+  sixb users search <text>            Find members by name or email
+  sixb users list|get ...
+
+A user parameter or property is {"type":"user","id":"<user-id>"}. Find the id with
+\`sixb users search <name>\`.
+
 Run \`sixb <group> --help\` or \`sixb <group> <command> --help\` for exact arguments.
 For query IR, run \`sixb objects query --help\` and \`sixb objects query --example list\`.`;
 var LOCAL_MAIN_HELP = SANDBOX_MAIN_HELP.replace("Sixb agent CLI", "Sixb instance CLI").replace("The CLI uses the run-scoped SIXB_API_BASE_URL. Do not configure authentication or another origin.", "The CLI uses the selected local profile and its API credentials.").replace(`  sixb doctor                         Check the sandbox and API gateway
@@ -347,7 +378,16 @@ var LOCAL_MAIN_HELP = SANDBOX_MAIN_HELP.replace("Sixb agent CLI", "Sixb instance
 `, "").replace(`
 When you do not know a type's properties or links, read its file under $SIXB_ONTOLOGY_DIR. Use
 \`sixb ontology get\` for a type that has no file there.
-`, "");
+`, "").replace(`Files:
+  sixb files upload|download ...
+`, `Files:
+  sixb files upload|download ...
+
+Models:
+  sixb models list [--kind <kind>]    Configured models of every kind, with prices
+  sixb models get <model>             One model's options and rate card
+  sixb models text|image|speech|transcribe ...   Call a model; see sixb models --help
+`);
 function renderInstanceHelp(mode) {
   return mode === "sandbox" ? SANDBOX_MAIN_HELP : LOCAL_MAIN_HELP;
 }
@@ -364,10 +404,18 @@ var SEARCH_HELP = `Usage:
 profiles.
 
 ${SEARCH_DETAILS}`;
+var GET_BY_HELP = `Usage:
+  sixb objects get-by <object-type> <property> <value> [--json]
+
+Prints the object of exactly <object-type> holding <value> for a property marked unique in its
+ontology doc, or null when no visible object holds it. Values match exactly, case included.
+The value is a string; with --json it is parsed as JSON, for an integer (42) or a user
+reference ({"type":"user","id":"usr_1"}).`;
 var OBJECTS_HELP = `Usage:
   sixb objects inspect <object-type> <primary-id> [options]
   sixb objects list [options]
   sixb objects get <object-type> <primary-id>...
+  sixb objects get-by <object-type> <property> <value> [--json]
   sixb objects search <text> [--type <object-type> [--vector-profile <name>]] [--limit <n>]
   sixb objects query --file <path|-> [--include-total|--no-total]
   sixb objects query --example <name>
@@ -434,7 +482,7 @@ Query nodes compose through input:
   limit     {"kind":"limit","input":<query>,"limit":${CLI_LIMITS.list.default}}
   page      {"kind":"page","input":<query>,"pageSize":${CLI_LIMITS.list.default},"pageToken":"from nextPageToken"}
   project   {"kind":"project","input":<query>,"properties":["name","status"]}
-  expand    {"kind":"expand","input":<query>,"expansions":[{"linkId":"link","direction":"outgoing","limit":5}]}
+  expand    {"kind":"expand","input":<query>,"expansions":[{"linkId":"link","direction":"outgoing","limit":5}],"users":["assignee"]}
   vector    {"kind":"vector","input":<start|filter>,"vector":"text","profile":"name","k":10}
   rerank    {"kind":"rerank","input":<vector>,"model":{"provider":"provider","modelId":"model"}}
 
@@ -445,11 +493,16 @@ Predicates use op, not kind:
   {"op":"in","propertyId":"status","values":["open","blocked"]}
   {"op":"exists","propertyId":"dueDate","value":true}
   {"op":"contains","propertyId":"tags","value":"urgent"}
+  {"op":"eq","propertyId":"assignee","value":{"type":"currentUser"}}  the caller, on a user reference: neq, in, contains too
 
 Every field shown is required except includeSubtypes, fields, pageToken, properties, a sort
-direction, and an expansion's limit. Sort by relevance after text or vector with
+direction, an expansion's limit, and users. Sort by relevance after text or vector with
 {"kind":"relevance"}. Wrap the outermost node in project to return only the properties you need.
 
+An expand's users, or an expansion's, lists user-reference properties: each row then carries the
+members' profiles under users (id, email, displayName, avatarUrl, status). Without access to the
+member directory, users is empty.
+
 Traversal and expansion directions are outgoing or incoming. For incoming relationships, the link
 is declared on the child/source type; add sourceObjectTypeId when needed to disambiguate it.
 
@@ -484,7 +537,8 @@ History options:
 \`actions get\` includes inputSchema, the exact JSON shape accepted by the Action. The JSON file
 contains that parameter object; use - to read standard input. \`actions request\` runs the Action
 and prints its finished run, with its status and any error. It waits at most 25 seconds: a run that
-takes longer keeps running, and the error names the run to read with \`action-runs get\`.`,
+takes longer keeps running, and the error names the run to read with \`action-runs get\`. A request
+that waits for the user's approval prints \`"status": "awaiting_approval"\` and exits with code 4.`,
   "action-runs": `Usage:
   sixb action-runs list [options]
   sixb action-runs get <run-id>
@@ -505,9 +559,48 @@ List options:
   workflows: `Usage:
   sixb workflows list
   sixb workflows get <workflow-id>
-  sixb workflows start <workflow-id> [--file <path|->]
+  sixb workflows start <workflow-id> [--file <path|->] [--run-id <id>]
+
+The JSON file contains the workflow input object. Use - to read standard input. A start that waits
+for the user's approval prints \`"status": "awaiting_approval"\` and exits with code 4.`,
+  users: `Usage:
+  sixb users list [options]
+  sixb users search <text> [options]
+  sixb users get <user-id>
+
+Options:
+  --status active|suspended|all       Defaults to active
+  --limit <1-${CLI_LIMITS.users.maximum}>                     Defaults to ${CLI_LIMITS.users.default}
+  --offset <n>                        Non-negative; defaults to 0
+
+\`users search\` matches part of a display name or email, ignoring case. Each member is
+{"id","email","displayName","avatarUrl","status"}; a user parameter takes
+{"type":"user","id":"<id>"}. Reading members requires can.view(project.users).`,
+  models: `Usage:
+  sixb models list [--kind language|image|speech|transcription]
+  sixb models get <model> [--kind <kind>]
+  sixb models text "<prompt>"|--file <path|-> [--model <tier|model>] [--instructions <text>]
+                   [--max-output-tokens <n>] [--reasoning <level>]
+  sixb models image "<prompt>" --output <path> [--model <model>] [--n <n>]
+                    [--size <size>] [--aspect-ratio <ratio>] [--quality <q>] [--style <s>]
+                    [--seed <n>] [--image <file>]...
+  sixb models speech "<text>" --output <path> [--model <model>] [--voice <voice>]
+                     [--format mp3|wav|ogg|aac|flac] [--instructions <text>]
+                     [--speed <n>] [--language <code>]
+  sixb models transcribe <file> [--model <model>]
+  sixb models calls files <call-id> [--output <path>]
+
+<model> is a model id, or provider:model-id when two providers share one; without --model, the
+kind's default answers. \`list\` shows each model's kind, default, description and price; \`get\`
+adds the sizes, voices and other options a request can use. Prices are in USD.
+
+\`text\` also takes a tier (light, standard or heavy) for --model, and reads a long prompt from
+--file: a path, or - for standard input.
 
-The JSON file contains the workflow input object. Use - to read standard input.`,
+--output is a file, numbered when a call returns several, or a directory ending in /. The
+extension follows the file's type, and the result lists the paths written. --image uploads a
+reference image; repeat it for several. \`calls files\` lists a past call's files, or downloads
+them again.`,
   "workflow-runs": `Usage:
   sixb workflow-runs list [options]
   sixb workflow-runs get <run-id>
@@ -527,9 +620,11 @@ var QUERY_EXAMPLES = {
   not: `{"kind":"limit","input":{"kind":"filter","input":{"kind":"start","objectTypeId":"Customer"},"predicate":{"op":"not","item":{"op":"eq","propertyId":"status","value":"churned"}}},"limit":${CLI_LIMITS.list.default}}`,
   in: `{"kind":"limit","input":{"kind":"filter","input":{"kind":"start","objectTypeId":"Customer"},"predicate":{"op":"in","propertyId":"status","values":["active","trial"]}},"limit":${CLI_LIMITS.list.default}}`,
   exists: `{"kind":"limit","input":{"kind":"filter","input":{"kind":"start","objectTypeId":"Customer"},"predicate":{"op":"exists","propertyId":"accountManager","value":false}},"limit":${CLI_LIMITS.list.default}}`,
+  mine: `{"kind":"limit","input":{"kind":"filter","input":{"kind":"start","objectTypeId":"Task"},"predicate":{"op":"eq","propertyId":"assignee","value":{"type":"currentUser"}}},"limit":${CLI_LIMITS.list.default}}`,
   project: `{"kind":"project","input":{"kind":"limit","input":{"kind":"start","objectTypeId":"Customer"},"limit":${CLI_LIMITS.list.default}},"properties":["name","status"]}`,
   incoming: '{"kind":"traverse","input":{"kind":"refs","refs":[{"objectTypeId":"RepositoryIssue","primaryId":"github:issue:owner/repo#297"}]},"linkId":"issue","direction":"incoming","sourceObjectTypeId":"RepositoryComment"}',
   expand: `{"kind":"expand","input":{"kind":"refs","refs":[{"objectTypeId":"RepositoryIssue","primaryId":"github:issue:owner/repo#297"}]},"expansions":[{"linkId":"issue","direction":"incoming","sourceObjectTypeId":"RepositoryComment","limit":${CLI_LIMITS.list.default}}]}`,
+  users: `{"kind":"expand","input":{"kind":"limit","input":{"kind":"start","objectTypeId":"Task"},"limit":${CLI_LIMITS.list.default}},"expansions":[],"users":["assignee"]}`,
   sort: `{"kind":"limit","input":{"kind":"sort","input":{"kind":"start","objectTypeId":"Customer"},"fields":[{"kind":"property","propertyId":"name","direction":"asc"}]},"limit":${CLI_LIMITS.list.default}}`,
   page: `{"kind":"page","input":{"kind":"start","objectTypeId":"Customer"},"pageSize":${CLI_LIMITS.list.default}}`,
   vector: `{"kind":"vector","input":{"kind":"filter","input":{"kind":"start","objectTypeId":"Product"},"predicate":{"op":"eq","propertyId":"status","value":"active"}},"vector":"waterproof trail shoes","profile":"content","k":${CLI_LIMITS.search.default}}`
@@ -567,20 +662,22 @@ function singleFileOption(args, command) {
   return options["--file"];
 }
 async function readJson(source) {
-  let text;
-  try {
-    text = source === "-" ? await readStdin() : await readFile2(source, "utf8");
-  } catch (error) {
-    if (isFileError(error, "ENOENT"))
-      fail(`JSON file '${source}' does not exist.`);
-    throw error;
-  }
+  const text = await readText(source, "JSON file");
   try {
     return JSON.parse(text);
   } catch {
     fail(source === "-" ? "Standard input is not valid JSON." : `JSON file '${source}' is not valid JSON.`, "invalid_json");
   }
 }
+async function readText(source, noun) {
+  try {
+    return source === "-" ? await readStdin() : await readFile2(source, "utf8");
+  } catch (error) {
+    if (isFileError(error, "ENOENT"))
+      fail(`${noun} '${source}' does not exist.`);
+    throw error;
+  }
+}
 function asRecord2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value) ? value : {};
 }
@@ -642,7 +739,7 @@ async function actions(api, args, requestWaitMs = ACTION_REQUEST_WAIT_MS) {
     const requestedRunId = runId ?? `act_${randomUUID2()}`;
     const waiting = AbortSignal.timeout(requestWaitMs);
     try {
-      return writeJson(await api.post(`/api/actions/${encodeURIComponent(actionId)}`, {
+      return writeRequestResult(await api.post(`/api/actions/${encodeURIComponent(actionId)}`, {
         params,
         ...subjectType && subjectId ? { subject: { kind: "object", objectTypeId: subjectType, primaryId: subjectId } } : {},
         runId: requestedRunId
@@ -703,6 +800,340 @@ async function files(api, args) {
   fail(`Unknown files command '${sub}'.`);
 }
 
+// src/commands/models.ts
+import { access as access2, mkdir, stat } from "fs/promises";
+import { dirname as dirname2, extname, join as join2, parse } from "path";
+var MODEL_KINDS = ["language", "image", "speech", "transcription"];
+async function models(api, args) {
+  const [sub, ...rest] = args;
+  if (!sub || isHelp(sub) || requestsHelp(rest))
+    return writeText(GROUP_HELP.models);
+  if (sub === "list") {
+    const { options } = parseCommandArgs(rest, { "--kind": "string" }, "models list", 0);
+    const kind = options["--kind"] === undefined ? undefined : modelKind(options["--kind"]);
+    const entries = catalogEntries(await api.get("/api/models"));
+    return writeJson(entries.filter((entry) => kind === undefined || entry.kind === kind).map(({ kind, entry }) => ({
+      kind,
+      model: entry.modelId,
+      provider: entry.provider,
+      ...entry.tier ? { tier: entry.tier } : {},
+      ...entry.isDefault ? { default: true } : {},
+      ...entry.description ? { description: entry.description } : {},
+      price: describePrice(entry.rateCard)
+    })));
+  }
+  if (sub === "get") {
+    const { positionals, options } = parseCommandArgs(rest, { "--kind": "string" }, "models get", 1);
+    const kind = options["--kind"] === undefined ? undefined : modelKind(options["--kind"]);
+    const entries = catalogEntries(await api.get("/api/models"));
+    const { kind: found, entry } = findModel(entries, positionals[0] ?? "", kind);
+    const { provider, modelId, isDefault, rateCard, ...details } = entry;
+    return writeJson({
+      kind: found,
+      model: modelId,
+      provider,
+      default: isDefault,
+      ...details,
+      price: describePrice(rateCard),
+      ...rateCard ? { rateCard } : {}
+    });
+  }
+  if (sub === "text")
+    return generateText(api, rest);
+  if (sub === "image")
+    return generateImages(api, rest);
+  if (sub === "speech")
+    return generateSpeech(api, rest);
+  if (sub === "transcribe")
+    return transcribe(api, rest);
+  if (sub === "calls")
+    return calls(api, rest);
+  fail(`Unknown models command '${sub}'.`);
+}
+var SPEECH_FORMATS = {
+  mp3: "audio/mpeg",
+  wav: "audio/wav",
+  ogg: "audio/ogg",
+  aac: "audio/aac",
+  flac: "audio/flac"
+};
+var SPEECH_FORMAT_NAMES = Object.keys(SPEECH_FORMATS);
+var MEDIA_TYPES = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".webp": "image/webp",
+  ".gif": "image/gif",
+  ".mp3": "audio/mpeg",
+  ".wav": "audio/wav",
+  ".ogg": "audio/ogg",
+  ".aac": "audio/aac",
+  ".flac": "audio/flac",
+  ".opus": "audio/opus",
+  ".m4a": "audio/mp4",
+  ".webm": "audio/webm"
+};
+var EXTENSIONS = Object.fromEntries(Object.entries(MEDIA_TYPES).filter(([extension]) => extension !== ".jpeg").map(([extension, mediaType]) => [mediaType, extension]));
+async function generateText(api, args) {
+  const { positionals, options } = parseCommandArgs(args, {
+    "--model": "string",
+    "--instructions": "string",
+    "--max-output-tokens": "string",
+    "--reasoning": "string",
+    "--file": "string"
+  }, "models text", [0, 1]);
+  const prompt = await readPrompt(positionals[0], options["--file"]);
+  const maxOutputTokens = options["--max-output-tokens"];
+  const result = await api.post("/api/models/language/generations", {
+    ...await languageModelRef(api, options["--model"]),
+    prompt,
+    ...options["--instructions"] === undefined ? {} : { instructions: options["--instructions"] },
+    ...maxOutputTokens === undefined ? {} : { maxOutputTokens: integerInRange("--max-output-tokens", maxOutputTokens, 1, 1e6) },
+    ...options["--reasoning"] === undefined ? {} : { reasoning: options["--reasoning"] }
+  });
+  writeJson({
+    callId: result.callId,
+    model: result.model.modelId,
+    text: result.text,
+    finishReason: result.finishReason,
+    cost: describeCost(result.cost)
+  });
+}
+async function generateImages(api, args) {
+  const { positionals, options } = parseCommandArgs(args, {
+    "--output": "string",
+    "--model": "string",
+    "--n": "string",
+    "--size": "string",
+    "--aspect-ratio": "string",
+    "--quality": "string",
+    "--style": "string",
+    "--seed": "string",
+    "--image": "strings"
+  }, "models image", 1);
+  const output = requireOutput(options["--output"], "models image");
+  const seed = options["--seed"];
+  if (seed !== undefined && !/^-?[0-9]+$/.test(seed))
+    fail("--seed must be an integer.");
+  const model = await modelRef(api, options["--model"], "image");
+  const images = [];
+  for (const path of options["--image"] ?? [])
+    images.push(await uploadInput(api, path, "image"));
+  const result = await api.post("/api/models/image/generations", {
+    ...model,
+    prompt: positionals[0],
+    ...options["--n"] === undefined ? {} : { n: integerInRange("--n", options["--n"], 1, 100) },
+    ...optional("size", options["--size"]),
+    ...optional("aspectRatio", options["--aspect-ratio"]),
+    ...optional("quality", options["--quality"]),
+    ...optional("style", options["--style"]),
+    ...seed === undefined ? {} : { seed: Number(seed) },
+    ...images.length > 0 ? { images } : {}
+  });
+  writeJson(await savedResult(api, result, output));
+}
+async function generateSpeech(api, args) {
+  const { positionals, options } = parseCommandArgs(args, {
+    "--output": "string",
+    "--model": "string",
+    "--voice": "string",
+    "--format": "string",
+    "--instructions": "string",
+    "--speed": "string",
+    "--language": "string"
+  }, "models speech", 1);
+  const output = requireOutput(options["--output"], "models speech");
+  const format = options["--format"];
+  const speed = options["--speed"];
+  if (speed !== undefined && !(Number(speed) > 0))
+    fail("--speed must be a positive number.");
+  const result = await api.post("/api/models/audio/speech", {
+    ...await modelRef(api, options["--model"], "speech"),
+    text: positionals[0],
+    ...optional("voice", options["--voice"]),
+    ...format === undefined ? {} : { mediaType: SPEECH_FORMATS[enumValue("--format", format, SPEECH_FORMAT_NAMES)] },
+    ...optional("instructions", options["--instructions"]),
+    ...speed === undefined ? {} : { speed: Number(speed) },
+    ...optional("language", options["--language"])
+  });
+  writeJson(await savedResult(api, result, output));
+}
+async function transcribe(api, args) {
+  const { positionals, options } = parseCommandArgs(args, { "--model": "string" }, "models transcribe", 1);
+  const model = await modelRef(api, options["--model"], "transcription");
+  const audio = await uploadInput(api, positionals[0] ?? "", "audio");
+  const result = await api.post("/api/models/audio/transcriptions", {
+    ...model,
+    audio
+  });
+  writeJson({
+    callId: result.callId,
+    model: result.model.modelId,
+    text: result.text,
+    cost: describeCost(result.cost)
+  });
+}
+async function calls(api, args) {
+  const [sub, ...rest] = args;
+  if (sub !== "files")
+    fail(`Unknown models calls command '${sub ?? ""}'. Use 'models calls files'.`);
+  const { positionals, options } = parseCommandArgs(rest, { "--output": "string" }, "models calls files", 1);
+  const callId = positionals[0] ?? "";
+  const call = await api.get(`/api/ai/model-calls/${encodeURIComponent(callId)}/files`);
+  const output = options["--output"];
+  if (output === undefined)
+    return writeJson(call);
+  writeJson({ callId: call.callId, files: await saveFiles(api, call.callId, call.files, output) });
+}
+async function modelRef(api, reference, kind) {
+  if (reference === undefined)
+    return {};
+  const { entry } = findModel(catalogEntries(await api.get("/api/models")), reference, kind);
+  return { model: { provider: entry.provider, modelId: entry.modelId } };
+}
+var LANGUAGE_TIERS = ["light", "standard", "heavy"];
+async function languageModelRef(api, reference) {
+  const tier = LANGUAGE_TIERS.find((candidate) => candidate === reference);
+  if (tier !== undefined)
+    return { model: tier };
+  return modelRef(api, reference, "language");
+}
+async function readPrompt(argument, source) {
+  if (argument !== undefined && source !== undefined) {
+    fail("models text takes its prompt as an argument or from --file, not both.");
+  }
+  const prompt = source === undefined ? argument : await readText(source, "Prompt file");
+  if (prompt === undefined) {
+    fail('models text requires a prompt: "<prompt>", or --file <path|-> to read it.');
+  }
+  if (!prompt.trim())
+    fail("The prompt is empty.");
+  return prompt;
+}
+function requireOutput(output, command) {
+  if (!output)
+    fail(`${command} requires --output <path>: a file, or a directory ending in /.`);
+  return output;
+}
+function optional(field, value) {
+  return value === undefined ? {} : { [field]: value };
+}
+async function uploadInput(api, path, kind) {
+  try {
+    await access2(path);
+  } catch {
+    fail(`Input file '${path}' does not exist.`);
+  }
+  const mediaType = MEDIA_TYPES[extname(path).toLowerCase()];
+  if (!mediaType?.startsWith(`${kind}/`)) {
+    const accepted = Object.entries(MEDIA_TYPES).filter(([, type]) => type.startsWith(`${kind}/`)).map(([extension]) => extension);
+    fail(`'${path}' is not an ${kind} file. Use ${accepted.join(", ")}.`);
+  }
+  return api.upload("/api/files", path, undefined, mediaType);
+}
+async function savedResult(api, result, output) {
+  return {
+    callId: result.callId,
+    model: result.model.modelId,
+    files: await saveFiles(api, result.callId, result.files ?? [], output),
+    ...result.warnings?.length ? { warnings: result.warnings } : {},
+    cost: describeCost(result.cost)
+  };
+}
+async function saveFiles(api, callId, files, output) {
+  const directory = output.endsWith("/") || (await stat(output).catch(() => null))?.isDirectory();
+  const paths = files.map((file, index) => {
+    const number = files.length > 1 ? `-${index + 1}` : "";
+    const extension = (file.mediaType && EXTENSIONS[file.mediaType]) ?? "";
+    if (directory)
+      return join2(output, `${callId}${number}${extension || ".bin"}`);
+    const { dir, name, ext } = parse(output);
+    return join2(dir, `${name}${number}${extension || ext}`);
+  });
+  for (const [index, path] of paths.entries()) {
+    await mkdir(dirname2(path), { recursive: true });
+    await api.download(`/api/ai/model-calls/${encodeURIComponent(callId)}/files/content`, path, {
+      path: `/files/${index}`
+    });
+  }
+  return paths;
+}
+function describeCost(cost) {
+  if (!cost.money)
+    return "unknown";
+  const nanos = BigInt(cost.money.amountNanos);
+  const whole = nanos / 1000000000n;
+  const fraction = (nanos % 1000000000n).toString().padStart(9, "0").replace(/0+$/, "");
+  return `$${whole}${fraction ? `.${fraction}` : ""}`;
+}
+function modelKind(value) {
+  const kind = MODEL_KINDS.find((candidate) => candidate === value);
+  if (!kind)
+    fail(`Unknown model kind '${value}'. Use one of: ${MODEL_KINDS.join(", ")}.`);
+  return kind;
+}
+function catalogEntries(catalog) {
+  return [
+    ...catalog.language.map((entry) => ({ kind: "language", entry })),
+    ...catalog.image.map((entry) => ({ kind: "image", entry })),
+    ...catalog.audio.speech.map((entry) => ({ kind: "speech", entry })),
+    ...catalog.audio.transcription.map((entry) => ({ kind: "transcription", entry }))
+  ];
+}
+function findModel(entries, reference, kind) {
+  const ofKind = entries.filter((candidate) => kind === undefined || candidate.kind === kind);
+  let matches = ofKind.filter((candidate) => candidate.entry.modelId === reference);
+  const separator = reference.indexOf(":");
+  if (matches.length === 0 && separator > 0) {
+    const provider = reference.slice(0, separator);
+    const modelId = reference.slice(separator + 1);
+    matches = ofKind.filter((candidate) => candidate.entry.provider === provider && candidate.entry.modelId === modelId);
+  }
+  const [match] = matches;
+  if (!match) {
+    fail(`No ${kind === undefined ? "" : `${kind} `}model '${reference}' is configured. Run 'sixb models list'.`);
+  }
+  if (matches.length > 1) {
+    const kinds = new Set(matches.map((candidate) => candidate.kind));
+    fail(kinds.size > 1 ? `'${reference}' is configured as ${[...kinds].join(" and ")}. Add --kind <kind>.` : `'${reference}' is configured by ${matches.map((candidate) => candidate.entry.provider).join(" and ")}. Use provider:${reference}.`);
+  }
+  return match;
+}
+function describePrice(card) {
+  if (!card)
+    return "price unknown";
+  const parts = [
+    variantPrice(card.images, "per image", "at"),
+    variantPrice(card.characters, "per 1M characters", "for"),
+    variantPrice(card.audioInputSeconds, "per second of audio", "for"),
+    card.input !== undefined && card.output !== undefined ? `${dollars(tokenPrice(card.input))} input \xB7 ${dollars(tokenPrice(card.output))} output per 1M tokens` : undefined,
+    card.audioOutput === undefined ? undefined : `${dollars(tokenPrice(card.audioOutput))} per 1M audio tokens`
+  ].filter((part) => part !== undefined);
+  return parts.length === 0 ? "price unknown" : parts.join(" \xB7 ");
+}
+function variantPrice(price, unit, joiner) {
+  if (price === undefined)
+    return;
+  if (typeof price === "string")
+    return `${dollars(price)} ${unit}`;
+  const only = price.default;
+  if (only !== undefined && price.variants.every((variant) => variant.price === only)) {
+    return `${dollars(only)} ${unit}`;
+  }
+  const variants = price.variants.map(({ price: amount, ...dimensions }) => {
+    const label = Object.values(dimensions).join(" ");
+    return `${dollars(amount)} ${joiner} ${label}`;
+  });
+  const otherwise = price.default === undefined ? [] : [`otherwise ${dollars(price.default)}`];
+  return `${unit}: ${[...variants, ...otherwise].join(", ")}`;
+}
+function tokenPrice(price) {
+  return typeof price === "string" ? price : price.default;
+}
+function dollars(amount) {
+  return `$${amount}`;
+}
+
 // src/graph.ts
 async function inspectGraph(api, objectTypeId, primaryId, options) {
   if (options.depth === 0)
@@ -968,6 +1399,8 @@ async function objects(api, args) {
       return objectsList(api, rest);
     case "get":
       return objectsGet(api, rest);
+    case "get-by":
+      return objectsGetBy(api, rest);
     case "search":
       return objectsSearch(api, rest);
     case "query":
@@ -1058,6 +1491,31 @@ async function objectsGet(api, args) {
     includeTotal: false
   }));
 }
+async function objectsGetBy(api, args) {
+  if (requestsHelp(args))
+    return writeText(GET_BY_HELP);
+  const { positionals, options } = parseCommandArgs(args, { "--json": "boolean" }, "objects get-by", 3);
+  const [objectTypeId = "", propertyId = "", text = ""] = positionals;
+  const value = options["--json"] ? parseJsonValue(text) : text;
+  const path = `/api/objects/${encodeURIComponent(objectTypeId)}/by/${encodeURIComponent(propertyId)}`;
+  try {
+    writeJson(await api.post(path, { value }));
+  } catch (error) {
+    if (!isObjectNotFound(error))
+      throw error;
+    writeJson(null);
+  }
+}
+function parseJsonValue(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    fail(`--json needs the value as JSON, such as 42 or '{"type":"user","id":"usr_1"}'.`);
+  }
+}
+function isObjectNotFound(error) {
+  return error instanceof CliError && error.body.status === 404 && error.body.code === "object.not_found";
+}
 async function objectsSearch(api, args) {
   if (requestsHelp(args))
     return writeText(SEARCH_HELP);
@@ -1379,7 +1837,45 @@ function normalizeTelemetryQueryInput(input) {
   return body;
 }
 
+// src/commands/users.ts
+var USER_STATUSES = ["active", "suspended", "all"];
+var LIST_FLAGS = {
+  "--status": "string",
+  "--limit": "string",
+  "--offset": "string"
+};
+async function users(api, args) {
+  const [sub, ...rest] = args;
+  if (!sub || isHelp(sub) || requestsHelp(rest))
+    return writeText(GROUP_HELP.users);
+  if (sub === "get") {
+    const { positionals } = parseCommandArgs(rest, {}, "users get", 1);
+    return writeJson(await api.get(`/api/users/${encodeURIComponent(positionals[0] ?? "")}`));
+  }
+  if (sub === "list") {
+    const { options } = parseCommandArgs(rest, LIST_FLAGS, "users list");
+    return writeJson(await api.get("/api/users", listQuery(options)));
+  }
+  if (sub === "search") {
+    const { positionals, options } = parseCommandArgs(rest, LIST_FLAGS, "users search", 1);
+    const search = positionals[0]?.trim();
+    if (!search)
+      fail("users search requires the text to find in a name or email.");
+    return writeJson(await api.get("/api/users", { ...listQuery(options), search }));
+  }
+  fail(`Unknown users command '${sub}'.`);
+}
+function listQuery(options) {
+  const limit = integerInRange("--limit", options["--limit"] ?? String(CLI_LIMITS.users.default), 1, CLI_LIMITS.users.maximum);
+  return {
+    status: enumValue("--status", options["--status"] ?? "active", USER_STATUSES),
+    limit: String(limit),
+    ...options["--offset"] === undefined ? {} : { offset: String(nonNegativeInteger("--offset", options["--offset"])) }
+  };
+}
+
 // src/commands/workflows.ts
+import { randomUUID as randomUUID3 } from "crypto";
 async function workflows(api, args) {
   const [sub, ...rest] = args;
   if (!sub || isHelp(sub) || requestsHelp(rest))
@@ -1398,12 +1894,16 @@ async function workflows(api, args) {
     const {
       positionals: [workflowId],
       options
-    } = parseCommandArgs(rest, { "--file": "string" }, "workflows start", 1);
+    } = parseCommandArgs(rest, { "--file": "string", "--run-id": "string" }, "workflows start", 1);
     const input = options["--file"] ? await readJson(options["--file"]) : {};
     if (Array.isArray(input) || typeof input !== "object" || input === null) {
       fail("Workflow input must be a JSON object.");
     }
-    return writeJson(await api.post(`/api/workflows/${encodeURIComponent(workflowId ?? "")}/runs`, { input }));
+    const runId = options["--run-id"] ?? `run_${randomUUID3()}`;
+    return writeRequestResult(await api.post(`/api/workflows/${encodeURIComponent(workflowId ?? "")}/runs`, {
+      input,
+      runId
+    }));
   }
   fail(`Unknown workflows command '${sub}'.`);
 }
@@ -1418,7 +1918,9 @@ var INSTANCE_COMMANDS = [
   "action-runs",
   "files",
   "workflows",
-  "workflow-runs"
+  "workflow-runs",
+  "users",
+  "models"
 ];
 function isInstanceCommand(command) {
   return INSTANCE_COMMANDS.includes(command);
@@ -1443,6 +1945,10 @@ async function dispatch(api, command, args) {
       return workflows(api, args);
     case "workflow-runs":
       return runs(api, "workflow", args);
+    case "users":
+      return users(api, args);
+    case "models":
+      return models(api, args);
     default:
       fail(`Unknown command '${command}'. Run 'sixb --help'.`);
   }
@@ -1482,4 +1988,4 @@ export {
   writeText
 };
 
-//# debugId=D8A3DF8338E3251F64756E2164756E21
+//# debugId=7F5CD0F40A1B96CA64756E2164756E21