orizu 0.2.0 → 0.3.0

package/src/index.ts

@@ -1,10 +1,22 @@
 #!/usr/bin/env node
-import { createHash, randomBytes } from 'crypto'
-import { basename, extname } from 'path'
-import { pathToFileURL } from 'url'
+import { createHash, randomBytes, randomUUID } from 'crypto'
+import { basename, delimiter, dirname, extname, isAbsolute, join, normalize } from 'path'
+import { fileURLToPath } from 'url'
 import { createServer } from 'http'
-import { readFileSync, statSync, writeFileSync } from 'fs'
-import { spawn } from 'child_process'
+import { gunzipSync, gzipSync } from 'zlib'
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  realpathSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from 'fs'
+import { spawn, spawnSync } from 'child_process'
+import { tmpdir } from 'os'
 import { createInterface } from 'readline/promises'
 import { stdin as input, stdout as output } from 'process'
 import { clearServerCredentials, getServerCredentials, saveServerCredentials } from './credentials.js'
@@ -80,6 +92,41 @@ interface DatasetSelection {
   name?: string
 }
 
+interface PromptSummary {
+  id: string
+  name: string
+  role: string
+  description?: string | null
+}
+
+interface ScorerSummary {
+  id: string
+  name: string
+  mode: string
+  metricLabel: string
+  implementationKind: string
+}
+
+interface RunnerExecContext {
+  prompt: {
+    body: string | null
+    bodyKind: string
+    providerSettings: Record<string, unknown>
+    promptId?: string
+    promptVersionId: string
+    runnerVersionId: string
+  }
+  scorer?: {
+    versionId: string
+    metricKey: string
+    higherIsBetter: boolean
+  } | null
+  rows: Array<{
+    id: string
+    row: Record<string, unknown>
+  }>
+}
+
 type DatasetUploadSourceType = 'csv' | 'json' | 'jsonl'
 
 interface DatasetUploadResponse {
@@ -153,7 +200,11 @@ function printVersion() {
 }
 
 function printUsage() {
-  printLine(`orizu global options:\n\n  --local                 Use http://localhost:3000\n  --server <url>          Use a specific server origin (for example: https://preview.example.com)\n  --version, -v           Print the orizu CLI version\n\norizu commands:\n\n  orizu login\n  orizu logout\n  orizu whoami\n  orizu teams list\n  orizu teams create [--name <name>]\n  orizu teams members list [--team <teamSlug>]\n  orizu teams members add --email <email> [--team <teamSlug>]\n  orizu teams members remove --email <email> [--team <teamSlug>]\n  orizu teams members role --team <teamSlug> --email <email> --role <admin|member>\n  orizu projects list [--team <teamSlug>]\n  orizu projects create --name <name> [--team <teamSlug>]\n  orizu apps list [--project <team/project>]\n  orizu apps create --project <team/project> --name <name> --dataset <datasetId> --file <path> --input-schema <json-path> --output-schema <json-path> [--component <name>]\n  orizu apps update [--app <appId>] [--project <team/project>] --file <path> --input-schema <json-path> --output-schema <json-path> [--component <name>]\n  orizu apps link-dataset --dataset <datasetId> [--app <appId>] [--project <team/project>] [--version <n>]\n  orizu apps detail --app <appId> [--project <team/project>] [--json]\n  orizu tasks list [--project <team/project>]\n  orizu tasks create --project <team/project> --dataset <datasetId> --app <appId> --title <title> --assignees <userIdOrEmail1,userIdOrEmail2> [--version <n>] [--instructions <text>] [--labels-per-item <n>] [--json]\n  orizu tasks assign --task <taskId> --assignees <userId1,userId2>\n  orizu tasks status --task <taskId> [--json]\n  orizu tasks pause --task <taskId>\n  orizu tasks unpause --task <taskId>\n  orizu datasets upload --file <path> [--project <team/project>] [--name <name>]\n  orizu datasets download [--dataset <datasetId|datasetUrl>] [--project <team/project>] [--format <csv|json|jsonl>] [--out <path>]\n  orizu datasets append [--dataset <datasetId|datasetUrl>] [--project <team/project>] --file <path>\n  orizu datasets edit-rows [--dataset <datasetId|datasetUrl>] [--project <team/project>] --file <path>\n  orizu datasets delete-rows [--dataset <datasetId|datasetUrl>] [--project <team/project>] --row-ids <id1,id2>\n  orizu datasets delete [--dataset <datasetId|datasetUrl>] [--project <team/project>]\n  orizu datasets lock [--dataset <datasetId|datasetUrl>] [--project <team/project>] [--reason <text>]\n  orizu datasets clone [--dataset <datasetId|datasetUrl>] [--project <team/project>] [--name <name>]\n  orizu tasks export [--task <taskId>] [--format <csv|json|jsonl>] [--out <path>]`)
+  printLine(`orizu global options:\n\n  --local                 Use http://localhost:3000\n  --server <url>          Use a specific server origin (for example: https://preview.example.com)\n  --version, -v           Print the orizu CLI version\n\norizu commands:\n\n  orizu login [--no-prompt-if-logged-in]\n  orizu logout\n  orizu whoami\n  orizu env [--project <team/project>] [--project-id <projectId>]\n  orizu log <event_type> --run-id <id> --sequence <n> --payload @event.json\n  orizu teams list\n  orizu teams create [--name <name>]\n  orizu teams members list [--team <teamSlug>]\n  orizu teams members add --email <email> [--team <teamSlug>]\n  orizu teams members remove --email <email> [--team <teamSlug>]\n  orizu teams members role --team <teamSlug> --email <email> --role <admin|member>\n  orizu projects list [--team <teamSlug>]\n  orizu projects create --name <name> [--team <teamSlug>]\n  orizu prompts list --project <team/project>\n  orizu prompts pull <prompt-id-or-name> --project <team/project> --out <dir> [--label <label> | --version <id>] [--json]\n  orizu prompts push <dir> [--runner-version <id>] [--project <team/project>] [--parent <version-id>] [--json]\n  orizu prompts labels set <prompt-name> <label> --version <version-id> [--project <team/project>] [--json]\n  orizu prompts scorers set-headline <prompt-id> --scorer-version <id> [--dataset-version <id> --split-set <id> --split <name>] [--project <team/project>] [--json]\n  orizu prompts scorers add <prompt-id> --scorer-version <id> [--dataset-version <id> --split-set <id> --split <name>] [--project <team/project>] [--json]\n  orizu scorers list --project <team/project>\n  orizu scorers register --project <team/project> --name <name> --manifest <manifest.json> [--prompt-version <id>] [--runner-version <id>] [--label <label>] [--json]\n  orizu scorers detail <scorer-id-or-name> --project <team/project> [--json]\n  orizu scorers labels set <scorer-name> <label> --version <scorer-version-id> [--project <team/project>] [--json]\n  orizu scores submit <results.jsonl|results.json> --scorer-version <id> --subject-version <prompt-version-id> [--dataset-version <id> --split-set <id> --split <name>] [--project <team/project>] [--json]\n  orizu judges list --project <team/project>\n  orizu judges pull <judge-id-or-name> --project <team/project> --out <dir> [--label <label> | --version <id>] [--json]\n  orizu judges push <dir> [--runner-version <id>] [--project <team/project>] [--parent <version-id>] [--json]\n  orizu runners push <dir> [--project <team/project>] [--name <name>] [--label <label>] [--json]\n  orizu runners exec (--prompt <prompt-version-id> | --prompt-version <id> --runner-version <id> | --scorer-version <id>) --dataset-version <id> --split-set <id-or-name> --split <name> [--runner-dir <dir>] --out <results.jsonl|results.jsonl.gz>\n  orizu optimizers push <dir> [--project <team/project>] [--name <name>] [--label <label>] [--json]\n  orizu runs submit <results.jsonl|results.jsonl.gz> --prompt-version <id> --runner-version <id> --dataset-version <id> --split-set <id> --split <name> [--project <team/project>]\n  orizu apps list [--project <team/project>]\n  orizu apps create --project <team/project> --name <name> --dataset <datasetId> --file <path> --input-schema <json-path> --output-schema <json-path> [--component <name>]\n  orizu apps update [--app <appId>] [--project <team/project>] --file <path> --input-schema <json-path> --output-schema <json-path> [--component <name>]\n  orizu apps link-dataset --dataset <datasetId> [--app <appId>] [--project <team/project>] [--version <n>]\n  orizu apps detail --app <appId> [--project <team/project>] [--json]\n  orizu tasks list [--project <team/project>]\n  orizu tasks create --project <team/project> --dataset <datasetId> --app <appId> --title <title> --assignees <userIdOrEmail1,userIdOrEmail2> [--version <n>] [--instructions <text>] [--labels-per-item <n>] [--json]\n  orizu tasks assign --task <taskId> --assignees <userId1,userId2>\n  orizu tasks status --task <taskId> [--json]\n  orizu tasks pause --task <taskId>\n  orizu tasks unpause --task <taskId>\n  orizu datasets upload --file <path> [--project <team/project>] [--name <name>]\n  orizu datasets push <path> [--project <team/project>] [--name <name>] [--json]\n  orizu datasets versions create <datasetId|dataset-name> [--project <team/project>] [--label <label>] [--json]\n  orizu datasets splits create <datasetVersionId> [--from-file <split.json>] [--json]\n  orizu datasets download [--dataset <datasetId|datasetUrl>] [--project <team/project>] [--format <csv|json|jsonl>] [--out <path>]\n  orizu datasets append [--dataset <datasetId|datasetUrl>] [--project <team/project>] --file <path>\n  orizu datasets edit-rows [--dataset <datasetId|datasetUrl>] [--project <team/project>] --file <path>\n  orizu datasets delete-rows [--dataset <datasetId|datasetUrl>] [--project <team/project>] --row-ids <id1,id2>\n  orizu datasets delete [--dataset <datasetId|datasetUrl>] [--project <team/project>]\n  orizu datasets lock [--dataset <datasetId|datasetUrl>] [--project <team/project>] [--reason <text>]\n  orizu datasets clone [--dataset <datasetId|datasetUrl>] [--project <team/project>] [--name <name>]\n  orizu tasks export [--task <taskId>] [--format <csv|json|jsonl>] [--out <path>]`)
+}
+
+function printOptimizationUsage() {
+  printLine(`\nOptimization lifecycle commands:\n\n  orizu optimizations start --project <team/project> --optimizer-version <id> --prompt-version <id[,id]> --selection-scorer <id> [--reflection-scorer <id>] [--pareto-scorer <id>] [--best-scorer <id>] --dataset-version <id> --split-set <id> [--train-split <name>] [--validation-split <name>] [--metadata <json|@file>] [--json]\n  orizu optimizations run-gepa --project <team/project> --optimizer-version-id <id> --candidate-version-id <id> --runner-version-id <id> --candidate-runner-dir <dir> --scorer-version-id <id> --scorer-runner-version-id <id> --scorer-runner-dir <dir> --dataset-version-id <id> --split-set-id <id> [--train-split train] [--val-split validation]\n  orizu optimizations pause <run-id> [--reason <text>] [--json]\n  orizu optimizations resume <run-id> [--json]\n  orizu optimizations finish <run-id> [--best-score <n>] [--best-candidate <id>] [--result-prompt-version <id>] [--metadata <json|@file>] [--json]\n  orizu optimizations fail <run-id> [--reason <text>] [--metadata <json|@file>] [--json]\n  orizu optimizations cancel <run-id> [--reason <text>] [--json]`)
 }
 
 let cliArgs = process.argv.slice(2)
@@ -288,6 +339,92 @@ export async function parseJsonResponse<T>(response: Response, context: string):
     )
   }
 }
