@spira-lab/cli 0.0.4 → 0.0.6

package/README.md

@@ -14,8 +14,14 @@ npm install -g @spira-lab/cli
 spira --help
 spira auth login
 spira ai models list
+spira ai models list --media-type audio
+spira ai jobs create --model-id nano-banana-2 --inputs-json '{"prompt":"A product photo"}' --wait
+spira ai jobs create --model-id elevenlabs-music-generation --inputs-json '{"prompt":"A short ambient cue","duration":"10"}' --wait
+spira workflows node-catalog --json
 spira workflows create --name "Product launch workflow"
 spira workflows update <workflowId> --workflow-definition-json '{"nodes":[],"edges":[]}'
 ```
 
 Use `spira --json` when you need machine-readable output.
+
+`ai jobs create --wait` prints the job ID and status changes to stderr while it waits. Its final stdout is a compact result containing the job ID, model, status, result type, and result URLs. Use `spira --json ai jobs status <jobId>` when you need the full job and provider execution details.

package/dist/index.cjs

@@ -18049,6 +18049,7 @@ var cliResultTypeSchema = external_exports.enum([
   "aiModelList",
   "aiModelDetail",
   "workflowList",
+  "workflowNodeCatalog",
   "workflowDetail",
   "workflowRunList",
   "workflowRunDetail",
@@ -18058,6 +18059,10 @@ var cliResultTypeSchema = external_exports.enum([
   "scheduleOccurrenceList",
   "scheduleExecutionList",
   "scheduleAction",
+  "dataBaseGlob",
+  "dataBaseRead",
+  "dataBaseGrep",
+  "dataBaseSearch",
   "generic"
 ]);
 var cliResultSchema = external_exports.object({
@@ -20193,6 +20198,260 @@ var cliAiModelDocs = [
       "first_last_frames_to_video requires exactly 2 referenceImage URLs.",
       "extendFromTaskId requires extendProviderId=socheap-media and resolution=720p."
     ]
+  },
+  {
+    id: "suno-music",
+    name: "Suno Music",
+    mediaType: "audio",
+    description: "Suno music generation with simple prompt and custom song modes.",
+    capabilities: ["text-to-audio"],
+    providers: ["socheap-media"],
+    variants: [
+      {
+        key: "v5_5",
+        display: "v5_5",
+        conditions: {},
+        billingUnit: "per_generation",
+        creditsPerUnit: 6.6
+      }
+    ],
+    fields: [
+      {
+        name: "prompt",
+        type: "string",
+        description: "Song description in simple mode, or lyrics in custom vocal mode."
+      },
+      {
+        name: "mode",
+        type: "string",
+        description: "Suno model version.",
+        values: ["v5_5"],
+        defaultValue: "v5_5"
+      },
+      {
+        name: "customMode",
+        type: "boolean",
+        description: "Enable custom lyrics, style, and title inputs.",
+        defaultValue: false
+      },
+      {
+        name: "instrumental",
+        type: "boolean",
+        description: "Generate an instrumental track. Only used in custom mode.",
+        defaultValue: false
+      },
+      {
+        name: "style",
+        type: "string",
+        description: "Required music style in custom mode."
+      },
+      {
+        name: "title",
+        type: "string",
+        description: "Required song title in custom mode."
+      }
+    ],
+    examples: [
+      {
+        label: "Generate music",
+        inputs: {
+          prompt: "A warm upbeat electronic instrumental for a product launch",
+          mode: "v5_5"
+        }
+      }
+    ],
+    notes: [
+      "Simple mode requires prompt. Custom mode requires style and title; vocal custom mode also requires prompt as lyrics."
+    ]
+  },
+  {
+    id: "elevenlabs-music-generation",
+    name: "Eleven Music V1",
+    mediaType: "audio",
+    description: "ElevenLabs prompt-to-music generation.",
+    capabilities: ["text-to-audio"],
+    providers: ["elevenlabs-audio"],
+    variants: [
+      {
+        key: "default",
+        display: "Per second",
+        conditions: {},
+        billingUnit: "per_second",
+        creditsPerUnit: 0.25
+      }
+    ],
+    fields: [
+      {
+        name: "prompt",
+        type: "string",
+        description: "Description of the music to generate.",
+        required: true
+      },
+      {
+        name: "duration",
+        type: "string",
+        description: "Whole number of seconds from 1 to 300.",
+        defaultValue: "10"
+      }
+    ],
+    examples: [
+      {
+        label: "Generate music",
+        inputs: {
+          prompt: "A calm ambient piano cue with a gentle ending",
+          duration: "10"
+        }
+      }
+    ]
+  },
+  {
+    id: "elevenlabs-sound-effects",
+    name: "Eleven Text To Sound V2",
+    mediaType: "audio",
+    description: "ElevenLabs sound-effect generation from an English prompt.",
+    capabilities: ["text-to-audio"],
+    providers: ["elevenlabs-audio"],
+    variants: [
+      {
+        key: "default",
+        display: "Per generation",
+        conditions: {},
+        billingUnit: "per_generation",
+        creditsPerUnit: 12
+      }
+    ],
+    fields: [
+      {
+        name: "prompt",
+        type: "string",
+        description: "English description of the sound effect.",
+        required: true
+      },
+      {
+        name: "duration",
+        type: "string",
+        description: "Duration in seconds from 0.5 to 30.",
+        defaultValue: "5"
+      }
+    ],
+    examples: [
+      {
+        label: "Generate a sound effect",
+        inputs: {
+          prompt: "A soft camera shutter in a quiet studio",
+          duration: "2"
+        }
+      }
+    ]
+  },
+  {
+    id: "elevenlabs-text-to-speech",
+    name: "ElevenLabs Text to Speech",
+    mediaType: "audio",
+    description: "ElevenLabs text-to-speech using an existing voice ID.",
+    capabilities: ["text-to-speech"],
+    providers: ["elevenlabs-audio"],
+    variants: [
+      {
+        key: "multilingual-v2-v3",
+        display: "Per character",
+        conditions: {},
+        billingUnit: "per_character",
+        creditsPerUnit: 0.01
+      }
+    ],
+    fields: [
+      {
+        name: "text",
+        type: "string",
+        description: "Text to speak.",
+        required: true
+      },
+      {
+        name: "voiceId",
+        type: "string",
+        description: "Existing ElevenLabs voice ID.",
+        required: true
+      },
+      {
+        name: "providerModelId",
+        type: "string",
+        description: "ElevenLabs speech model.",
+        values: ["eleven_multilingual_v2", "eleven_v3"],
+        defaultValue: "eleven_multilingual_v2"
+      }
+    ],
+    examples: [
+      {
+        label: "Generate speech",
+        inputs: {
+          text: "Welcome to Spira.",
+          voiceId: "<voice-id>",
+          providerModelId: "eleven_multilingual_v2"
+        }
+      }
+    ]
+  },
+  {
+    id: "elevenlabs-voice-clone-tts",
+    name: "ElevenLabs Voice TTS",
+    mediaType: "audio",
+    description: "Text-to-speech using either an existing voice ID or one reference audio URL.",
+    capabilities: ["text-to-speech", "audio-to-speech"],
+    providers: ["elevenlabs-audio"],
+    variants: [
+      {
+        key: "voice-clone-tts",
+        display: "Per character",
+        conditions: {},
+        billingUnit: "per_character",
+        creditsPerUnit: 0.01
+      }
+    ],
+    fields: [
+      {
+        name: "text",
+        type: "string",
+        description: "Text to speak.",
+        required: true
+      },
+      {
+        name: "voiceId",
+        type: "string",
+        description: "Existing ElevenLabs voice ID. Do not combine with referenceAudio."
+      },
+      {
+        name: "referenceAudio",
+        type: "string[]",
+        description: "Exactly one audio URL when cloning a voice. Do not combine with voiceId."
+      },
+      {
+        name: "providerModelId",
+        type: "string",
+        description: "ElevenLabs speech model.",
+        values: ["eleven_multilingual_v2", "eleven_v3"],
+        defaultValue: "eleven_multilingual_v2"
+      },
+      {
+        name: "qualityMode",
+        type: "string",
+        description: "Voice delivery mode.",
+        values: ["stable", "expressive"],
+        defaultValue: "stable"
+      }
+    ],
+    examples: [
+      {
+        label: "Generate speech from a reference voice",
+        inputs: {
+          text: "Welcome to Spira.",
+          referenceAudio: ["https://example.com/reference.mp3"],
+          providerModelId: "eleven_multilingual_v2",
+          qualityMode: "stable"
+        }
+      }
+    ],
+    notes: ["Provide either voiceId or exactly one referenceAudio URL, never both."]
   }
 ];
 function listCliAiModelDocs(mediaType) {
@@ -20202,6 +20461,115 @@ function getCliAiModelDoc(modelId) {
   return cliAiModelDocs.find((model) => model.id === modelId);
 }
 
+// src/ai/wait.ts
+function wait(durationMs) {
+  return new Promise((resolve) => setTimeout(resolve, durationMs));
+}
+function jobStatus(result) {
+  if (!result.data || typeof result.data !== "object") return void 0;
+  const status = result.data.status;
+  return typeof status === "string" ? status : void 0;
+}
+function providerError(result) {
+  if (!result.data || typeof result.data !== "object") return void 0;
+  const latestExecution = result.data.latestExecution;
+  if (!latestExecution || typeof latestExecution !== "object") return void 0;
+  const error51 = latestExecution.error;
+  if (typeof error51 === "string") return error51;
+  if (error51 && typeof error51 === "object" && typeof error51.message === "string") {
+    return error51.message;
+  }
+  return void 0;
+}
+function completedResult(result) {
+  return cliResultSchema.parse({
+    ...result,
+    resultType: "aiJobStatus",
+    command: "spira ai jobs create",
+    nextActions: []
+  });
+}
+function pollingError(result) {
+  return cliResultSchema.parse({
+    ...result,
+    command: "spira ai jobs create"
+  });
+}
+function terminalError(result, jobId, status) {
+  const message = providerError(result) ?? `AI job ${jobId} ended with status ${status}.`;
+  return cliResultSchema.parse({
+    ...result,
+    status: "error",
+    resultType: "aiJobStatus",
+    command: "spira ai jobs create",
+    error: {
+      code: status === "FAILED" ? "PROVIDER_FAILED" : "ASYNC_STATE",
+      message,
+      resource: { type: "aiJob", id: jobId },
+      retryable: false,
+      nextActions: [{ label: "Show job status", command: `spira ai jobs status ${jobId}` }]
+    }
+  });
+}
+function timeoutResult(jobId, timeoutMs, lastResult) {
+  return cliResultSchema.parse({
+    object: "cli.result",
+    status: "error",
+    resultType: "aiJobStatus",
+    command: "spira ai jobs create",
+    data: lastResult?.data,
+    ids: { ...lastResult?.ids, jobId },
+    error: {
+      code: "TIMEOUT",
+      message: `AI job ${jobId} did not finish within ${timeoutMs}ms.`,
+      resource: { type: "aiJob", id: jobId },
+      retryable: true,
+      nextActions: [{ label: "Show job status", command: `spira ai jobs status ${jobId}` }]
+    }
+  });
+}
+function contractError(result, jobId) {
+  return cliResultSchema.parse({
+    ...result,
+    status: "error",
+    resultType: "aiJobStatus",
+    command: "spira ai jobs create",
+    error: {
+      code: "CONTRACT_MISMATCH",
+      message: `AI job ${jobId} status response did not contain a recognized status.`,
+      resource: { type: "aiJob", id: jobId },
+      retryable: false,
+      nextActions: [{ label: "Show job status", command: `spira ai jobs status ${jobId}` }]
+    }
+  });
+}
+async function waitForAiJob(input) {
+  const now = input.now ?? Date.now;
+  const sleep = input.sleep ?? wait;
+  const deadline = now() + input.timeoutMs;
+  let lastResult;
+  let lastStatus;
+  while (true) {
+    const result = await input.poll();
+    lastResult = result;
+    if (result.status === "error") {
+      if (!result.error?.retryable) return pollingError(result);
+    } else {
+      const status = jobStatus(result);
+      if (status && status !== lastStatus) {
+        input.onStatus?.(status);
+        lastStatus = status;
+      }
+      if (status === "COMPLETED") return completedResult(result);
+      if (status === "FAILED" || status === "CANCELED") return terminalError(result, input.jobId, status);
+      if (status !== "QUEUED" && status !== "RUNNING") return contractError(result, input.jobId);
+    }
+    const remainingMs = deadline - now();
+    if (remainingMs <= 0) return timeoutResult(input.jobId, input.timeoutMs, lastResult);
+    await sleep(Math.min(input.intervalMs, remainingMs));
+  }
+}
+
 // src/commands/definitions.ts
 var commonListOptions = [
   {
@@ -20385,7 +20753,10 @@ var commandDefinitions = [
     },
     resultType: "socialSubmissionList",
     examples: ["spira social submissions list --platform tiktok --status draft --limit 10"],
-    relatedCommands: ["spira social submissions get <submissionId>", "spira social submissions publish <submissionId> --confirm"]
+    relatedCommands: [
+      "spira social submissions get <submissionId>",
+      "spira social submissions publish <submissionId> --confirm"
+    ]
   },
   {
     path: ["social", "submissions", "get"],
@@ -20431,7 +20802,12 @@ var commandDefinitions = [
         defaultValue: "oauth_account"
       },
       { name: "title", flag: "--title <title>", description: "Draft title.", type: "string" },
-      { name: "description", flag: "--description <description>", description: "Draft description/text.", type: "string" },
+      {
+        name: "description",
+        flag: "--description <description>",
+        description: "Draft description/text.",
+        type: "string"
+      },
       { name: "mediaUrls", flag: "--media-url <url>", description: "Media URL. Repeatable.", type: "stringArray" },
       { name: "agentId", flag: "--agent-id <agentId>", description: "Associated agent ID.", type: "string" },
       {
@@ -20458,9 +20834,7 @@ var commandDefinitions = [
       ]
     },
     resultType: "socialSubmissionAction",
-    examples: [
-      'spira social submissions create --platform twitter --content-kind text --description "Launch note"'
-    ],
+    examples: ['spira social submissions create --platform twitter --content-kind text --description "Launch note"'],
     relatedCommands: [
       "spira social submissions get <submissionId>",
       "spira social submissions publish <submissionId> --confirm"
@@ -20471,9 +20845,20 @@ var commandDefinitions = [
     purpose: "Publish a social submission draft.",
     arguments: [{ name: "submissionId", description: "Submission ID.", required: true }],
     options: [
-      { name: "confirm", flag: "--confirm", description: "Required explicit publish confirmation.", type: "boolean", required: true },
+      {
+        name: "confirm",
+        flag: "--confirm",
+        description: "Required explicit publish confirmation.",
+        type: "boolean",
+        required: true
+      },
       { name: "title", flag: "--title <title>", description: "Platform title override.", type: "string" },
-      { name: "description", flag: "--description <description>", description: "Platform description override.", type: "string" },
+      {
+        name: "description",
+        flag: "--description <description>",
+        description: "Platform description override.",
+        type: "string"
+      },
       { name: "text", flag: "--text <text>", description: "Text override for X or LinkedIn.", type: "string" },
       { name: "mediaUrls", flag: "--media-url <url>", description: "Media URL. Repeatable.", type: "stringArray" },
       { name: "privacyLevel", flag: "--privacy-level <value>", description: "TikTok privacy level.", type: "string" },
@@ -20514,18 +20899,18 @@ var commandDefinitions = [
   },
   {
     path: ["ai", "models", "list"],
-    purpose: "List AI image and video models available from the CLI.",
+    purpose: "List AI image, video, and audio models available from the CLI.",
     options: [
       {
         name: "mediaType",
         flag: "--media-type <type>",
         description: "Filter by model media type.",
         type: "string",
-        enumValues: ["image", "video"]
+        enumValues: ["image", "video", "audio"]
       }
     ],
     resultType: "aiModelList",
-    examples: ["spira ai models list", "spira ai models list --media-type video"],
+    examples: ["spira ai models list", "spira ai models list --media-type audio"],
     relatedCommands: ["spira ai models get <modelId>", "spira ai jobs create"]
   },
   {
@@ -20538,11 +20923,45 @@ var commandDefinitions = [
   },
   {
     path: ["ai", "jobs", "create"],
-    purpose: "Create an AI image or video generation job.",
+    purpose: "Create an AI image, video, or audio generation job.",
     options: [
       { name: "modelId", flag: "--model-id <modelId>", description: "AI model ID.", type: "string", required: true },
-      { name: "providerId", flag: "--provider-id <providerId>", description: "Advanced routing override.", type: "string", hidden: true },
-      { name: "inputsJson", flag: "--inputs-json <json>", description: "Model inputs JSON object.", type: "json", required: true }
+      {
+        name: "providerId",
+        flag: "--provider-id <providerId>",
+        description: "Advanced routing override.",
+        type: "string",
+        hidden: true
+      },
+      {
+        name: "inputsJson",
+        flag: "--inputs-json <json>",
+        description: "Model inputs JSON object.",
+        type: "json",
+        required: true
+      },
+      {
+        name: "wait",
+        flag: "--wait",
+        description: "Wait for the job to finish and print the final result.",
+        type: "boolean"
+      },
+      {
+        name: "waitTimeout",
+        flag: "--wait-timeout <duration>",
+        description: "Maximum wait duration.",
+        type: "duration",
+        defaultValue: 6e5,
+        minimum: 1e3
+      },
+      {
+        name: "waitInterval",
+        flag: "--wait-interval <duration>",
+        description: "Polling interval while waiting.",
+        type: "duration",
+        defaultValue: 3e3,
+        minimum: 1e3
+      }
     ],
     http: {
       method: "POST",
@@ -20555,7 +20974,10 @@ var commandDefinitions = [
       ]
     },
     resultType: "aiJobAction",
-    examples: [`spira ai jobs create --model-id nano-banana-2 --inputs-json '{"prompt":"A product photo"}'`],
+    examples: [
+      `spira ai jobs create --model-id nano-banana-2 --inputs-json '{"prompt":"A product photo"}'`,
+      `spira ai jobs create --model-id nano-banana-2 --inputs-json '{"prompt":"A product photo"}' --wait`
+    ],
     relatedCommands: ["spira ai jobs status <jobId>", "spira ai models get <modelId>", "spira credits balance"]
   },
   {
@@ -20592,6 +21014,33 @@ var commandDefinitions = [
       "spira workflows runs list <workflowId>"
     ]
   },
+  {
+    path: ["workflows", "node-catalog"],
+    purpose: "Show the current server workflow node catalog.",
+    options: [
+      {
+        name: "surface",
+        flag: "--surface <surface>",
+        description: "Workflow access surface.",
+        type: "string",
+        enumValues: ["dashboard", "admin"],
+        defaultValue: "dashboard"
+      }
+    ],
+    http: {
+      method: "GET",
+      path: "/api/cli/v1/workflows/node-catalog",
+      authRequired: true,
+      query: [{ name: "surface", source: "option", from: "surface" }]
+    },
+    resultType: "workflowNodeCatalog",
+    examples: ["spira workflows node-catalog --json", "spira workflows node-catalog --surface admin --json"],
+    relatedCommands: [
+      "spira workflows create --name <name>",
+      "spira workflows update <workflowId>",
+      "spira workflows get <workflowId>"
+    ]
+  },
   {
     path: ["workflows", "create"],
     purpose: "Create a canvas workflow.",
@@ -20635,7 +21084,11 @@ var commandDefinitions = [
       'spira workflows create --name "Product launch workflow"',
       `spira workflows create --name "Product launch workflow" --workflow-definition-json '{"nodes":[],"edges":[]}'`
     ],
-    relatedCommands: ["spira workflows get <workflowId>", "spira workflows update <workflowId>", "spira workflows runs start <workflowId>"]
+    relatedCommands: [
+      "spira workflows get <workflowId>",
+      "spira workflows update <workflowId>",
+      "spira workflows runs start <workflowId>"
+    ]
   },
   {
     path: ["workflows", "get"],
@@ -20773,7 +21226,12 @@ var commandDefinitions = [
     purpose: "Start a workflow run and return its run ID.",
     arguments: [{ name: "workflowId", description: "Workflow ID.", required: true }],
     options: [
-      { name: "startOptionsJson", flag: "--start-options-json <json>", description: "Workflow start options JSON.", type: "json" },
+      {
+        name: "startOptionsJson",
+        flag: "--start-options-json <json>",
+        description: "Workflow start options JSON.",
+        type: "json"
+      },
       {
         name: "surface",
         flag: "--surface <surface>",
@@ -20832,7 +21290,9 @@ var commandDefinitions = [
     path: ["schedules", "executions"],
     purpose: "List persisted schedule execution attempts.",
     arguments: [{ name: "scheduleId", description: "Schedule ID.", required: true }],
-    options: [{ name: "limit", flag: "--limit <number>", description: "Maximum executions to return.", type: "number" }],
+    options: [
+      { name: "limit", flag: "--limit <number>", description: "Maximum executions to return.", type: "number" }
+    ],
     http: {
       method: "GET",
       path: "/api/schedules/:scheduleId/executions",
@@ -20848,11 +21308,28 @@ var commandDefinitions = [
     path: ["schedules", "calendar"],
     purpose: "List scheduled occurrences between two times.",
     options: [
-      { name: "from", flag: "--from <ms>", description: "Start timestamp in epoch milliseconds.", type: "number", required: true },
-      { name: "to", flag: "--to <ms>", description: "End timestamp in epoch milliseconds.", type: "number", required: true },
+      {
+        name: "from",
+        flag: "--from <ms>",
+        description: "Start timestamp in epoch milliseconds.",
+        type: "number",
+        required: true
+      },
+      {
+        name: "to",
+        flag: "--to <ms>",
+        description: "End timestamp in epoch milliseconds.",
+        type: "number",
+        required: true
+      },
       { name: "limit", flag: "--limit <number>", description: "Maximum occurrences to return.", type: "number" },
       { name: "offset", flag: "--offset <number>", description: "Zero-based occurrence offset.", type: "number" },
-      { name: "scheduleId", flag: "--schedule-id <scheduleId>", description: "Optional schedule id filter.", type: "string" }
+      {
+        name: "scheduleId",
+        flag: "--schedule-id <scheduleId>",
+        description: "Optional schedule id filter.",
+        type: "string"
+      }
     ],
     http: {
       method: "GET",
@@ -20869,6 +21346,125 @@ var commandDefinitions = [
     resultType: "scheduleOccurrenceList",
     examples: ["spira schedules calendar --from 1781884800000 --to 1782490000000"],
     relatedCommands: ["spira schedules get <scheduleId>"]
+  },
+  {
+    path: ["dataBase", "glob"],
+    purpose: "List files and folders in your Brand database matching a glob pattern.",
+    arguments: [{ name: "pattern", description: "Glob pattern (default: /**).", required: false }],
+    http: {
+      method: "GET",
+      path: "/api/cli/v1/data-base/glob",
+      authRequired: true,
+      query: [{ name: "pattern", source: "argument", from: "pattern" }]
+    },
+    resultType: "dataBaseGlob",
+    examples: ["spira dataBase glob", "spira dataBase glob '/docs/**'", "spira dataBase glob '/**/*.md'"],
+    relatedCommands: ["spira dataBase read <path>", 'spira dataBase search "<query>"']
+  },
+  {
+    path: ["dataBase", "read"],
+    purpose: "Read file content at a Brand database path with optional line/page slicing.",
+    arguments: [{ name: "path", description: "Brand database path (e.g. /docs/style-guide.md).", required: true }],
+    options: [
+      { name: "line", flag: "--line <number>", description: "Start line (1-based).", type: "number" },
+      { name: "lineEnd", flag: "--line-end <number>", description: "End line (inclusive).", type: "number" },
+      { name: "page", flag: "--page <number>", description: "Start page (1-based, PDFs).", type: "number" },
+      { name: "pageEnd", flag: "--page-end <number>", description: "End page (inclusive).", type: "number" },
+      {
+        name: "expand",
+        flag: "--expand <number>",
+        description: "Extra lines of context around the range.",
+        type: "number"
+      }
+    ],
+    http: {
+      method: "GET",
+      path: "/api/cli/v1/data-base/read",
+      authRequired: true,
+      query: [
+        { name: "path", source: "argument", from: "path" },
+        { name: "line", source: "option", from: "line" },
+        { name: "lineEnd", source: "option", from: "lineEnd" },
+        { name: "page", source: "option", from: "page" },
+        { name: "pageEnd", source: "option", from: "pageEnd" },
+        { name: "expand", source: "option", from: "expand" }
+      ]
+    },
+    resultType: "dataBaseRead",
+    examples: [
+      "spira dataBase read /README.md",
+      "spira dataBase read /docs/style-guide.md --line 40 --line-end 120",
+      "spira dataBase read /decks/pitch.pdf --page 2 --page-end 3"
+    ],
+    relatedCommands: ["spira dataBase glob", 'spira dataBase search "<query>"']
+  },
+  {
+    path: ["dataBase", "grep"],
+    purpose: "Lexical (FTS + exact) search across your Brand database. Fast and deterministic.",
+    arguments: [{ name: "query", description: "Search query.", required: true }],
+    options: [
+      { name: "scope", flag: "--scope <path>", description: "Restrict to a folder path.", type: "string" },
+      { name: "limit", flag: "--limit <number>", description: "Max matches (default 20, max 100).", type: "number" },
+      {
+        name: "debug",
+        flag: "--debug",
+        description: "Include candidate scoring breakdown (JSON mode).",
+        type: "boolean"
+      }
+    ],
+    http: {
+      method: "POST",
+      path: "/api/cli/v1/data-base/grep",
+      authRequired: true,
+      body: [
+        { name: "query", source: "argument", from: "query" },
+        { name: "scope", source: "option", from: "scope" },
+        { name: "limit", source: "option", from: "limit" },
+        { name: "debug", source: "option", from: "debug" }
+      ]
+    },
+    resultType: "dataBaseGrep",
+    examples: ['spira dataBase grep "brand voice"', 'spira dataBase grep "tone" --scope /docs --limit 10'],
+    relatedCommands: ["spira dataBase read <path>", 'spira dataBase search "<query>"']
+  },
+  {
+    path: ["dataBase", "search"],
+    purpose: "Semantic search (pgvector + RRF + MMR) across your Brand database.",
+    arguments: [{ name: "query", description: "Natural-language query.", required: true }],
+    options: [
+      { name: "scope", flag: "--scope <path>", description: "Restrict to a folder path.", type: "string" },
+      { name: "limit", flag: "--limit <number>", description: "Max matches (default 20, max 100).", type: "number" },
+      {
+        name: "rerank",
+        flag: "--rerank",
+        description: "Enable LLM reranking (slower, higher quality).",
+        type: "boolean"
+      },
+      {
+        name: "debug",
+        flag: "--debug",
+        description: "Include candidate scoring breakdown (JSON mode).",
+        type: "boolean"
+      }
+    ],
+    http: {
+      method: "POST",
+      path: "/api/cli/v1/data-base/search",
+      authRequired: true,
+      body: [
+        { name: "query", source: "argument", from: "query" },
+        { name: "scope", source: "option", from: "scope" },
+        { name: "limit", source: "option", from: "limit" },
+        { name: "rerank", source: "option", from: "rerank" },
+        { name: "debug", source: "option", from: "debug" }
+      ]
+    },
+    resultType: "dataBaseSearch",
+    examples: [
+      'spira dataBase search "what is our stance on price anchoring"',
+      'spira dataBase search "founder biography" --scope /about --rerank'
+    ],
+    relatedCommands: ["spira dataBase read <path>", 'spira dataBase grep "<query>"']
   }
 ];
 function findCommandDefinition(path) {
@@ -20892,6 +21488,13 @@ function validateCommandInput(command, args, options) {
         return validationError(command, option.name, `Expected one of: ${option.enumValues.join(", ")}.`);
       }
     }
+    if (typeof value === "number" && option.minimum !== void 0 && value < option.minimum) {
+      return validationError(
+        command,
+        option.name,
+        `${getOptionDisplayName(option.flag)} must be at least ${option.minimum}.`
+      );
+    }
   }
   return null;
 }
@@ -21445,6 +22048,43 @@ async function logout() {
   });
 }
 
+// src/render/ai-job-wait.ts
+function objectRecord(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function compactResult(result) {
+  const data = objectRecord(result.data);
+  const execution = objectRecord(data.latestExecution);
+  const status = typeof data.status === "string" ? data.status.toLowerCase() : result.status;
+  const resultUrls = Array.isArray(execution.resultUrls) ? execution.resultUrls.filter((url2) => typeof url2 === "string") : [];
+  return {
+    id: typeof data.id === "string" ? data.id : result.ids.jobId,
+    modelId: typeof data.modelId === "string" ? data.modelId : void 0,
+    status,
+    resultType: typeof execution.resultType === "string" ? execution.resultType : void 0,
+    resultUrls,
+    ...result.error ? {
+      error: {
+        code: result.error.code,
+        message: result.error.message,
+        retryable: result.error.retryable
+      }
+    } : {}
+  };
+}
+function renderAiJobWait(result, options) {
+  const compact = compactResult(result);
+  if (options.json) return `${JSON.stringify(compact, null, 2)}
+`;
+  const lines = [`id: ${compact.id ?? "-"}`, `status: ${compact.status}`];
+  if (compact.modelId) lines.push(`modelId: ${compact.modelId}`);
+  if (compact.resultType) lines.push(`resultType: ${compact.resultType}`);
+  lines.push(...compact.resultUrls);
+  if (compact.error) lines.push(`error: ${compact.error.message}`);
+  return `${lines.join("\n")}
+`;
+}
+
 // src/render/human.ts
 function valueToText(value) {
   if (value === null || value === void 0 || value === "") return "-";
@@ -21495,11 +22135,11 @@ function renderKeyValues(data) {
 `;
   return Object.entries(data).filter(([, value]) => typeof value !== "object" || value === null).map(([key, value]) => `${key}: ${valueToText(value)}`).join("\n").concat("\n");
 }
