@clickraft/cli 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,8 +1,8 @@
-## [0.2.0](https://github.com/clickraft/cli/compare/v0.1.8...v0.2.0) (2026-05-24)
+## [0.3.0](https://github.com/clickraft/cli/compare/v0.2.0...v0.3.0) (2026-05-24)
 
 ### Features
 
-* **commands:** add balance and brand-model list commands ([19e27a2](https://github.com/clickraft/cli/commit/19e27a2c5cebe3f19954a80c64139f9e5d6bbd22))
+* **commands:** add template list, get, and find commands ([b2f5c5c](https://github.com/clickraft/cli/commit/b2f5c5c2e501f8ea5c6586476d121b97ce97f4ba))
 
 # Changelog
 

package/README.md

@@ -19,6 +19,9 @@ clickraft login
 clickraft generate create --prompt "a serene mountain landscape at dawn"
 clickraft balance
 clickraft brand-model list
+clickraft template list
+clickraft template get <template-id>
+clickraft template find "coffee brand"
 ```
 
 Full documentation: [docs.clickraft.ai/cli](https://docs.clickraft.ai/cli) _(coming soon)_

package/dist/cli.js

@@ -721,6 +721,10 @@ function buildUrl(baseUrl, path, query) {
   if (query) {
     for (const [key, value] of Object.entries(query)) {
       if (value === void 0) continue;
+      if (Array.isArray(value)) {
+        for (const item of value) url.searchParams.append(key, item);
+        continue;
+      }
       url.searchParams.append(key, String(value));
     }
   }
@@ -2305,21 +2309,112 @@ function inspectTelemetry(options = {}) {
   };
 }
 
-// src/commands/tokens/list.ts
+// src/commands/template/internal.ts
+async function buildTemplateClient(opts) {
+  const cfg = await loadConfig({
+    flagProfile: opts.profile,
+    flagApiBaseUrl: opts.apiBaseUrl,
+    flagToken: opts.token
+  });
+  return new ApiClient({
+    apiBaseUrl: cfg.apiBaseUrl,
+    accessToken: cfg.accessToken,
+    signal: opts.signal,
+    cloudflareAccess: cfg.cloudflareAccess
+  });
+}
+
+// src/schemas/templates.ts
 import { z as z8 } from "zod";
-var TokenRowSchema = z8.object({
+var DeclaredParamSchema = z8.object({
+  name: z8.string(),
+  type: z8.string(),
+  required: z8.boolean(),
+  defaultValue: z8.string().nullable().optional(),
+  enumValues: z8.array(z8.string()).nullable().optional(),
+  description: z8.string().nullable().optional()
+}).strict();
+var TemplateSummarySchema = z8.object({
   id: z8.string().uuid(),
-  organizationId: z8.string().uuid(),
-  userId: z8.string().uuid(),
-  clientId: z8.string().nullable(),
-  tokenPrefix: z8.string(),
-  name: z8.string().nullable(),
-  scopes: z8.array(z8.string()),
-  lastUsedAt: z8.string().nullable(),
-  expiresAt: z8.string(),
+  source: z8.enum(["own", "system"]),
+  name: z8.string(),
+  description: z8.string().nullable(),
+  category: z8.string().nullable(),
+  thumbnailUrl: z8.string().nullable(),
+  tags: z8.array(z8.string()),
   createdAt: z8.string()
 }).strict();
-var TokensListResponseSchema = z8.array(TokenRowSchema);
+var TemplateDetailSchema = TemplateSummarySchema.extend({
+  declaredParams: z8.array(DeclaredParamSchema),
+  timesUsed: z8.number()
+}).strict();
+var TemplatesListResponseSchema = z8.object({
+  templates: z8.array(TemplateSummarySchema),
+  cursor: z8.string().nullable(),
+  hasMore: z8.boolean()
+}).strict();
+
+// src/commands/template/list.ts
+async function listTemplates(opts) {
+  const client = opts.client ?? await buildTemplateClient(opts);
+  const data = await client.request({
+    method: "GET",
+    path: "/templates",
+    query: {
+      q: opts.q,
+      tags: opts.tags,
+      scope: opts.scope,
+      cursor: opts.cursor,
+      limit: opts.limit
+    },
+    responseSchema: TemplatesListResponseSchema,
+    signal: opts.signal
+  });
+  return data;
+}
+
+// src/commands/template/find.ts
+async function findTemplates(opts) {
+  return listTemplates({
+    q: opts.query,
+    tags: opts.tags,
+    scope: opts.scope,
+    limit: opts.limit,
+    cursor: opts.cursor,
+    profile: opts.profile,
+    apiBaseUrl: opts.apiBaseUrl,
+    token: opts.token,
+    signal: opts.signal,
+    client: opts.client
+  });
+}
+
+// src/commands/template/get.ts
+async function getTemplate(opts) {
+  const client = opts.client ?? await buildTemplateClient(opts);
+  return client.request({
+    method: "GET",
+    path: `/templates/${encodeURIComponent(opts.id)}`,
+    responseSchema: TemplateDetailSchema,
+    signal: opts.signal
+  });
+}
+
+// src/commands/tokens/list.ts
+import { z as z9 } from "zod";
+var TokenRowSchema = z9.object({
+  id: z9.string().uuid(),
+  organizationId: z9.string().uuid(),
+  userId: z9.string().uuid(),
+  clientId: z9.string().nullable(),
+  tokenPrefix: z9.string(),
+  name: z9.string().nullable(),
+  scopes: z9.array(z9.string()),
+  lastUsedAt: z9.string().nullable(),
+  expiresAt: z9.string(),
+  createdAt: z9.string()
+}).strict();
+var TokensListResponseSchema = z9.array(TokenRowSchema);
 async function listTokens(options) {
   const config = await loadConfig({
     flagProfile: options.profile,
@@ -2717,6 +2812,61 @@ function renderBrandModelsList(models, out) {
   out.write(padRow(headers) + "\n");
   for (const cells of data) out.write(padRow(cells) + "\n");
 }
+function renderTemplatesList(result, out) {
+  const { templates } = result;
+  if (templates.length === 0) {
+    out.write("No templates.\n");
+    return;
+  }
+  const MAX_TAGS = 3;
+  const headers = ["SOURCE", "NAME", "CATEGORY", "TAGS", "CREATED"];
+  const data = templates.map((t) => {
+    const shown = t.tags.slice(0, MAX_TAGS).join(", ");
+    const extra = t.tags.length > MAX_TAGS ? ` +${t.tags.length - MAX_TAGS} more` : "";
+    return [
+      t.source,
+      t.name,
+      t.category ?? "\u2014",
+      t.tags.length > 0 ? shown + extra : "\u2014",
+      t.createdAt.slice(0, 10)
+    ];
+  });
+  const widths = headers.map(
+    (header, i) => Math.max(header.length, ...data.map((cells) => cells[i].length))
+  );
+  const padRow = (cells) => cells.map((cell, i) => cell.padEnd(widths[i])).join("  ").trimEnd();
+  out.write(padRow(headers) + "\n");
+  for (const cells of data) out.write(padRow(cells) + "\n");
+  if (result.hasMore) {
+    out.write("\nMore results available. Use --cursor to fetch the next page.\n");
+  }
+}
+function renderTemplateDetail(detail, out) {
+  const pad = 17;
+  const lines = [
+    detail.name,
+    `${"ID:".padEnd(pad)}${detail.id}`,
+    `${"Source:".padEnd(pad)}${detail.source}`,
+    `${"Category:".padEnd(pad)}${detail.category ?? "\u2014"}`,
+    `${"Tags:".padEnd(pad)}${detail.tags.length > 0 ? detail.tags.join(", ") : "\u2014"}`,
+    `${"Created:".padEnd(pad)}${detail.createdAt.slice(0, 10)}`,
+    `${"Times used:".padEnd(pad)}${detail.timesUsed}`
+  ];
+  if (detail.description) {
+    lines.push("", detail.description);
+  }
+  lines.push("", "Declared parameters:");
+  if (detail.declaredParams.length === 0) {
+    lines.push("  (none)");
+  } else {
+    for (const p of detail.declaredParams) {
+      const req = p.required ? "required" : "optional";
+      const desc = p.description ? `: ${p.description}` : "";
+      lines.push(`  - ${p.name} (${p.type}, ${req})${desc}`);
+    }
+  }
+  out.write(lines.join("\n") + "\n");
+}
 function formatExpiresAt(iso) {
   const ms = Date.parse(iso);
   if (Number.isNaN(ms)) return iso;
@@ -2944,6 +3094,9 @@ function renderRootHelp(version) {
     "  balance                 Show credit balance and rate limits",
     "  brand-model list        List available brand models",
     "  telemetry inspect       Show current telemetry state and payload shape",
+    "  template list            List available templates",
+    "  template get             Fetch a template by ID",
+    "  template find            Search templates by keyword",
     "  generate create         Submit a generation job and wait for completion",
     "  generate wait           Wait for an existing job to reach a terminal state",
     "  generate get            Fetch the current state of a job",
@@ -3027,6 +3180,62 @@ function renderCommandHelp(command) {
         "  --json             Emit JSON envelope instead of human output",
         ""
       ].join("\n");
+    case "template":
+      return [
+        "Usage: clickraft template <subcommand> [options]",
+        "",
+        "Subcommands:",
+        "  list   List available templates",
+        "  get    Fetch a template by ID",
+        "  find   Search templates by keyword",
+        ""
+      ].join("\n");
+    case "template list":
+      return [
+        "Usage: clickraft template list [options]",
+        "",
+        "Options:",
+        "  --scope <scope>       Filter by scope: own, system, or all (default: all)",
+        "  --q <query>           Free-text search query",
+        "  --tags <tag>          Filter by tag (repeatable)",
+        "  --cursor <token>      Pagination cursor from a previous response",
+        "  --limit <n>           Max results per page (1-50, default: 20)",
+        "  --profile <name>",
+        "  --api-base-url <url>",
+        "  --token <token>",
+        "  --json",
+        ""
+      ].join("\n");
+    case "template get":
+      return [
+        "Usage: clickraft template get <id> [options]",
+        "",
+        "Fetches a single template by its ID, including declared parameters.",
+        "",
+        "Options:",
+        "  --profile <name>",
+        "  --api-base-url <url>",
+        "  --token <token>",
+        "  --json",
+        ""
+      ].join("\n");
+    case "template find":
+      return [
+        "Usage: clickraft template find <query> [options]",
+        "",
+        "Searches templates by keyword. Shorthand for `template list --q <query>`.",
+        "",
+        "Options:",
+        "  --tags <tag>          Filter by tag (repeatable)",
+        "  --scope <scope>       Filter by scope: own, system, or all (default: all)",
+        "  --limit <n>           Max results per page (1-50, default: 20)",
+        "  --cursor <token>      Pagination cursor from a previous response",
+        "  --profile <name>",
+        "  --api-base-url <url>",
+        "  --token <token>",
+        "  --json",
+        ""
+      ].join("\n");
     case "generate":
       return [
         "Usage: clickraft generate <subcommand> [options]",
@@ -3148,6 +3357,14 @@ function matchNewCommand(argv) {
     if (sub === void 0 || sub.startsWith("-")) return { kind: "sub-help", verb: "jobs" };
     return { kind: "unknown-sub", verb: "jobs", sub };
   }
+  if (verb === "template") {
+    const sub = argv[1];
+    if (sub === "list") return { kind: "cmd", path: "template.list", verbTokenCount: 2 };
+    if (sub === "get") return { kind: "cmd", path: "template.get", verbTokenCount: 2 };
+    if (sub === "find") return { kind: "cmd", path: "template.find", verbTokenCount: 2 };
+    if (sub === void 0 || sub.startsWith("-")) return { kind: "sub-help", verb: "template" };
+    return { kind: "unknown-sub", verb: "template", sub };
+  }
   return null;
 }
 async function runNewCommand(newCmd, options, stdout, stderr) {
@@ -3198,6 +3415,12 @@ async function runNewCommand(newCmd, options, stdout, stderr) {
         return await runJobsWait(argvAfterVerb, ctx, rc);
       case "upload":
         return await runUploadCmd(argvAfterVerb, ctx, rc);
+      case "template.list":
+        return await runTemplateList(argvAfterVerb, ctx, rc);
+      case "template.get":
+        return await runTemplateGet(argvAfterVerb, ctx, rc);
+      case "template.find":
+        return await runTemplateFind(argvAfterVerb, ctx, rc);
     }
   } catch (err) {
     if (isAbortedError(err, options.signal)) {
@@ -3392,6 +3615,87 @@ function exitCodeForResult(result) {
   }
   return 0;
 }
+async function runTemplateList(argv, ctx, rc) {
+  const parsed = parseArgs(argv, {
+    string: [...COMMON_RICH_STRING_FLAGS, "scope", "q", "cursor", "limit"],
+    boolean: [...COMMON_RICH_BOOL_FLAGS],
+    array: ["tags"]
+  });
+  const result = await listTemplates({
+    q: parsed.string.q,
+    tags: parsed.array.tags,
+    scope: parsed.string.scope,
+    cursor: parsed.string.cursor,
+    limit: optionalInt(parsed.string.limit, "limit"),
+    profile: parsed.string.profile,
+    apiBaseUrl: parsed.string["api-base-url"],
+    token: parsed.string.token,
+    signal: rc.signal
+  });
+  ctx.nextCursor = result.cursor ?? void 0;
+  emitTemplateList(result, ctx, rc);
+  return 0;
+}
+async function runTemplateGet(argv, ctx, rc) {
+  const parsed = parseArgs(argv, {
+    string: [...COMMON_RICH_STRING_FLAGS],
+    boolean: [...COMMON_RICH_BOOL_FLAGS]
+  });
+  const id = parsed.positional[0];
+  if (!id) throw new ArgError("Missing required <id> argument.");
+  const detail = await getTemplate({
+    id,
+    profile: parsed.string.profile,
+    apiBaseUrl: parsed.string["api-base-url"],
+    token: parsed.string.token,
+    signal: rc.signal
+  });
+  emitTemplateDetail(detail, ctx, rc);
+  return 0;
+}
+async function runTemplateFind(argv, ctx, rc) {
+  const parsed = parseArgs(argv, {
+    string: [...COMMON_RICH_STRING_FLAGS, "scope", "cursor", "limit"],
+    boolean: [...COMMON_RICH_BOOL_FLAGS],
+    array: ["tags"]
+  });
+  const query = parsed.positional[0];
+  if (!query) throw new ArgError("Missing required <query> argument.");
+  const result = await findTemplates({
+    query,
+    tags: parsed.array.tags,
+    scope: parsed.string.scope,
+    cursor: parsed.string.cursor,
+    limit: optionalInt(parsed.string.limit, "limit"),
+    profile: parsed.string.profile,
+    apiBaseUrl: parsed.string["api-base-url"],
+    token: parsed.string.token,
+    signal: rc.signal
+  });
+  ctx.nextCursor = result.cursor ?? void 0;
+  emitTemplateList(result, ctx, rc);
+  return 0;
+}
+function emitTemplateList(result, ctx, rc) {
+  if (rc.signal?.aborted) {
+    throw new AuthError("AUTH_FLOW_CANCELLED", "Cancelled.");
+  }
+  if (rc.jsonMode) {
+    rc.stdout.write(JSON.stringify(wrapSuccess(result, ctx)) + "\n");
+    return;
+  }
+  renderTemplatesList(result, rc.stdout);
+}
+function emitTemplateDetail(detail, ctx, rc) {
+  if (rc.signal?.aborted) {
+    throw new AuthError("AUTH_FLOW_CANCELLED", "Cancelled.");
+  }
+  if (rc.jsonMode) {
+    rc.stdout.write(JSON.stringify(wrapSuccess(detail, ctx)) + "\n");
+    return;
+  }
+  renderTemplateDetail(detail, rc.stdout);
+}
 
 // src/index.ts
 var __filename2 = fileURLToPath(import.meta.url);