+
+function shellQuote(value: string): string {
+  return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`
+}
+
+function getStoredAuthTokenForBaseUrl(baseUrl: string): string {
+  const credentials = getServerCredentials(baseUrl)
+  if (!credentials) {
+    throw new Error(`Not logged in for ${baseUrl}. Run \`orizu login --server ${baseUrl}\` (or \`--local\`) first.`)
+  }
+
+  return 'accessToken' in credentials ? credentials.accessToken : credentials.apiKey
+}
+
+function printPromptSummaries(items: PromptSummary[], emptyMessage: string) {
+  if (items.length === 0) {
+    printLine(emptyMessage)
+    return
+  }
+
+  const rows = items.map(item => ({
+    id: sanitizeTerminalText(item.id),
+    name: sanitizeTerminalText(item.name),
+    role: sanitizeTerminalText(item.role),
+  }))
+  const idWidth = Math.max('ID'.length, ...rows.map(row => row.id.length))
+  const nameWidth = Math.max('NAME'.length, ...rows.map(row => row.name.length))
+  const roleWidth = Math.max('ROLE'.length, ...rows.map(row => row.role.length))
+
+  printLine(`${'ID'.padEnd(idWidth)}  ${'NAME'.padEnd(nameWidth)}  ${'ROLE'.padEnd(roleWidth)}`)
+  printLine(`${'-'.repeat(idWidth)}  ${'-'.repeat(nameWidth)}  ${'-'.repeat(roleWidth)}`)
+  rows.forEach(row => {
+    printLine(`${row.id.padEnd(idWidth)}  ${row.name.padEnd(nameWidth)}  ${row.role.padEnd(roleWidth)}`)
+  })
+}
+
+function printScorerSummaries(items: ScorerSummary[]) {
+  if (items.length === 0) {
+    printLine('No scorers found.')
+    return
+  }
+
+  const rows = items.map(item => ({
+    id: sanitizeTerminalText(item.id),
+    name: sanitizeTerminalText(item.name),
+    mode: sanitizeTerminalText(item.mode),
+    metric: sanitizeTerminalText(item.metricLabel),
+    implementation: sanitizeTerminalText(item.implementationKind),
+  }))
+  const idWidth = Math.max('ID'.length, ...rows.map(row => row.id.length))
+  const nameWidth = Math.max('NAME'.length, ...rows.map(row => row.name.length))
+  const modeWidth = Math.max('MODE'.length, ...rows.map(row => row.mode.length))
+  const metricWidth = Math.max('METRIC'.length, ...rows.map(row => row.metric.length))
+
+  printLine(`${'ID'.padEnd(idWidth)}  ${'NAME'.padEnd(nameWidth)}  ${'MODE'.padEnd(modeWidth)}  ${'METRIC'.padEnd(metricWidth)}  IMPLEMENTATION`)
+  printLine(`${'-'.repeat(idWidth)}  ${'-'.repeat(nameWidth)}  ${'-'.repeat(modeWidth)}  ${'-'.repeat(metricWidth)}  ${'-'.repeat('IMPLEMENTATION'.length)}`)
+  rows.forEach(row => {
+    printLine(`${row.id.padEnd(idWidth)}  ${row.name.padEnd(nameWidth)}  ${row.mode.padEnd(modeWidth)}  ${row.metric.padEnd(metricWidth)}  ${row.implementation}`)
+  })
+}
+
+function readJsonObjectArg(valueArg: string | null, label: string): Record<string, unknown> {
+  if (!valueArg) {
+    return {}
+  }
+
+  const trimmed = valueArg.trim()
+  const raw = trimmed.startsWith('{')
+    ? trimmed
+    : readSourceFile(trimmed.startsWith('@') ? trimmed.slice(1) : trimmed)
+
+  try {
+    const parsed = JSON.parse(raw) as unknown
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      throw new Error('JSON root must be an object')
+    }
+    return parsed as Record<string, unknown>
+  } catch (error: any) {
+    throw new Error(`Invalid ${label} '${valueArg}': ${error?.message || String(error)}`)
+  }
+}
+
+function readJsonPayloadArg(pathArg: string | null): Record<string, unknown> {
+  return readJsonObjectArg(pathArg, 'event payload')
+}
+
 async function promptSelect<T>(
   title: string,
   items: T[],
@@ -392,7 +529,8 @@ async function fetchTeamMembers(teamSlug: string): Promise<TeamMember[]> {
   return data.members
 }
 
-async function resolveProjectSlug(projectArg: string | null): Promise<string> {
+async function resolveProjectSelection(projectArg: string | null): Promise<Project> {
+  projectArg = projectArg || process.env.ORIZU_PROJECT || null
   const teams = await fetchTeams()
 
   if (teams.length === 0) {
@@ -415,7 +553,7 @@ async function resolveProjectSlug(projectArg: string | null): Promise<string> {
       { forcePrompt: true }
     )
 
-    return `${project.teamSlug}/${project.slug}`
+    return project
   }
 
   const segments = projectArg.split('/')
@@ -440,7 +578,7 @@ async function resolveProjectSlug(projectArg: string | null): Promise<string> {
       project => `${project.name} (${project.teamSlug}/${project.slug})`
     )
 
-    return `${selectedProject.teamSlug}/${selectedProject.slug}`
+    return selectedProject
   }
 
   const projects = await fetchProjects(matchedTeam.slug)
@@ -454,10 +592,15 @@ async function resolveProjectSlug(projectArg: string | null): Promise<string> {
       project => `${project.name} (${project.teamSlug}/${project.slug})`
     )
 
-    return `${selectedProject.teamSlug}/${selectedProject.slug}`
+    return selectedProject
   }
 
-  return `${matchedTeam.slug}/${matchedProject.slug}`
+  return matchedProject
+}
+
+async function resolveProjectSlug(projectArg: string | null): Promise<string> {
+  const project = await resolveProjectSelection(projectArg)
+  return `${project.teamSlug}/${project.slug}`
 }
 
 async function selectTaskIdInteractively(): Promise<string> {
@@ -820,8 +963,14 @@ function renderCliAuthBrowserPage(status: 'success' | 'error'): string {
 }
 
 async function login() {
-  const baseUrl = resolveLoginBaseUrl()
+  const baseUrl = hasArg('--no-prompt-if-logged-in') ? getBaseUrl() : resolveLoginBaseUrl()
   assertSecureTokenTransport(baseUrl)
+
+  if (hasArg('--no-prompt-if-logged-in') && getServerCredentials(baseUrl)) {
+    printLine(`Already logged in to ${sanitizeTerminalText(baseUrl)}.`)
+    return
+  }
+
   const codeVerifier = createCodeVerifier()
   const codeChallenge = createCodeChallenge(codeVerifier)
   const callbackPort = resolveAuthCallbackPort()
@@ -947,19 +1096,1033 @@ async function logout() {
         : undefined,
     })
 
-    if (!response.ok) {
-      remoteLogoutError = sanitizeTerminalText(await response.text()).slice(0, 180)
+    if (!response.ok) {
+      remoteLogoutError = sanitizeTerminalText(await response.text()).slice(0, 180)
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    remoteLogoutError = sanitizeTerminalText(message).slice(0, 180)
+  }
+
+  clearServerCredentials(baseUrl)
+  if (remoteLogoutError) {
+    console.warn(`Warning: remote logout failed: ${remoteLogoutError}`)
+  }
+  printLine(`Logged out from ${sanitizeTerminalText(baseUrl)}.`)
+}
+
+async function printEnv() {
+  const baseUrl = getBaseUrl()
+  const token = getStoredAuthTokenForBaseUrl(baseUrl)
+  const projectArg = getArg('--project')
+  const project = projectArg ? await resolveProjectSelection(projectArg) : null
+  const projectId = project?.id || getArg('--project-id') || process.env.ORIZU_PROJECT_ID || ''
+  const projectSlug = project ? `${project.teamSlug}/${project.slug}` : process.env.ORIZU_PROJECT || ''
+
+  printLine(`export ORIZU_API_URL=${shellQuote(baseUrl)}`)
+  printLine(`export ORIZU_TOKEN=${shellQuote(token)}`)
+  printLine(`export ORIZU_PROJECT_ID=${shellQuote(projectId)}`)
+  if (projectSlug) {
+    printLine(`export ORIZU_PROJECT=${shellQuote(projectSlug)}`)
+  }
+}
+
+async function logOptimizationEvent() {
+  const eventType = cliArgs[1]
+  const runId = getArg('--run-id')
+  const sequenceArg = getArg('--sequence')
+  const payload = readJsonPayloadArg(getArg('--payload'))
+  const sequence = sequenceArg ? Number(sequenceArg) : Number.NaN
+
+  if (!eventType || eventType.startsWith('--') || !runId || !Number.isInteger(sequence) || sequence <= 0) {
+    throw new Error('Usage: orizu log <event_type> --run-id <id> --sequence <n> --payload @event.json')
+  }
+
+  const response = await authedFetch(`/api/cli/optimization-runs/${encodeURIComponent(runId)}/events`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      eventId: getArg('--event-id') || randomUUID(),
+      sequence,
+      eventType,
+      eventLayer: getArg('--event-layer') || 'core',
+      optimizerFamily: getArg('--optimizer-family'),
+      iteration: getArg('--iteration') ? Number(getArg('--iteration')) : undefined,
+      candidateId: getArg('--candidate-id'),
+      parentCandidateId: getArg('--parent-candidate-id'),
+      childCandidateId: getArg('--child-candidate-id'),
+      payload,
+    }),
+  })
+
+  if (!response.ok) {
+    throw new Error(`Failed to log event: ${await response.text()}`)
+  }
+
+  const data = await parseJsonResponse<{ eventId: string }>(response, 'Optimization event log')
+  printLine(`Logged event ${sanitizeTerminalText(data.eventId)}`)
+}
+
+async function listPrompts() {
+  const project = getArg('--project') || await resolveProjectSlug(null)
+  const response = await authedFetch(`/api/cli/prompts?project=${encodeURIComponent(project)}`)
+  if (!response.ok) {
+    throw new Error(`Failed to fetch prompts: ${await response.text()}`)
+  }
+
+  const data = await parseJsonResponse<{ prompts: PromptSummary[] }>(response, 'Prompts list')
+  printPromptSummaries(data.prompts, 'No prompts found.')
+}
+
+async function listJudges() {
+  const project = getArg('--project') || await resolveProjectSlug(null)
+  const response = await authedFetch(`/api/cli/judges?project=${encodeURIComponent(project)}`)
+  if (!response.ok) {
+    throw new Error(`Failed to fetch judges: ${await response.text()}`)
+  }
+
+  const data = await parseJsonResponse<{ judges: PromptSummary[] }>(response, 'Judges list')
+  printPromptSummaries(data.judges, 'No judges found.')
+}
+
+async function listScorers() {
+  const project = getArg('--project') || await resolveProjectSlug(null)
+  const response = await authedFetch(`/api/cli/scorers?project=${encodeURIComponent(project)}`)
+  if (!response.ok) {
+    throw new Error(`Failed to fetch scorers: ${await response.text()}`)
+  }
+
+  const data = await parseJsonResponse<{ scorers: ScorerSummary[] }>(response, 'Scorers list')
+  printScorerSummaries(data.scorers)
+}
+
+async function registerScorer() {
+  const project = getArg('--project') || await resolveProjectSlug(null)
+  const name = getArg('--name')
+  const manifestPath = getArg('--manifest')
+
+  if (!name || !manifestPath) {
+    throw new Error('Usage: orizu scorers register --project <team/project> --name <name> --manifest <manifest.json> [--prompt-version <id>] [--runner-version <id>] [--label <label>] [--json]')
+  }
+
+  const manifest = readJsonFile(manifestPath)
+  const response = await authedFetch(`/api/cli/scorers?project=${encodeURIComponent(project)}`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      name,
+      manifest,
+      promptVersionId: getArg('--prompt-version') || undefined,
+      runnerVersionId: getArg('--runner-version') || undefined,
+      label: getArg('--label') || undefined,
+    }),
+  })
+
+  if (!response.ok) {
+    throw new Error(`Failed to register scorer: ${await response.text()}`)
+  }
+
+  const data = await parseJsonResponse<Record<string, unknown>>(response, 'Scorer register')
+  if (hasJsonFlag()) {
+    printJson(data)
+    return
+  }
+
+  printLine(`Registered scorer ${sanitizeTerminalText(name)} (${sanitizeTerminalText(String(data.scorer_version_id || 'unknown version'))})`)
+}
+
+async function showScorerDetail() {
+  const scorerId = getPositionalArg(2)
+  const project = getArg('--project') || await resolveProjectSlug(null)
+  if (!scorerId) {
+    throw new Error('Usage: orizu scorers detail <scorer-id-or-name> --project <team/project> [--json]')
+  }
+
+  const response = await authedFetch(`/api/cli/scorers/${encodeURIComponent(scorerId)}?project=${encodeURIComponent(project)}`)
+  if (!response.ok) {
+    throw new Error(`Failed to fetch scorer: ${await response.text()}`)
+  }
+
+  const data = await parseJsonResponse<Record<string, unknown>>(response, 'Scorer detail')
+  if (hasJsonFlag()) {
+    printJson(data)
+    return
+  }
+
+  const scorer = data.scorer as Record<string, unknown> | undefined
+  printLine(`${sanitizeTerminalText(String(scorer?.name || scorerId))}`)
+  printLine(`Metric: ${sanitizeTerminalText(String(scorer?.metricLabel || 'Score'))}`)
+}
+
+async function setScorerLabel() {
+  const scorerName = getPositionalArg(3)
+  const label = getPositionalArg(4)
+  const project = getArg('--project') || await resolveProjectSlug(null)
+  const scorerVersionId = getArg('--version')
+
+  if (!scorerName || !label || !scorerVersionId) {
+    throw new Error('Usage: orizu scorers labels set <scorer-name> <label> --version <scorer-version-id> [--project <team/project>] [--json]')
+  }
+
+  const response = await authedFetch(`/api/cli/scorers/labels?project=${encodeURIComponent(project)}`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ scorerName, label, scorerVersionId }),
+  })
+
+  if (!response.ok) {
+    throw new Error(`Failed to set scorer label: ${await response.text()}`)
+  }
+
+  const data = await parseJsonResponse<Record<string, unknown>>(response, 'Scorer label set')
+  if (hasJsonFlag()) {
+    printJson(data)
+    return
+  }
+
+  printLine(`Moved ${sanitizeTerminalText(label)} to ${sanitizeTerminalText(scorerVersionId)}`)
+}
+
+async function pushRunnerArtifact(kind: 'runner' | 'optimizer') {
+  const artifactDir = getPositionalArg(2)
+  const project = getArg('--project') || await resolveProjectSlug(null)
+  const name = getArg('--name')
+  const label = getArg('--label') || undefined
+
+  if (!artifactDir) {
+    throw new Error(`Usage: orizu ${kind === 'runner' ? 'runners' : 'optimizers'} push <dir> --project <team/project> [--name <name>] [--label <label>] [--json]`)
+  }
+
+  const manifest = readManifestFile(artifactDir)
+  const artifactName = name || (typeof manifest.name === 'string' ? manifest.name : basename(expandHomePath(artifactDir)))
+  const description = typeof manifest.description === 'string' ? manifest.description : undefined
+  const { zipBase64, contentSha256 } = zipDirectoryToBase64(artifactDir)
+  const endpoint = kind === 'runner' ? 'runners' : 'optimizers'
+  const response = await authedFetch(`/api/cli/${endpoint}?project=${encodeURIComponent(project)}`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      name: artifactName,
+      description,
+      label,
+      manifest,
+      zipBase64,
+      contentSha256,
+    }),
+  })
+
+  if (!response.ok) {
+    throw new Error(`Failed to push ${kind}: ${await response.text()}`)
+  }
+
+  const data = await parseJsonResponse<Record<string, unknown>>(response, `${kind} push`)
+  if (hasJsonFlag()) {
+    printJson(data)
+    return
+  }
+
+  const versionId = kind === 'runner' ? data.runner_version_id : data.optimizer_version_id
+  printLine(`Pushed ${kind} ${sanitizeTerminalText(String(artifactName))} (${sanitizeTerminalText(String(versionId || 'unknown version'))})`)
+}
+
+async function pushPromptArtifact(kind: 'prompt' | 'judge') {
+  const promptDir = getPositionalArg(2)
+  const project = getArg('--project') || await resolveProjectSlug(null)
+  const runnerVersionArg = getArg('--runner-version')
+  const parentVersionId = getArg('--parent') || undefined
+
+  if (!promptDir) {
+    throw new Error(`Usage: orizu ${kind === 'judge' ? 'judges' : 'prompts'} push <dir> --project <team/project> [--runner-version <id>] [--parent <version-id>] [--json]`)
+  }
+
+  const promptRoot = expandHomePath(promptDir)
+  const manifest = readJsonFile(join(promptRoot, 'orizu.prompt.json'))
+  const primaryText = readPromptPrimaryText(manifest, promptRoot)
+  const sidecars = readPromptSidecars(manifest, promptRoot)
+  const runnerFromManifest = stringFromRecord(manifest, 'runner_version_id') ||
+    (isRecord(manifest.runner) ? stringFromRecord(manifest.runner, 'version_id') : undefined)
+  const runnerVersionId = runnerVersionArg || runnerFromManifest
+  if (!runnerVersionId) {
+    throw new Error(`Usage: orizu ${kind === 'judge' ? 'judges' : 'prompts'} push <dir> --project <team/project> [--runner-version <id>] [--parent <version-id>] [--json]`)
+  }
+  const baseBundle = isRecord(manifest.bundle) ? manifest.bundle : {}
+  const endpoint = kind === 'judge' ? 'judges' : 'prompts'
+  const response = await authedFetch(`/api/cli/${endpoint}?project=${encodeURIComponent(project)}`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      name: manifest.name,
+      role: kind === 'judge' && manifest.role === undefined ? 'judge_per_row' : manifest.role,
+      description: manifest.description,
+      body: primaryText.body,
+      bodyKind: primaryText.bodyKind,
+      providerSettings: manifest.provider_settings || {},
+      bundle: {
+        ...baseBundle,
+        tags: manifest.tags || [],
+        provenance: manifest.provenance || {},
+        primaryText: {
+          path: primaryText.path,
+          kind: primaryText.bodyKind,
+        },
+        sidecars,
+      },
+      runnerVersionId,
+      parentVersionId,
+      versionLabel: manifest.version_label,
+      createdBy: manifest.provenance || { kind: 'human-edit' },
+    }),
+  })
+
+  if (!response.ok) {
+    throw new Error(`Failed to push ${kind}: ${await response.text()}`)
+  }
+
+  const data = await parseJsonResponse<Record<string, unknown>>(response, `${kind} push`)
+  if (hasJsonFlag()) {
+    printJson(data)
+    return
+  }
+
+  printLine(`Pushed ${kind} ${sanitizeTerminalText(String(manifest.name || promptDir))} (${sanitizeTerminalText(String(data.prompt_version_id || 'unknown version'))})`)
+}
+
+async function pullPromptArtifact(kind: 'prompt' | 'judge') {
+  const promptRef = getPositionalArg(2)
+  const project = getArg('--project') || await resolveProjectSlug(null)
+  const outDir = getArg('--out')
+  const label = getArg('--label')
+  const version = getArg('--version')
+
+  if (!promptRef || !outDir) {
+    throw new Error(`Usage: orizu ${kind === 'judge' ? 'judges' : 'prompts'} pull <prompt-id-or-name> --project <team/project> --out <dir> [--label <label> | --version <version-id>] [--json]`)
+  }
+  if (label && version) {
+    throw new Error('Use either --label or --version, not both')
+  }
+
+  const params = new URLSearchParams({ project })
+  if (label) params.set('label', label)
+  if (version) params.set('version', version)
+
+  const endpoint = kind === 'judge' ? 'judges' : 'prompts'
+  const response = await authedFetch(`/api/cli/${endpoint}/${encodeURIComponent(promptRef)}?${params.toString()}`)
+  if (!response.ok) {
+    throw new Error(`Failed to pull ${kind}: ${await response.text()}`)
+  }
+
+  const data = await parseJsonResponse<{
+    prompt: {
+      id: string
+      name: string
+      role: string
+      description?: string | null
+    }
+    version: {
+      id: string
+      versionNumber?: number
+      versionLabel?: string | null
+      body?: string | null
+      bodyKind?: string | null
+      providerSettings?: Record<string, unknown>
+      runnerVersionId?: string | null
+      bundle?: Record<string, unknown>
+    }
+    labels?: Array<{ label: string; promptVersionId: string }>
+  }>(response, `${kind} pull`)
+
+  const targetDir = expandHomePath(outDir)
+  mkdirSync(targetDir, { recursive: true })
+
+  const bundle = isRecord(data.version.bundle) ? data.version.bundle : {}
+  const bundlePrimaryText = isRecord(bundle.primaryText)
+    ? bundle.primaryText
+    : isRecord(bundle.primary_text)
+      ? bundle.primary_text
+      : null
+  const primaryPath = safeRelativePath(
+    stringFromRecord(bundlePrimaryText || {}, 'path') || 'prompt.md',
+    'prompt.md'
+  )
+  const bodyKind = stringFromRecord(bundlePrimaryText || {}, 'kind') || data.version.bodyKind || 'text'
+
+  writeTextFileEnsuringDir(join(targetDir, primaryPath), data.version.body || '')
+
+  const exportedSidecars: Array<Record<string, unknown>> = []
+  const sidecars = Array.isArray(bundle.sidecars) ? bundle.sidecars : []
+  for (const rawSidecar of sidecars) {
+    if (!isRecord(rawSidecar)) continue
+    const sidecarPathValue = stringFromRecord(rawSidecar, 'path')
+    if (!sidecarPathValue) continue
+    const sidecarPath = safeRelativePath(sidecarPathValue, sidecarPathValue)
+    const content = typeof rawSidecar.content === 'string' ? rawSidecar.content : null
+    const contentSha256 = stringFromRecord(rawSidecar, 'contentSha256') ||
+      stringFromRecord(rawSidecar, 'content_sha256') ||
+      (content !== null ? sha256Hex(content) : undefined)
+    if (content !== null) {
+      writeTextFileEnsuringDir(join(targetDir, sidecarPath), content)
+    }
+    const { content: _ignoredContent, contentSha256: _ignoredCamel, content_sha256: _ignoredSnake, ...metadata } = rawSidecar
+    exportedSidecars.push({
+      ...metadata,
+      type: stringFromRecord(rawSidecar, 'type') || 'file',
+      path: sidecarPath,
+      ...(contentSha256 ? { content_sha256: contentSha256 } : {}),
+    })
+  }
+
+  const labels = (data.labels || [])
+    .filter(item => item.promptVersionId === data.version.id)
+    .map(item => item.label)
+
+  const manifest: Record<string, unknown> = {
+    schema_version: 'orizu.prompt.v1',
+    name: data.prompt.name,
+    role: data.prompt.role,
+    description: data.prompt.description || undefined,
+    primary_text: {
+      path: primaryPath,
+      kind: bodyKind,
+    },
+    provider_settings: data.version.providerSettings || {},
+    runner_version_id: data.version.runnerVersionId || undefined,
+    version_id: data.version.id,
+    version_number: data.version.versionNumber,
+    version_label: data.version.versionLabel || undefined,
+    labels,
+    sidecars: exportedSidecars,
+  }
+
+  writeTextFileEnsuringDir(
+    join(targetDir, 'orizu.prompt.json'),
+    `${JSON.stringify(manifest, null, 2)}\n`
+  )
+
+  if (hasJsonFlag()) {
+    printJson({
+      prompt_id: data.prompt.id,
+      prompt_version_id: data.version.id,
+      path: targetDir,
+    })
+    return
+  }
+
+  printLine(`Pulled ${kind} ${sanitizeTerminalText(data.prompt.name)} to ${sanitizeTerminalText(targetDir)}`)
+}
+
+async function setPromptLabel() {
+  const promptName = getPositionalArg(3)
+  const label = getPositionalArg(4)
+  const project = getArg('--project') || await resolveProjectSlug(null)
+  const promptVersionId = getArg('--version')
+
+  if (!promptName || !label || !promptVersionId) {
+    throw new Error('Usage: orizu prompts labels set <prompt-name> <label> --version <prompt-version-id> [--project <team/project>] [--json]')
+  }
+
+  const response = await authedFetch(`/api/cli/prompts/labels?project=${encodeURIComponent(project)}`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      promptName,
+      label,
+      promptVersionId,
+    }),
+  })
+
+  if (!response.ok) {
+    throw new Error(`Failed to set prompt label: ${await response.text()}`)
+  }
+
+  const data = await parseJsonResponse<Record<string, unknown>>(response, 'Prompt label set')
+  if (hasJsonFlag()) {
+    printJson(data)
+    return
+  }
+
+  printLine(`Moved ${sanitizeTerminalText(label)} to ${sanitizeTerminalText(promptVersionId)}`)
+}
+
+async function bindPromptScorer(role: 'headline' | 'tracked') {
+  const promptId = getPositionalArg(3)
+  const project = getArg('--project') || await resolveProjectSlug(null)
+  const scorerVersionId = getArg('--scorer-version')
+
+  if (!promptId || !scorerVersionId) {
+    throw new Error(`Usage: orizu prompts scorers ${role === 'headline' ? 'set-headline' : 'add'} <prompt-id> --scorer-version <id> [--dataset-version <id> --split-set <id> --split <name>] [--project <team/project>] [--json]`)
+  }
+
+  const response = await authedFetch(`/api/cli/prompts/scorers?project=${encodeURIComponent(project)}`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      promptId,
+      scorerVersionId,
+      role,
+      datasetVersionId: getArg('--dataset-version') || undefined,
+      splitSetId: getArg('--split-set') || undefined,
+      splitName: getArg('--split') || undefined,
+    }),
+  })
+
+  if (!response.ok) {
+    throw new Error(`Failed to bind prompt scorer: ${await response.text()}`)
+  }
+
+  const data = await parseJsonResponse<Record<string, unknown>>(response, 'Prompt scorer bind')
+  if (hasJsonFlag()) {
+    printJson(data)
+    return
+  }
+
+  printLine(`${role === 'headline' ? 'Set headline' : 'Added'} scorer ${sanitizeTerminalText(scorerVersionId)} for ${sanitizeTerminalText(promptId)}`)
+}
+
+function getPositionalArg(index: number): string | null {
+  const value = cliArgs[index]
+  return value && !value.startsWith('--') ? value : null
+}
+
+function parseRatioFlag(name: string, fallback: number): number {
+  const value = getArg(name)
+  if (!value) {
+    return fallback
+  }
+
+  const parsed = Number(value)
+  if (!Number.isFinite(parsed) || parsed < 0 || parsed > 1) {
+    throw new Error(`${name} must be a number between 0 and 1`)
+  }
+
+  return parsed
+}
+
+function parsePositiveIntegerFlag(name: string, fallback: number): number {
+  const value = getArg(name)
+  if (!value) {
+    return fallback
+  }
+
+  const parsed = Number(value)
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw new Error(`${name} must be a positive integer`)
+  }
+
+  return parsed
+}
+
+function formatPercent(value: number | null): string {
+  if (value === null || !Number.isFinite(value)) {
+    return 'unscored'
+  }
+
+  return `${(value * 100).toFixed(1)}%`
+}
+
+function looksLikeUuid(value: string): boolean {
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value)
+}
+
+async function resolveDatasetIdForProject(datasetRef: string, projectArg: string | null): Promise<string> {
+  if (looksLikeUuid(datasetRef)) {
+    return datasetRef
+  }
+
+  projectArg = projectArg || process.env.ORIZU_PROJECT || null
+  if (!projectArg) {
+    return datasetRef
+  }
+
+  const project = projectArg || await resolveProjectSlug(null)
+  const datasets = await fetchDatasets(project)
+  const matches = datasets.filter(dataset => dataset.name === datasetRef || dataset.id === datasetRef)
+
+  if (matches.length === 0) {
+    throw new Error(`Dataset '${sanitizeTerminalText(datasetRef)}' not found in ${sanitizeTerminalText(project)}`)
+  }
+
+  return matches[0].id
+}
+
+async function createDatasetVersion() {
+  const datasetId = getPositionalArg(3) || getArg('--dataset')
+  const versionLabel = getArg('--label') || getArg('--version-label') || null
+  const project = getArg('--project')
+
+  if (!datasetId) {
+    throw new Error('Usage: orizu datasets versions create <datasetId|dataset-name> [--project <team/project>] [--label <label>] [--json]')
+  }
+
+  const resolvedDatasetId = await resolveDatasetIdForProject(datasetId, project)
+  const response = await authedFetch(`/api/cli/datasets/${encodeURIComponent(resolvedDatasetId)}/versions`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ versionLabel }),
+  })
+
+  if (!response.ok) {
+    throw new Error(`Failed to create dataset version: ${await response.text()}`)
+  }
+
+  const data = await parseJsonResponse<{
+    datasetVersion: {
+      id: string
+      rowCount: number
+      artifactFormat?: string
+      artifactStoragePath?: string
+    }
+  }>(response, 'Dataset version create')
+
+  if (hasJsonFlag()) {
+    printJson({
+      dataset_version_id: data.datasetVersion.id,
+      row_count: data.datasetVersion.rowCount,
+    })
+    return
+  }
+
+  const details = [
+    `${data.datasetVersion.rowCount} rows`,
+    data.datasetVersion.artifactFormat,
+  ].filter(Boolean).join(', ')
+  printLine(
+    `Created dataset version ${sanitizeTerminalText(data.datasetVersion.id)}` +
+    (details ? ` (${sanitizeTerminalText(details)})` : '')
+  )
+}
+
+async function createDatasetSplitSet() {
+  const datasetVersionId = getPositionalArg(3) || getArg('--dataset-version')
+  const splitFile = getArg('--from-file')
+  const splitSpec = splitFile ? readJsonFile(splitFile) : null
+  const name = getArg('--name') || (typeof splitSpec?.name === 'string' ? splitSpec.name : 'default')
+  const strategy = getArg('--strategy') || (typeof splitSpec?.strategy === 'string' ? splitSpec.strategy : 'random')
+  const seed = splitSpec && (splitSpec.seed === null || typeof splitSpec.seed === 'number')
+    ? splitSpec.seed
+    : parsePositiveIntegerFlag('--seed', 1)
+  const train = parseRatioFlag('--train', 0.7)
+  const validation = parseRatioFlag('--validation', 0.2)
+  const test = parseRatioFlag('--test', 0.1)
+
+  if (!datasetVersionId) {
+    throw new Error(
+      'Usage: orizu datasets splits create <datasetVersionId> [--from-file <split.json>] [--name <name>] [--seed <n>] [--train <ratio>] [--validation <ratio>] [--test <ratio>] [--json]'
+    )
+  }
+
+  const partitions = splitSpec && Array.isArray(splitSpec.partitions) ? splitSpec.partitions : undefined
+  const metadata = splitSpec && typeof splitSpec.metadata === 'object' && splitSpec.metadata !== null
+    ? splitSpec.metadata
+    : undefined
+
+  const response = await authedFetch(`/api/cli/dataset-versions/${encodeURIComponent(datasetVersionId)}/split-sets`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      name,
+      strategy,
+      seed,
+      train,
+      validation,
+      test,
+      partitions,
+      metadata,
+    }),
+  })
+
+  if (!response.ok) {
+    throw new Error(`Failed to create dataset split set: ${await response.text()}`)
+  }
+
+  const data = await parseJsonResponse<{ splitSet: { id: string } }>(response, 'Dataset split set create')
+  if (hasJsonFlag()) {
+    printJson({ split_set_id: data.splitSet.id })
+    return
+  }
+
+  printLine(`Created split set ${sanitizeTerminalText(data.splitSet.id)}`)
+}
+
+async function submitRunResults() {
+  const resultsPath = getPositionalArg(2) || getArg('--file') || getArg('--results')
+  const project = getArg('--project') || await resolveProjectSlug(null)
+  const promptVersionId = getArg('--prompt-version')
+  const runnerVersionId = getArg('--runner-version')
+  const datasetVersionId = getArg('--dataset-version')
+  const splitSetId = getArg('--split-set')
+  const splitName = getArg('--split')
+
+  if (
+    !resultsPath ||
+    !promptVersionId ||
+    !runnerVersionId ||
+    !datasetVersionId ||
+    !splitSetId ||
+    !splitName
+  ) {
+    throw new Error(
+      'Usage: orizu runs submit <results.jsonl> --project <team/project> --prompt-version <id> --runner-version <id> --dataset-version <id> --split-set <id> --split <name> [--judge-version <id>] [--judge-runner-version <id>]'
+    )
+  }
+
+  const resultBytes = readSourceBytes(resultsPath)
+  const resultsJsonl = resultsPath.endsWith('.gz')
+    ? gunzipSync(resultBytes).toString('utf8')
+    : resultBytes.toString('utf8')
+  const response = await authedFetch(`/api/cli/runs/submit?project=${encodeURIComponent(project)}`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      promptVersionId,
+      runnerVersionId,
+      datasetVersionId,
+      splitSetId,
+      splitName,
+      judgeVersionId: getArg('--judge-version') || undefined,
+      judgeRunnerVersionId: getArg('--judge-runner-version') || undefined,
+      resultsJsonl,
+    }),
+  })
+
+  if (!response.ok) {
+    throw new Error(`Failed to submit run: ${await response.text()}`)
+  }
+
+  const data = await parseJsonResponse<{
+    run: {
+      id: string
+      aggregateScore: number | null
+      perRowResultsStoragePath: string
+    }
+  }>(response, 'Run submit')
+  printLine(
+    `Submitted run ${sanitizeTerminalText(data.run.id)} ` +
+    `(${formatPercent(data.run.aggregateScore)}) -> ` +
+    sanitizeTerminalText(data.run.perRowResultsStoragePath)
+  )
+}
+
+async function submitScoreResults() {
+  const resultsPath = getPositionalArg(2) || getArg('--file') || getArg('--results')
+  const project = getArg('--project') || await resolveProjectSlug(null)
+  const scorerVersionId = getArg('--scorer-version')
+  const subjectPromptVersionId = getArg('--subject-version') || getArg('--prompt-version')
+  const optimizationRunId = getArg('--optimization-run')
+  const candidateId = getArg('--candidate')
+
+  if (!resultsPath || !scorerVersionId || (!subjectPromptVersionId && (!optimizationRunId || !candidateId))) {
+    throw new Error('Usage: orizu scores submit <results.jsonl|results.json> --project <team/project> --scorer-version <id> (--subject-version <prompt-version-id> | --optimization-run <id> --candidate <id>) [--dataset-version <id> --split-set <id> --split <name>] [--json]')
+  }
+
+  const resultBytes = readSourceBytes(resultsPath)
+  const raw = resultsPath.endsWith('.gz')
+    ? gunzipSync(resultBytes).toString('utf8')
+    : resultBytes.toString('utf8')
+  const resultsJsonl = normalizeScoreResultsInput(resultsPath, raw)
+  const response = await authedFetch(`/api/cli/scores/submit?project=${encodeURIComponent(project)}`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      scorerVersionId,
+      subjectPromptVersionId: subjectPromptVersionId || undefined,
+      datasetVersionId: getArg('--dataset-version') || undefined,
+      splitSetId: getArg('--split-set') || undefined,
+      splitName: getArg('--split') || undefined,
+      optimizationRunId: optimizationRunId || undefined,
+      candidateId: candidateId || undefined,
+      resultsJsonl,
+    }),
+  })
+
+  if (!response.ok) {
+    throw new Error(`Failed to submit score: ${await response.text()}`)
+  }
+
+  const data = await parseJsonResponse<{
+    scoreRun: {
+      id: string
+      scoreValue: number | null
+      rowResultsStoragePath?: string | null
+    }
+  }>(response, 'Score submit')
+  if (hasJsonFlag()) {
+    printJson(data)
+    return
+  }
+
+  printLine(
+    `Submitted score ${sanitizeTerminalText(data.scoreRun.id)} ` +
+    `(${formatPercent(data.scoreRun.scoreValue)})`
+  )
+}
+
+function normalizeScoreResultsInput(sourcePath: string, raw: string): string {
+  const logicalPath = sourcePath.endsWith('.gz') ? sourcePath.slice(0, -3) : sourcePath
+  if (!logicalPath.endsWith('.json')) return raw
+
+  try {
+    const parsed = JSON.parse(raw) as unknown
+    const rows = Array.isArray(parsed) ? parsed : [parsed]
+    if (rows.some(row => !isRecord(row))) {
+      throw new Error('JSON score results must be an object or an array of objects')
+    }
+    return rows.map(row => JSON.stringify(row)).join('\n')
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    throw new Error(`Invalid score results JSON '${sourcePath}': ${message}`)
+  }
+}
+
+type OptimizationLifecycleAction = 'pause' | 'resume' | 'finish' | 'fail' | 'cancel'
+
+function parseOptionalNumberFlag(name: string): number | undefined {
+  const value = getArg(name)
+  if (!value) {
+    return undefined
+  }
+
+  const parsed = Number(value)
+  if (!Number.isFinite(parsed)) {
+    throw new Error(`${name} must be a number`)
+  }
+
+  return parsed
+}
+
+function hasObjectKeys(value: Record<string, unknown>): boolean {
+  return Object.keys(value).length > 0
+}
+
+async function startOptimizationRun() {
+  const project = getArg('--project') || await resolveProjectSlug(null)
+  const optimizerVersionId = getArg('--optimizer-version')
+  const promptVersionIds = parseCommaSeparated(
+    getArg('--prompt-version') || getArg('--prompt-versions')
+  )
+  const judgeVersionIds = parseCommaSeparated(
+    getArg('--judge-version') || getArg('--judge-versions')
+  )
+  const selectionScorer = getArg('--selection-scorer') || getArg('--scorer-version')
+  const reflectionScorer = getArg('--reflection-scorer')
+  const paretoScorers = parseCommaSeparated(getArg('--pareto-scorer') || getArg('--pareto-scorers'))
+  const bestScorers = parseCommaSeparated(getArg('--best-scorer') || getArg('--best-scorers'))
+  const datasetVersionId = getArg('--dataset-version')
+  const splitSetId = getArg('--split-set')
+  const metadata = readJsonObjectArg(getArg('--metadata'), 'optimization metadata')
+
+  if (
+    !optimizerVersionId ||
+    promptVersionIds.length === 0 ||
+    !selectionScorer ||
+    !datasetVersionId ||
+    !splitSetId
+  ) {
+    throw new Error(
+      'Usage: orizu optimizations start --project <team/project> --optimizer-version <id> --prompt-version <id[,id]> --selection-scorer <id> [--reflection-scorer <id>] [--pareto-scorer <id>] [--best-scorer <id>] --dataset-version <id> --split-set <id> [--train-split <name>] [--validation-split <name>] [--metadata <json|@file>] [--json]'
+    )
+  }
+
+  const scorers = [
+    { scorerVersionId: selectionScorer, role: 'selection' },
+    ...(reflectionScorer ? [{ scorerVersionId: reflectionScorer, role: 'reflection' }] : []),
+    ...paretoScorers.map(scorerVersionId => ({
+      scorerVersionId,
+      role: 'tracked',
+      trackedScope: 'pareto_candidates',
+    })),
+    ...bestScorers.map(scorerVersionId => ({
+      scorerVersionId,
+      role: 'tracked',
+      trackedScope: 'best_candidate',
+    })),
+  ]
+
+  const response = await authedFetch(`/api/cli/optimization-runs?project=${encodeURIComponent(project)}`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      optimizerVersionId,
+      promptVersionIds,
+      judgeVersionIds,
+      scorers,
+      datasetVersionId,
+      splitSetId,
+      trainSplitName: getArg('--train-split') || undefined,
+      validationSplitName: getArg('--validation-split') || undefined,
+      metadata,
+    }),
+  })
+
+  if (!response.ok) {
+    throw new Error(`Failed to start optimization run: ${await response.text()}`)
+  }
+
+  const data = await parseJsonResponse<{
+    optimization_run_id: string
+    optimizationRun: {
+      id: string
+      status: string
+      startedAt?: string | null
+      createdAt?: string | null
+    }
+  }>(response, 'Optimization run start')
+
+  if (hasJsonFlag()) {
+    printJson(data)
+    return
+  }
+
+  printLine(
+    `Started optimization run ${sanitizeTerminalText(data.optimization_run_id)} ` +
+    `(${sanitizeTerminalText(data.optimizationRun.status)})`
+  )
+}
+
+async function updateOptimizationRunLifecycle(action: OptimizationLifecycleAction) {
+  const runId = getPositionalArg(2) || getArg('--run-id')
+  if (!runId) {
+    throw new Error(`Usage: orizu optimizations ${action} <run-id>`)
+  }
+
+  const statusByAction: Record<OptimizationLifecycleAction, string> = {
+    pause: 'paused',
+    resume: 'running',
+    finish: 'succeeded',
+    fail: 'failed',
+    cancel: 'cancelled',
+  }
+
+  const body: Record<string, unknown> = {
+    status: statusByAction[action],
+  }
+  const metadata = readJsonObjectArg(getArg('--metadata'), 'optimization metadata')
+  const reason = getArg('--reason')
+
+  if ((action === 'pause' || action === 'cancel') && reason) {
+    metadata.reason = reason
+  }
+
+  if (action === 'fail' && reason) {
+    metadata.failure_reason = reason
+    body.failureReason = reason
+  }
+
+  if (hasObjectKeys(metadata)) {
+    body.metadata = metadata
+  }
+
+  if (action === 'finish') {
+    const bestScore = parseOptionalNumberFlag('--best-score')
+    if (bestScore !== undefined) {
+      body.bestScore = bestScore
+    }
+
+    const bestCandidateId = getArg('--best-candidate')
+    if (bestCandidateId) {
+      body.bestCandidateId = bestCandidateId
+    }
+
+    const resultPromptVersionId = getArg('--result-prompt-version')
+    if (resultPromptVersionId) {
+      body.resultPromptVersionId = resultPromptVersionId
+    }
+  }
+
+  const response = await authedFetch(`/api/cli/optimization-runs/${encodeURIComponent(runId)}`, {
+    method: 'PATCH',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+  })
+
+  if (!response.ok) {
+    throw new Error(`Failed to update optimization run: ${await response.text()}`)
+  }
+
+  const data = await parseJsonResponse<{
+    optimizationRun: {
+      id: string
+      status: string
+      startedAt?: string | null
+      finishedAt?: string | null
+      bestScore?: number | null
+      bestCandidateId?: string | null
+      resultPromptVersionId?: string | null
+      metadata?: Record<string, unknown>
+    }
+  }>(response, 'Optimization run update')
+
+  if (hasJsonFlag()) {
+    printJson(data)
+    return
+  }
+
+  const id = sanitizeTerminalText(data.optimizationRun.id)
+  if (action === 'pause') {
+    printLine(`Paused optimization run ${id}`)
+  } else if (action === 'resume') {
+    printLine(`Resumed optimization run ${id}`)
+  } else if (action === 'finish') {
+    printLine(`Finished optimization run ${id}`)
+  } else if (action === 'fail') {
+    printLine(`Marked optimization run ${id} failed`)
+  } else {
+    printLine(`Cancelled optimization run ${id}`)
+  }
+}
+
+function removeFlagWithValue(args: string[], flag: string): string[] {
+  const filtered: string[] = []
+  for (let index = 0; index < args.length; index += 1) {
+    if (args[index] === flag) {
+      index += 1
+      continue
     }
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error)
-    remoteLogoutError = sanitizeTerminalText(message).slice(0, 180)
+    filtered.push(args[index])
   }