-function objectRecord(data) {
+function objectRecord2(data) {
   return data && typeof data === "object" ? data : {};
 }
 function formatWhen(value) {
-  const record2 = objectRecord(value);
+  const record2 = objectRecord2(value);
   const entries = Object.entries(record2);
   if (!entries.length) return "";
   return entries.map(([key, item]) => `${key}=${valueToText(item)}`).join(", ");
@@ -21512,11 +22152,34 @@ function formatCreditOption(option) {
   const when = formatWhen(option.when ?? option.conditions);
   return `  ${key}: ${label} - ${credits} credits ${unit}${when ? ` (${when})` : ""}`;
 }
+function portSummary(ports) {
+  if (!Array.isArray(ports) || ports.length === 0) return "-";
+  return ports.map((port) => {
+    const record2 = objectRecord2(port);
+    const suffix = record2.multiple ? "[]" : "";
+    return `${valueToText(record2.id)}:${valueToText(record2.valueType)}${suffix}`;
+  }).join(", ");
+}
+function renderWorkflowNodeCatalog(data) {
+  const record2 = objectRecord2(data);
+  const nodes = Array.isArray(record2.nodes) ? record2.nodes : [];
+  const rows = nodes.map((node) => {
+    const nodeRecord = objectRecord2(node);
+    const ports = objectRecord2(nodeRecord.ports);
+    return {
+      type: nodeRecord.type,
+      inputs: portSummary(ports.inputs),
+      outputs: portSummary(ports.outputs),
+      requiredPermission: nodeRecord.requiredPermission
+    };
+  });
+  return renderRows(rows, ["type", "inputs", "outputs", "requiredPermission"]);
+}
 function renderAccountList(data) {
   const channels = data && typeof data === "object" ? data.publishChannels : null;
   if (Array.isArray(channels)) {
     const rows = channels.map((channel) => {
-      const record2 = objectRecord(channel);
+      const record2 = objectRecord2(channel);
       return {
         platform: record2.platform,
         connected: record2.oauthAccountsCount,
@@ -21529,12 +22192,12 @@ function renderAccountList(data) {
   return renderKeyValues(data);
 }
 function renderAccountConnect(data) {
-  const record2 = objectRecord(data);
+  const record2 = objectRecord2(data);
   return `platform: ${valueToText(record2.platform)}
 `;
 }
 function renderCreditBalance(data) {
-  const record2 = objectRecord(data);
+  const record2 = objectRecord2(data);
   const lines = [
     `availableCredits: ${formatCredits(record2.availableCredits)}`,
     `permanentCredits: ${formatCredits(record2.availablePermanentCredits)}`,
@@ -21561,7 +22224,7 @@ function renderUser(prefix, value) {
 function renderAuthWhoami(data) {
   if (!data || typeof data !== "object") return renderKeyValues(data);
   const record2 = data;
-  const effective = objectRecord(record2.effectiveUser);
+  const effective = objectRecord2(record2.effectiveUser);
   const name = valueToText(effective.name);
   const email3 = valueToText(effective.email);
   const lines = [`user: ${name}${email3 === "-" ? "" : ` <${email3}>`}`];
@@ -21576,8 +22239,8 @@ function renderAuthLogin(data) {
 `;
 }
 function renderSocialSubmissionDetail(data) {
-  const raw = objectRecord(data);
-  const nested = objectRecord(raw.data);
+  const raw = objectRecord2(data);
+  const nested = objectRecord2(raw.data);
   const record2 = nested.submission_id || nested.postUrl || nested.tweetId ? {
     id: nested.submission_id,
     platform: raw.platform,
@@ -21611,8 +22274,8 @@ function renderSocialSubmissionDetail(data) {
 `;
 }
 function renderAiJobStatus(data) {
-  const record2 = objectRecord(data);
-  const latestExecution = objectRecord(record2.latestExecution);
+  const record2 = objectRecord2(data);
+  const latestExecution = objectRecord2(record2.latestExecution);
   const resultUrls = Array.isArray(latestExecution.resultUrls) ? latestExecution.resultUrls : [];
   const lines = [
     `id: ${valueToText(record2.id)}`,
@@ -21631,10 +22294,10 @@ function renderAiModelList(data) {
   return renderRows(dataArray(data), ["id", "mediaType", "creditOptions", "name", "capabilities"]);
 }
 function renderAiModelDetail(data) {
-  const record2 = objectRecord(data);
-  const fields = Array.isArray(record2.fields) ? record2.fields.map(objectRecord) : [];
-  const creditOptions = Array.isArray(record2.creditOptions) ? record2.creditOptions.map(objectRecord) : Array.isArray(record2.variants) ? record2.variants.map(objectRecord) : [];
-  const examples = Array.isArray(record2.examples) ? record2.examples.map(objectRecord) : [];
+  const record2 = objectRecord2(data);
+  const fields = Array.isArray(record2.fields) ? record2.fields.map(objectRecord2) : [];
+  const creditOptions = Array.isArray(record2.creditOptions) ? record2.creditOptions.map(objectRecord2) : Array.isArray(record2.variants) ? record2.variants.map(objectRecord2) : [];
+  const examples = Array.isArray(record2.examples) ? record2.examples.map(objectRecord2) : [];
   const notes = Array.isArray(record2.notes) ? record2.notes : [];
   const lines = [
     `id: ${valueToText(record2.id)}`,
@@ -21674,8 +22337,8 @@ function renderAiModelDetail(data) {
 `;
 }
 function renderWorkflowDetail(data) {
-  const record2 = objectRecord(data);
-  const definition = objectRecord(record2.workflowDefinition);
+  const record2 = objectRecord2(data);
+  const definition = objectRecord2(record2.workflowDefinition);
   const nodes = Array.isArray(definition.nodes) ? definition.nodes : [];
   const edges = Array.isArray(definition.edges) ? definition.edges : [];
   return [
@@ -21688,9 +22351,9 @@ function renderWorkflowDetail(data) {
   ].join("\n").concat("\n");
 }
 function renderScheduleDetail(data) {
-  const record2 = objectRecord(data);
-  const executorConfig = objectRecord(record2.executorConfig);
-  const currentPattern = objectRecord(record2.currentPattern);
+  const record2 = objectRecord2(data);
+  const executorConfig = objectRecord2(record2.executorConfig);
+  const currentPattern = objectRecord2(record2.currentPattern);
   return [
     `id: ${valueToText(record2.id)}`,
     `executorType: ${valueToText(record2.executorType)}`,
@@ -21703,6 +22366,112 @@ function renderScheduleDetail(data) {
     `scheduledAt: ${valueToText(currentPattern.scheduledAt)}`
   ].join("\n").concat("\n");
 }
+function formatByteSize(value) {
+  const n = typeof value === "number" && Number.isFinite(value) ? value : NaN;
+  if (!Number.isFinite(n) || n < 0) return "-";
+  if (n < 1024) return `${n} B`;
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(n < 10 * 1024 ? 1 : 0)} KB`;
+  if (n < 1024 * 1024 * 1024) return `${(n / (1024 * 1024)).toFixed(1)} MB`;
+  return `${(n / (1024 * 1024 * 1024)).toFixed(2)} GB`;
+}
+function formatAnchor(anchor) {
+  const parts = [];
+  const line = anchor.line;
+  const lineEnd = anchor.lineEnd;
+  const page = anchor.page;
+  const pageEnd = anchor.pageEnd;
+  const timeStart = anchor.timeStartMs;
+  const timeEnd = anchor.timeEndMs;
+  if (typeof line === "number") {
+    parts.push(typeof lineEnd === "number" ? `L${line}-${lineEnd}` : `L${line}`);
+  }
+  if (typeof page === "number") {
+    parts.push(typeof pageEnd === "number" ? `p${page}-${pageEnd}` : `p${page}`);
+  }
+  if (typeof timeStart === "number") {
+    parts.push(typeof timeEnd === "number" ? `t${timeStart}-${timeEnd}ms` : `t${timeStart}ms`);
+  }
+  return parts.join(", ") || "-";
+}
+function renderDataBaseGlob(data) {
+  const record2 = objectRecord2(data);
+  const pattern = valueToText(record2.pattern);
+  const entries = Array.isArray(record2.entries) ? record2.entries.map(objectRecord2) : [];
+  if (entries.length === 0) return `pattern: ${pattern}
+No entries.
+`;
+  const rows = entries.map((entry) => {
+    const isFolder = entry.type === "folder";
+    const isVirtual = entry.virtual === true;
+    return {
+      type: isFolder ? "dir" : isVirtual ? "file*" : "file",
+      path: entry.path,
+      fileType: isFolder ? "-" : valueToText(entry.fileType),
+      size: isFolder ? `${valueToText(entry.fileCount)} files` : formatByteSize(entry.size),
+      status: isFolder ? "-" : valueToText(entry.processingStatus),
+      updatedAt: entry.updatedAt
+    };
+  });
+  return `pattern: ${pattern}  (${entries.length} entries)
+${renderRows(rows, ["type", "path", "fileType", "size", "status", "updatedAt"])}`;
+}
+function renderDataBaseRead(data) {
+  const record2 = objectRecord2(data);
+  const path = valueToText(record2.path);
+  const fileType = valueToText(record2.fileType);
+  const mimeType = valueToText(record2.mimeType);
+  const rangeObj = objectRecord2(record2.range);
+  let rangeStr = "-";
+  if (Array.isArray(rangeObj.line) && rangeObj.line.length === 2) {
+    rangeStr = `lines ${rangeObj.line[0]}-${rangeObj.line[1]}`;
+  } else if (Array.isArray(rangeObj.page) && rangeObj.page.length === 2) {
+    rangeStr = `pages ${rangeObj.page[0]}-${rangeObj.page[1]}`;
+  }
+  const totalLines = record2.totalLines !== void 0 ? valueToText(record2.totalLines) : "-";
+  const truncated = valueToText(record2.truncated);
+  const lines = [
+    `path: ${path}`,
+    `fileType: ${fileType}`,
+    `mimeType: ${mimeType}`,
+    `range: ${rangeStr}`,
+    `totalLines: ${totalLines}`,
+    `truncated: ${truncated}`
+  ];
+  if (record2.virtual === true) lines.push("virtual: true");
+  if (record2.processingStatus) lines.push(`processingStatus: ${valueToText(record2.processingStatus)}`);
+  if (record2.storageUrl) lines.push(`storageUrl: ${valueToText(record2.storageUrl)}`);
+  const content = typeof record2.content === "string" ? record2.content : "";
+  const header = `${lines.join("\n")}
+`;
+  const nextLine = typeof record2.nextLine === "number" ? record2.nextLine : void 0;
+  const footer = record2.truncated === true && nextLine ? `
+--
+(truncated; continue with: spira dataBase read ${path} --line ${nextLine})
+` : "";
+  return `${header}
+${content}${footer}`;
+}
+function renderDataBaseMatches(data) {
+  const record2 = objectRecord2(data);
+  const query = valueToText(record2.query);
+  const matches = Array.isArray(record2.matches) ? record2.matches.map(objectRecord2) : [];
+  if (matches.length === 0) return `query: ${query}
+No matches.
+`;
+  const blocks = matches.map((match) => {
+    const anchor = formatAnchor(objectRecord2(match.anchor));
+    const score = typeof match.score === "number" ? match.score.toFixed(3) : valueToText(match.score);
+    const fields = Array.isArray(match.matchedFields) ? match.matchedFields.join(",") : "";
+    const header = `${valueToText(match.path)}(${anchor})  [score=${score}${fields ? ` fields=${fields}` : ""}]`;
+    const snippet = typeof match.snippet === "string" ? match.snippet : valueToText(match.snippet);
+    const indented = snippet.split("\n").map((line) => `  ${line}`).join("\n");
+    return `${header}
+${indented}`;
+  });
+  return `query: ${query}  (${matches.length} matches)
+${blocks.join("\n\n")}
+`;
+}
 function renderSuccess(result) {
   switch (result.resultType) {
     case "authLogin":
@@ -21720,7 +22489,7 @@ function renderSuccess(result) {
     case "socialSubmissionList":
       return renderRows(
         dataArray(result.data).map((item) => {
-          const record2 = objectRecord(item);
+          const record2 = objectRecord2(item);
           return {
             id: record2.id,
             platform: record2.platform,
@@ -21745,6 +22514,8 @@ function renderSuccess(result) {
       return renderAiModelDetail(result.data);
     case "workflowList":
       return renderRows(dataArray(result.data), ["id", "name", "creatorName", "nodeTypes", "updatedAt"]);
+    case "workflowNodeCatalog":
+      return renderWorkflowNodeCatalog(result.data);
     case "workflowDetail":
       return renderWorkflowDetail(result.data);
     case "workflowRunList":
@@ -21757,6 +22528,13 @@ function renderSuccess(result) {
       return renderRows(dataArray(result.data), ["id", "scheduleId", "scheduledAt", "status", "executorType"]);
     case "scheduleExecutionList":
       return renderRows(dataArray(result.data), ["id", "scheduleId", "status", "originalScheduledAt", "startedAt", "finishedAt"]);
+    case "dataBaseGlob":
+      return renderDataBaseGlob(result.data);
+    case "dataBaseRead":
+      return renderDataBaseRead(result.data);
+    case "dataBaseGrep":
+    case "dataBaseSearch":
+      return renderDataBaseMatches(result.data);
     default:
       return renderKeyValues(result.data);
   }
@@ -21808,6 +22586,7 @@ function renderJson(result) {
 
 // src/render/index.ts
 function renderResult(result, options) {
+  if (options.compactAiJobWait) return renderAiJobWait(result, options);
   return options.json ? renderJson(result) : renderHuman(result);
 }
 
@@ -21960,6 +22739,24 @@ function parseNumber(value) {
   if (!Number.isFinite(parsed)) throw new InvalidArgumentError("Expected a number.");
   return parsed;
 }
+function parseDuration(value) {
+  const match = /^(\d+(?:\.\d+)?)(ms|s|m|h)$/.exec(value.trim());
+  if (!match) throw new InvalidArgumentError("Expected a duration such as 500ms, 3s, 10m, or 1h.");
+  const amount = Number(match[1]);
+  const unit = match[2];
+  const multiplier = unit === "ms" ? 1 : unit === "s" ? 1e3 : unit === "m" ? 6e4 : 36e5;
+  const durationMs = amount * multiplier;
+  if (!Number.isSafeInteger(durationMs) || durationMs <= 0) {
+    throw new InvalidArgumentError("Expected a positive duration.");
+  }
+  return durationMs;
+}
+function formatDuration(durationMs) {
+  if (durationMs % 36e5 === 0) return `${durationMs / 36e5}h`;
+  if (durationMs % 6e4 === 0) return `${durationMs / 6e4}m`;
+  if (durationMs % 1e3 === 0) return `${durationMs / 1e3}s`;
+  return `${durationMs}ms`;
+}
 function parseJson(value) {
   try {
     return JSON.parse(value);
@@ -21978,6 +22775,11 @@ function addOption(command, definition) {
     command.addOption(option.argParser(parseNumber).default(definition.defaultValue));
     return;
   }
+  if (definition.type === "duration") {
+    const defaultDescription = typeof definition.defaultValue === "number" ? formatDuration(definition.defaultValue) : void 0;
+    command.addOption(option.argParser(parseDuration).default(definition.defaultValue, defaultDescription));
+    return;
+  }
   if (definition.type === "json") {
     command.addOption(option.argParser(parseJson).default(definition.defaultValue));
     return;
@@ -22034,10 +22836,7 @@ function getOrCreateSubcommand(parent, name) {
   return next;
 }
 function renderCommandReference(definition) {
-  const lines = [
-    `Command: spira ${definition.path.join(" ")}`,
-    `Description: ${definition.purpose}`
-  ];
+  const lines = [`Command: spira ${definition.path.join(" ")}`, `Description: ${definition.purpose}`];
   if (definition.arguments?.length) {
     lines.push("Arguments:");
     for (const argument of definition.arguments) {
@@ -22066,8 +22865,8 @@ function renderCommandIndex() {
 `;
 }
 async function packageVersion() {
-  if ("0.0.4".length > 0) {
-    return "0.0.4";
+  if ("0.0.6".length > 0) {
+    return "0.0.6";
   }
   try {
     const packageUrl = new URL("../package.json", import_meta.url);
@@ -22240,7 +23039,38 @@ ${url2}
       resultType: "aiModelDetail",
       command: "spira ai models get",
       data: publicAiModelDoc(model),
-      nextActions: [{ label: "Create job", command: `spira ai jobs create --model-id ${model.id} --inputs-json '<json>'` }]
+      nextActions: [
+        { label: "Create job", command: `spira ai jobs create --model-id ${model.id} --inputs-json '<json>'` }
+      ]
+    });
+  }
+  if (commandKey(definition.path) === "ai jobs create") {
+    const created = await executeHttpCommand({ command: definition, args, options });
+    if (options.wait !== true || created.status === "error") return created;
+    const jobId = created.ids.jobId;
+    if (!jobId) {
+      return cliResultSchema.parse({
+        ...created,
+        status: "error",
+        error: {
+          code: "CONTRACT_MISMATCH",
+          message: "AI job creation response did not contain a jobId.",
+          retryable: false,
+          nextActions: []
+        }
+      });
+    }
+    const statusCommand = findCommandDefinition(["ai", "jobs", "status"]);
+    if (!statusCommand) throw new Error("AI job status command is not registered.");
+    output.error(`AI job ${jobId}: SUBMITTED
+`);
+    return waitForAiJob({
+      jobId,
+      timeoutMs: options.waitTimeout,
+      intervalMs: options.waitInterval,
+      onStatus: (status) => output.error(`AI job ${jobId}: ${status}
+`),
+      poll: () => executeHttpCommand({ command: statusCommand, args: { jobId }, options: {} })
     });
   }
   return executeHttpCommand({ command: definition, args, options });
@@ -22258,12 +23088,19 @@ function addLeafCommand(root, definition, output) {
   for (const option of definition.options ?? []) addOption(leaf, option);
   leaf.action(async (...values) => {
     const command = values[values.length - 1];
-    const positional = values.slice(0, -1).map((value) => String(value));
-    const args = Object.fromEntries((definition.arguments ?? []).map((argument, index) => [argument.name, positional[index] ?? ""]));
+    const positional = values.slice(0, -1).map((value) => value === void 0 ? "" : String(value));
+    const args = Object.fromEntries(
+      (definition.arguments ?? []).map((argument, index) => [argument.name, positional[index] ?? ""])
+    );
     const options = command.optsWithGlobals();
     const validationResult2 = validateCommandInput(definition, args, options);
     const result = validationResult2 ?? await executeDefinition(definition, args, options, output);
-    output.write(renderResult(result, { json: Boolean(options.json) }));
+    output.write(
+      renderResult(result, {
+        json: Boolean(options.json),
+        compactAiJobWait: commandKey(definition.path) === "ai jobs create" && options.wait === true
+      })
+    );
     if (result.status === "error") process.exitCode = 1;
   });
   parent.addCommand(leaf);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spira-lab/cli",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "Command line client for Spira.",
   "type": "module",
   "bin": {