+  return filtered
+}
 
-  clearServerCredentials(baseUrl)
-  if (remoteLogoutError) {
-    console.warn(`Warning: remote logout failed: ${remoteLogoutError}`)
+function bundledOrizuGepaPythonPath(): string | null {
+  const candidate = fileURLToPath(new URL('../../orizu-gepa-python/src', import.meta.url))
+  return existsSync(candidate) ? candidate : null
+}
+
+async function runGepaOptimization() {
+  const project = getArg('--project') || await resolveProjectSlug(null)
+  const baseUrl = getBaseUrl()
+  const token = getStoredAuthTokenForBaseUrl(baseUrl)
+  const python = getArg('--python') || process.env.PYTHON || 'python3'
+  const bundledPythonPath = bundledOrizuGepaPythonPath()
+  let forwardedArgs = removeFlagWithValue(cliArgs.slice(2), '--python')
+
+  if (!forwardedArgs.includes('--project')) {
+    forwardedArgs = ['--project', project, ...forwardedArgs]
+  }
+
+  const pythonPathEntries = [
+    bundledPythonPath,
+    process.env.PYTHONPATH,
+  ].filter((entry): entry is string => Boolean(entry))
+
+  const result = spawnSync(python, ['-m', 'orizu_gepa.cli', ...forwardedArgs], {
+    stdio: 'inherit',
+    env: {
+      ...process.env,
+      ORIZU_API_URL: baseUrl,
+      ORIZU_TOKEN: token,
+      ORIZU_PROJECT: project,
+      PYTHONPATH: pythonPathEntries.join(delimiter),
+      PYTHONUNBUFFERED: process.env.PYTHONUNBUFFERED || '1',
+    },
+  })
+
+  if (result.error) {
+    throw result.error
+  }
+
+  if (result.status !== 0) {
+    throw new Error(`orizu-gepa failed with exit code ${result.status}`)
   }
-  printLine(`Logged out from ${sanitizeTerminalText(baseUrl)}.`)
 }
 
 async function listTeams() {
@@ -1074,6 +2237,26 @@ function readSourceFile(pathArg: string): string {
   }
 }
 
+function readSourceBytes(pathArg: string): Buffer {
+  const expandedPath = expandHomePath(pathArg)
+  try {
+    return readFileSync(expandedPath)
+  } catch (error: any) {
+    if (error?.code === 'ENOENT') {
+      throw new Error(`File not found: ${expandedPath}`)
+    }
+    throw new Error(`Failed to read file '${expandedPath}': ${error?.message || String(error)}`)
+  }
+}
+
+function hasJsonFlag(): boolean {
+  return hasArg('--json')
+}
+
+function printJson(value: Record<string, unknown>) {
+  printLine(JSON.stringify(value))
+}
+
 function readJsonFile(pathArg: string): Record<string, unknown> {
   const raw = readSourceFile(pathArg)
   try {
@@ -1088,6 +2271,218 @@ function readJsonFile(pathArg: string): Record<string, unknown> {
   }
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function stringFromRecord(record: Record<string, unknown>, key: string): string | undefined {
+  const value = record[key]
+  return typeof value === 'string' && value.trim() ? value.trim() : undefined
+}
+
+function safeRelativePath(value: string, fallback: string): string {
+  const raw = value && value.trim() ? value.trim() : fallback
+  if (raw.includes('\0')) {
+    throw new Error(`Unsafe relative path: ${raw}`)
+  }
+  const normalized = normalize(raw)
+  if (isAbsolute(raw) || normalized === '..' || normalized.startsWith('../') || normalized.startsWith('..\\')) {
+    throw new Error(`Unsafe relative path: ${raw}`)
+  }
+  return normalized === '.' ? fallback : normalized
+}
+
+function sha256Hex(value: string | Buffer): string {
+  return createHash('sha256').update(value).digest('hex')
+}
+
+function readPromptPrimaryText(manifest: Record<string, unknown>, promptDir: string): {
+  body: string
+  bodyKind: string
+  path: string
+} {
+  const primaryText = isRecord(manifest.primary_text) ? manifest.primary_text : null
+  const pathValue = primaryText
+    ? stringFromRecord(primaryText, 'path')
+    : stringFromRecord(manifest, 'body_file')
+  const bodyPath = safeRelativePath(pathValue || 'prompt.md', 'prompt.md')
+  const bodyKind = primaryText
+    ? stringFromRecord(primaryText, 'kind') || stringFromRecord(manifest, 'body_kind') || 'text'
+    : stringFromRecord(manifest, 'body_kind') || 'text'
+
+  return {
+    body: readSourceFile(join(promptDir, bodyPath)),
+    bodyKind,
+    path: bodyPath,
+  }
+}
+
+function readPromptSidecars(manifest: Record<string, unknown>, promptDir: string) {
+  const sidecars = Array.isArray(manifest.sidecars) ? manifest.sidecars : []
+  return sidecars
+    .filter(isRecord)
+    .map(sidecar => {
+      const pathValue = stringFromRecord(sidecar, 'path')
+      if (!pathValue) {
+        throw new Error('Prompt sidecar entries require path')
+      }
+      const relativePath = safeRelativePath(pathValue, pathValue)
+      const content = readSourceFile(join(promptDir, relativePath))
+      const { content: _ignoredContent, content_sha256: _ignoredSnake, contentSha256: _ignoredCamel, ...metadata } = sidecar
+      return {
+        ...metadata,
+        type: stringFromRecord(sidecar, 'type') || 'file',
+        path: relativePath,
+        content,
+        contentSha256: sha256Hex(content),
+      }
+    })
+}
+
+function writeTextFileEnsuringDir(pathArg: string, content: string) {
+  mkdirSync(dirname(pathArg), { recursive: true })
+  writeFileSync(pathArg, content)
+}
+
+function shouldExcludeArtifactPath(relativePath: string): boolean {
+  const parts = relativePath.split('/')
+  return parts.some(part =>
+    part === '.git' ||
+    part === '.DS_Store' ||
+    part === '__pycache__' ||
+    part === '.pytest_cache'
+  )
+}
+
+function collectArtifactFiles(sourceDir: string, relativeDir = ''): string[] {
+  const absoluteDir = relativeDir ? join(sourceDir, relativeDir) : sourceDir
+  return readdirSync(absoluteDir, { withFileTypes: true })
+    .flatMap(entry => {
+      const relativePath = relativeDir ? `${relativeDir}/${entry.name}` : entry.name
+      if (shouldExcludeArtifactPath(relativePath)) {
+        return []
+      }
+      if (entry.isDirectory()) {
+        return collectArtifactFiles(sourceDir, relativePath)
+      }
+      return entry.isFile() ? [relativePath] : []
+    })
+    .sort((left, right) => left < right ? -1 : left > right ? 1 : 0)
+}
+
+const ZIP_GENERAL_PURPOSE_UTF8 = 0x0800
+const ZIP_DOS_TIME_2000_01_01 = 0
+const ZIP_DOS_DATE_2000_01_01 = ((2000 - 1980) << 9) | (1 << 5) | 1
+const CRC32_TABLE = Array.from({ length: 256 }, (_, index) => {
+  let value = index
+  for (let bit = 0; bit < 8; bit++) {
+    value = (value & 1) ? (0xedb88320 ^ (value >>> 1)) : (value >>> 1)
+  }
+  return value >>> 0
+})
+
+function crc32(bytes: Buffer): number {
+  let crc = 0xffffffff
+  for (const byte of bytes) {
+    crc = CRC32_TABLE[(crc ^ byte) & 0xff] ^ (crc >>> 8)
+  }
+  return (crc ^ 0xffffffff) >>> 0
+}
+
+function createStoredZip(entries: Array<{ path: string; data: Buffer }>): Buffer {
+  const localParts: Buffer[] = []
+  const centralParts: Buffer[] = []
+  let offset = 0
+
+  for (const entry of entries) {
+    const name = Buffer.from(entry.path, 'utf8')
+    const crc = crc32(entry.data)
+    const localHeader = Buffer.alloc(30)
+    localHeader.writeUInt32LE(0x04034b50, 0)
+    localHeader.writeUInt16LE(10, 4)
+    localHeader.writeUInt16LE(ZIP_GENERAL_PURPOSE_UTF8, 6)
+    localHeader.writeUInt16LE(0, 8)
+    localHeader.writeUInt16LE(ZIP_DOS_TIME_2000_01_01, 10)
+    localHeader.writeUInt16LE(ZIP_DOS_DATE_2000_01_01, 12)
+    localHeader.writeUInt32LE(crc, 14)
+    localHeader.writeUInt32LE(entry.data.length, 18)
+    localHeader.writeUInt32LE(entry.data.length, 22)
+    localHeader.writeUInt16LE(name.length, 26)
+    localHeader.writeUInt16LE(0, 28)
+
+    localParts.push(localHeader, name, entry.data)
+
+    const centralHeader = Buffer.alloc(46)
+    centralHeader.writeUInt32LE(0x02014b50, 0)
+    centralHeader.writeUInt16LE(20, 4)
+    centralHeader.writeUInt16LE(10, 6)
+    centralHeader.writeUInt16LE(ZIP_GENERAL_PURPOSE_UTF8, 8)
+    centralHeader.writeUInt16LE(0, 10)
+    centralHeader.writeUInt16LE(ZIP_DOS_TIME_2000_01_01, 12)
+    centralHeader.writeUInt16LE(ZIP_DOS_DATE_2000_01_01, 14)
+    centralHeader.writeUInt32LE(crc, 16)
+    centralHeader.writeUInt32LE(entry.data.length, 20)
+    centralHeader.writeUInt32LE(entry.data.length, 24)
+    centralHeader.writeUInt16LE(name.length, 28)
+    centralHeader.writeUInt16LE(0, 30)
+    centralHeader.writeUInt16LE(0, 32)
+    centralHeader.writeUInt16LE(0, 34)
+    centralHeader.writeUInt16LE(0, 36)
+    centralHeader.writeUInt32LE(0, 38)
+    centralHeader.writeUInt32LE(offset, 42)
+    centralParts.push(centralHeader, name)
+
+    offset += localHeader.length + name.length + entry.data.length
+  }
+
+  const centralDirectoryOffset = offset
+  const centralDirectory = Buffer.concat(centralParts)
+  const endOfCentralDirectory = Buffer.alloc(22)
+  endOfCentralDirectory.writeUInt32LE(0x06054b50, 0)
+  endOfCentralDirectory.writeUInt16LE(0, 4)
+  endOfCentralDirectory.writeUInt16LE(0, 6)
+  endOfCentralDirectory.writeUInt16LE(entries.length, 8)
+  endOfCentralDirectory.writeUInt16LE(entries.length, 10)
+  endOfCentralDirectory.writeUInt32LE(centralDirectory.length, 12)
+  endOfCentralDirectory.writeUInt32LE(centralDirectoryOffset, 16)
+  endOfCentralDirectory.writeUInt16LE(0, 20)
+
+  return Buffer.concat([...localParts, centralDirectory, endOfCentralDirectory])
+}
+
+function zipDirectoryToBase64(dirArg: string): { zipBase64: string; contentSha256: string } {
+  const sourceDir = expandHomePath(dirArg)
+  try {
+    const stats = statSync(sourceDir)
+    if (!stats.isDirectory()) {
+      throw new Error(`${sourceDir} is not a directory`)
+    }
+  } catch (error: any) {
+    if (error?.code === 'ENOENT') {
+      throw new Error(`Directory not found: ${sourceDir}`)
+    }
+    throw error
+  }
+
+  const files = collectArtifactFiles(sourceDir)
+  if (files.length === 0) {
+    throw new Error(`Directory contains no artifact files: ${sourceDir}`)
+  }
+
+  const bytes = createStoredZip(files.map(relativePath => ({
+    path: relativePath,
+    data: readFileSync(join(sourceDir, relativePath)),
+  })))
+  return {
+    zipBase64: bytes.toString('base64'),
+    contentSha256: createHash('sha256').update(bytes).digest('hex'),
+  }
+}
+
+function readManifestFile(dirArg: string): Record<string, unknown> {
+  return readJsonFile(join(expandHomePath(dirArg), 'manifest.json'))
+}
+
 async function createAppFromFile() {
   const project = getArg('--project')
   const name = getArg('--name')
@@ -1695,6 +3090,36 @@ async function uploadDataset() {
   }
 }
 
+async function pushDataset() {
+  const projectArg = getArg('--project')
+  const fileArg = getPositionalArg(2) || getArg('--file')
+  const name = getArg('--name')
+
+  if (!fileArg) {
+    throw new Error('Usage: orizu datasets push <rows.csv|rows.json|rows.jsonl> [--project <team/project>] [--name <name>] [--json]')
+  }
+
+  const file = expandHomePath(fileArg)
+  const project = await resolveProjectSlug(projectArg)
+  const datasetName = name || basename(file)
+  const { rows, sourceType } = parseDatasetFile(file)
+  const data = await createDatasetFromRows(project, datasetName, sourceType, rows)
+
+  if (hasJsonFlag()) {
+    printJson({
+      dataset_id: data.dataset.id,
+      name: data.dataset.name,
+      row_count: data.dataset.rowCount,
+    })
+    return
+  }
+
+  printLine(`Uploaded dataset ${sanitizeTerminalText(data.dataset.name)} (${sanitizeTerminalText(data.dataset.id)}) with ${data.dataset.rowCount} rows.`)
+  if (data.dataset.url) {
+    printLine(`View dataset: ${formatTerminalLink(data.dataset.url)}`)
+  }
+}
+
 function getDatasetReferenceInput(): string | null {
   const fromFlag = getArg('--dataset')
   if (fromFlag) {
@@ -2167,6 +3592,253 @@ async function downloadAnnotations() {
   printLine(`Saved ${format.toUpperCase()} export to ${sanitizeTerminalText(filename)}`)
 }
 
+function readRunnerManifest(runnerDir: string): { command: string[]; supports_body_kind?: string[] } {
+  const manifestPath = join(runnerDir, 'manifest.json')
+  const raw = readSourceFile(manifestPath)
+  const manifest = JSON.parse(raw) as {
+    command?: unknown
+    supports_body_kind?: unknown
+    supports_body_kinds?: unknown
+  }
+
+  if (!Array.isArray(manifest.command) || !manifest.command.every(item => typeof item === 'string')) {
+    throw new Error(`Runner manifest at ${manifestPath} must include command: string[]`)
+  }
+
+  const supportedBodyKinds = manifest.supports_body_kinds ?? manifest.supports_body_kind
+  if (
+    supportedBodyKinds !== undefined &&
+    (!Array.isArray(supportedBodyKinds) ||
+      !supportedBodyKinds.every(item => typeof item === 'string'))
+  ) {
+    throw new Error(`Runner manifest at ${manifestPath} has invalid supports_body_kinds`)
+  }
+
+  return {
+    command: manifest.command,
+    supports_body_kind: supportedBodyKinds as string[] | undefined,
+  }
+}
+
+const RUNNER_TIMEOUT_MS = 120_000
+const RUNNER_OUTPUT_MAX_BYTES = 2 * 1024 * 1024
+const RUNNER_ARTIFACT_MAX_BYTES = 25 * 1024 * 1024
+const RUNNER_ENV_ALLOWLIST = new Set([
+  'PATH',
+  'SystemRoot',
+  'WINDIR',
+  'HOME',
+  'TMPDIR',
+  'TEMP',
+  'TMP',
+  'LANG',
+  'LC_ALL',
+  'PYTHONPATH',
+  'NODE_PATH',
+  'ANTHROPIC_API_KEY',
+  'OPENAI_API_KEY',
+  'GEMINI_API_KEY',
+  'GOOGLE_API_KEY',
+])
+
+function runnerSubprocessEnv(inputPath: string, outputPath: string): NodeJS.ProcessEnv {
+  const env = {} as NodeJS.ProcessEnv
+  for (const key of RUNNER_ENV_ALLOWLIST) {
+    const value = process.env[key]
+    if (value !== undefined) {
+      env[key] = value
+    }
+  }
+  env.ORIZU_RUNNER_INPUT_PATH = inputPath
+  env.ORIZU_RUNNER_OUTPUT_PATH = outputPath
+  return env
+}
+
+function boundedRunnerOutput(value: string | Buffer | null | undefined): string {
+  if (!value) return ''
+  const buffer = Buffer.isBuffer(value) ? value : Buffer.from(value)
+  if (buffer.byteLength <= RUNNER_OUTPUT_MAX_BYTES) {
+    return buffer.toString('utf8')
+  }
+  return `${buffer.subarray(0, RUNNER_OUTPUT_MAX_BYTES).toString('utf8')}\n[truncated]`
+}
+
+async function materializeRunnerVersion(runnerVersionId: string): Promise<{ runnerDir: string; cleanup: () => void }> {
+  const response = await authedFetch(`/api/cli/runner-versions/${encodeURIComponent(runnerVersionId)}/download`)
+  if (!response.ok) {
+    throw new Error(`Failed to download runner version: ${await response.text()}`)
+  }
+
+  const tempDir = mkdtempSync(join(tmpdir(), 'orizu-runner-version-'))
+  const zipPath = join(tempDir, 'runner.zip')
+  const runnerDir = join(tempDir, 'runner')
+  const zipBytes = new Uint8Array(await response.arrayBuffer())
+  if (zipBytes.byteLength > RUNNER_ARTIFACT_MAX_BYTES) {
+    rmSync(tempDir, { recursive: true, force: true })
+    throw new Error(`Runner artifact exceeds ${RUNNER_ARTIFACT_MAX_BYTES} bytes`)
+  }
+  writeFileSync(zipPath, zipBytes)
+
+  const result = spawnSync('unzip', ['-q', zipPath, '-d', runnerDir], {
+    encoding: 'utf8',
+  })
+  if (result.error) {
+    rmSync(tempDir, { recursive: true, force: true })
+    throw result.error
+  }
+  if (result.status !== 0) {
+    rmSync(tempDir, { recursive: true, force: true })
+    throw new Error(`unzip failed: ${sanitizeTerminalText(result.stderr || result.stdout || '')}`)
+  }
+
+  return {
+    runnerDir,
+    cleanup: () => rmSync(tempDir, { recursive: true, force: true }),
+  }
+}
+
+async function runnersExec() {
+  const prompt = getArg('--prompt')
+  const promptVersion = getArg('--prompt-version')
+  const runnerVersion = getArg('--runner-version')
+  const scorerVersion = getArg('--scorer-version')
+  const datasetVersion = getArg('--dataset-version')
+  const splitSet = getArg('--split-set')
+  const split = getArg('--split')
+  const runnerDirArg = getArg('--runner-dir')
+  const outArg = getArg('--out')
+
+  if (
+    (!prompt && !promptVersion && !scorerVersion) ||
+    (scorerVersion && (prompt || promptVersion)) ||
+    (promptVersion && !runnerVersion) ||
+    !datasetVersion ||
+    !splitSet ||
+    !split ||
+    !outArg
+  ) {
+    throw new Error(
+      'Usage: orizu runners exec (--prompt <prompt> | --prompt-version <id> --runner-version <id> | --scorer-version <id>) --dataset-version <id> --split-set <id-or-name> --split <name> [--runner-dir <dir>] --out <results.jsonl|results.jsonl.gz>'
+    )
+  }
+
+  const query = new URLSearchParams()
+  if (scorerVersion) {
+    query.set('scorerVersion', scorerVersion)
+  } else if (promptVersion) {
+    query.set('promptVersion', promptVersion)
+  } else if (prompt) {
+    query.set('prompt', prompt)
+  }
+  if (runnerVersion) {
+    query.set('runnerVersion', runnerVersion)
+  }
+  query.set('datasetVersion', datasetVersion)
+  query.set('splitSet', splitSet)
+  query.set('split', split)
+  const contextResponse = await authedFetch(`/api/cli/runners/exec-context?${query.toString()}`)
+  if (!contextResponse.ok) {
+    throw new Error(`Failed to fetch runner execution context: ${await contextResponse.text()}`)
+  }
+
+  const context = await parseJsonResponse<RunnerExecContext>(contextResponse, 'Runner exec context')
+  const materializedRunner = runnerDirArg
+    ? { runnerDir: expandHomePath(runnerDirArg), cleanup: () => {} }
+    : await materializeRunnerVersion(runnerVersion || context.prompt.runnerVersionId)
+  const runnerDir = materializedRunner.runnerDir
+  const manifest = readRunnerManifest(runnerDir)
+
+  try {
+    if (manifest.supports_body_kind && !manifest.supports_body_kind.includes(context.prompt.bodyKind)) {
+      throw new Error(
+        `Runner does not support prompt body kind '${context.prompt.bodyKind}'. Supported kinds: ${manifest.supports_body_kind.join(', ')}`
+      )
+    }
+
+    const resultLines: string[] = []
+    for (const row of context.rows) {
+      const tempDir = mkdtempSync(join(tmpdir(), 'orizu-runner-'))
+      const inputPath = join(tempDir, 'input.json')
+      const outputPath = join(tempDir, 'output.json')
+
+      try {
+        const modelOutput = row.row.model_output ?? row.row.modelOutput ?? row.row.output ?? null
+        writeFileSync(inputPath, JSON.stringify({
+          row: row.row,
+          prompt: {
+            body: context.prompt.body,
+            body_kind: context.prompt.bodyKind,
+            provider_settings: context.prompt.providerSettings,
+          },
+          subject: scorerVersion
+            ? {
+                type: 'scorer_row',
+                row_id: row.id,
+                scorer_version_id: context.scorer?.versionId || scorerVersion,
+                prompt_version_id: context.prompt.promptVersionId,
+              }
+            : {
+                type: 'prompt_version',
+                row_id: row.id,
+                prompt_version_id: context.prompt.promptVersionId,
+              },
+          scorer: scorerVersion
+            ? {
+                version_id: context.scorer?.versionId || scorerVersion,
+                metric_key: context.scorer?.metricKey || 'score',
+                higher_is_better: context.scorer?.higherIsBetter ?? true,
+              }
+            : null,
+          model_output: modelOutput,
+          prompt_version_id: context.prompt.promptVersionId,
+          runner_version_id: context.prompt.runnerVersionId,
+          run_id: null,
+        }))
+
+        const result = spawnSync(manifest.command[0], manifest.command.slice(1), {
+          cwd: runnerDir,
+          env: runnerSubprocessEnv(inputPath, outputPath),
+          encoding: 'utf8',
+          maxBuffer: RUNNER_OUTPUT_MAX_BYTES,
+          timeout: RUNNER_TIMEOUT_MS,
+        })
+
+        if (result.error) {
+          throw result.error
+        }
+
+        if (result.status !== 0) {
+          throw new Error(
+            `Runner failed for row ${row.id} with exit code ${result.status}: ${sanitizeTerminalText(boundedRunnerOutput(result.stderr || result.stdout))}`
+          )
+        }
+
+        const runnerOutput = JSON.parse(readFileSync(outputPath, 'utf8')) as Record<string, unknown>
+        resultLines.push(JSON.stringify({
+          row_id: row.id,
+          prompt_version_id: context.prompt.promptVersionId,
+          runner_version_id: context.prompt.runnerVersionId,
+          ...(scorerVersion ? { scorer_version_id: context.scorer?.versionId || scorerVersion } : {}),
+          ...runnerOutput,
+        }))
+      } finally {
+        rmSync(tempDir, { recursive: true, force: true })
+      }
+    }
+
+    const outPath = expandHomePath(outArg)
+    const resultJsonl = `${resultLines.join('\n')}${resultLines.length > 0 ? '\n' : ''}`
+    if (outPath.endsWith('.gz')) {
+      writeFileSync(outPath, gzipSync(Buffer.from(resultJsonl, 'utf8')))
+    } else {
+      writeFileSync(outPath, resultJsonl)
+    }
+    printLine(`Wrote ${context.rows.length} runner results to ${sanitizeTerminalText(outPath)}`)
+  } finally {
+    materializedRunner.cleanup()
+  }
+}
+
 export async function main(rawArgs = process.argv.slice(2)) {
   const parsed = parseGlobalFlags(rawArgs)
   setGlobalFlags(parsed.flags)
@@ -2182,6 +3854,7 @@ export async function main(rawArgs = process.argv.slice(2)) {
 
   if (!command) {
     printUsage()
+    printOptimizationUsage()
     process.exit(1)
   }
 
@@ -2200,6 +3873,16 @@ export async function main(rawArgs = process.argv.slice(2)) {
     return
   }
 
+  if (command === 'env') {
+    await printEnv()
+    return
+  }
+
+  if (command === 'log') {
+    await logOptimizationEvent()
+    return
+  }
+
   if (command === 'teams' && subcommand === 'list') {
     await listTeams()
     return
@@ -2238,6 +3921,120 @@ export async function main(rawArgs = process.argv.slice(2)) {
     return
   }
 
+  if (command === 'prompts' && subcommand === 'list') {
+    await listPrompts()
+    return
+  }
+
+  if (command === 'prompts' && subcommand === 'pull') {
+    await pullPromptArtifact('prompt')
+    return
+  }
+
+  if (command === 'prompts' && subcommand === 'push') {
+    await pushPromptArtifact('prompt')
+    return
+  }
+
+  if (command === 'prompts' && subcommand === 'labels' && cliArgs[2] === 'set') {
+    await setPromptLabel()
+    return
+  }
+
+  if (command === 'prompts' && subcommand === 'scorers' && cliArgs[2] === 'set-headline') {
+    await bindPromptScorer('headline')
+    return
+  }
+
+  if (command === 'prompts' && subcommand === 'scorers' && cliArgs[2] === 'add') {
+    await bindPromptScorer('tracked')
+    return
+  }
+
+  if (command === 'judges' && subcommand === 'list') {
+    await listJudges()
+    return
+  }
+
+  if (command === 'judges' && subcommand === 'pull') {
+    await pullPromptArtifact('judge')
+    return
+  }
+
+  if (command === 'judges' && subcommand === 'push') {
+    await pushPromptArtifact('judge')
+    return
+  }
+
+  if (command === 'scorers' && subcommand === 'list') {
+    await listScorers()
+    return
+  }
+
+  if (command === 'scorers' && subcommand === 'register') {
+    await registerScorer()
+    return
+  }
+
+  if (command === 'scorers' && subcommand === 'detail') {
+    await showScorerDetail()
+    return
+  }
+
+  if (command === 'scorers' && subcommand === 'labels' && cliArgs[2] === 'set') {
+    await setScorerLabel()
+    return
+  }
+
+  if (command === 'runners' && subcommand === 'push') {
+    await pushRunnerArtifact('runner')
+    return
+  }
+
+  if (command === 'runners' && subcommand === 'exec') {
+    await runnersExec()
+    return
+  }
+
+  if (command === 'optimizers' && subcommand === 'push') {
+    await pushRunnerArtifact('optimizer')
+    return
+  }
+
+  if (command === 'runs' && subcommand === 'submit') {
+    await submitRunResults()
+    return
+  }
+
+  if (command === 'scores' && subcommand === 'submit') {
+    await submitScoreResults()
+    return
+  }
+
+  if (command === 'optimizations' && subcommand === 'start') {
+    await startOptimizationRun()
+    return
+  }
+
+  if (command === 'optimizations' && subcommand === 'run-gepa') {
+    await runGepaOptimization()
+    return
+  }
+
+  if (
+    command === 'optimizations' &&
+    (
+      subcommand === 'pause' ||
+      subcommand === 'resume' ||
+      subcommand === 'finish' ||
+      subcommand === 'fail' ||
+      subcommand === 'cancel'
+    )
+  ) {
+    await updateOptimizationRunLifecycle(subcommand)
+    return
+  }
+
   if (command === 'apps' && subcommand === 'list') {
     await listApps()
     return
@@ -2298,6 +4095,11 @@ export async function main(rawArgs = process.argv.slice(2)) {
     return
   }
 
+  if (command === 'datasets' && subcommand === 'push') {
+    await pushDataset()
+    return
+  }
+
   if (command === 'datasets' && subcommand === 'download') {
     await downloadDataset()
     return
@@ -2308,6 +4110,17 @@ export async function main(rawArgs = process.argv.slice(2)) {
     return
   }
 
+  const datasetsAction = cliArgs[2]
+  if (command === 'datasets' && subcommand === 'versions' && datasetsAction === 'create') {
+    await createDatasetVersion()
+    return
+  }
+
+  if (command === 'datasets' && subcommand === 'splits' && datasetsAction === 'create') {
+    await createDatasetSplitSet()
+    return
+  }
+
   if (command === 'datasets' && subcommand === 'edit-rows') {
     await editDatasetRows()
     return
@@ -2339,10 +4152,24 @@ export async function main(rawArgs = process.argv.slice(2)) {
   }
 
   printUsage()
+  printOptimizationUsage()
   process.exit(1)
 }
 
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+function isCliEntrypoint(): boolean {
+  const entry = process.argv[1]
+  if (!entry) {
+    return false
+  }
+
+  try {
+    return realpathSync(entry) === realpathSync(fileURLToPath(import.meta.url))
+  } catch {
+    return false
+  }
+}
+
+if (isCliEntrypoint()) {
   main().catch(error => {
     console.error(sanitizeTerminalText(error instanceof Error ? error.message : 'Unknown error'))
     process.exit(1)