@gizai/cli 2.1.2 → 2.2.1

package/cli/giz.mjs

@@ -0,0 +1,1129 @@
+#!/usr/bin/env node
+import { computerIdentity, managedRevision } from './computer-identity.mjs'
+import { checkForUpdate, explicitUpdate, installSource, maybeNotify } from './update.mjs'
+import { runToolchain, toolchainCommand } from './toolchain.mjs'
+import { createHash, randomBytes } from 'node:crypto'
+import { openAsBlob, statSync } from 'node:fs'
+import { mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises'
+import { createServer } from 'node:http'
+import { once } from 'node:events'
+import { createRequire } from 'node:module'
+import os from 'node:os'
+import path from 'node:path'
+import { spawn, spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import { lock } from 'proper-lockfile'
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+
+const { version: CLI_VERSION } = createRequire(import.meta.url)('../package.json')
+const DEFAULT_URL = 'https://www.giz.ai'
+const CLIENT_ID = 'giz-cli'
+const SCOPES = ['giz.read', 'giz.inference', 'giz.write', 'giz.execute', 'giz.destructive', 'offline_access']
+const BOOLEAN_OPTIONS = new Set(['help', 'json', 'no-open', 'version', 'device'])
+const configPath = path.resolve(process.env.GIZ_CONFIG ||
+  path.join(os.homedir(), '.config', 'giz', 'credentials.json'))
+
+class CliError extends Error {
+  constructor(message, hint, status) {
+    super(message)
+    this.hint = hint
+    this.status = status
+  }
+}
+
+function parse(argv) {
+  const positionals = []
+  const options = {}
+  for (let index = 0; index < argv.length; index += 1) {
+    const value = argv[index]
+    if (value === '--') {
+      positionals.push(...argv.slice(index + 1))
+      break
+    }
+    if (!value.startsWith('--')) {
+      positionals.push(value)
+      continue
+    }
+    const [rawName, inline] = value.slice(2).split(/=(.*)/s, 2)
+    const next = argv[index + 1]
+    const parsed = inline !== undefined
+      ? inline
+      : BOOLEAN_OPTIONS.has(rawName) || !next || next.startsWith('--')
+        ? true
+        : next
+    if (rawName === 'upload') {
+      options.upload = [...(Array.isArray(options.upload) ? options.upload : []), parsed]
+    } else {
+      options[rawName] = parsed
+    }
+    if (inline === undefined && parsed !== true) index += 1
+  }
+  return { positionals, options }
+}
+
+async function readConfig() {
+  try {
+    return JSON.parse(await readFile(configPath, 'utf8'))
+  } catch (error) {
+    if (error?.code === 'ENOENT') return undefined
+    throw new CliError('Could not read Giz credentials.', `Remove or repair ${configPath}.`)
+  }
+}
+
+async function updateConfig(update) {
+  await mkdir(path.dirname(configPath), { recursive: true, mode: 0o700 })
+  const release = await lock(configPath, { realpath: false, retries: { retries: 120, minTimeout: 100, maxTimeout: 500 } })
+  const temporary = `${configPath}.${randomBytes(8).toString('hex')}`
+  try {
+    const config = await update(await readConfig())
+    if (config) {
+      await writeFile(temporary, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600, flag: 'wx' })
+      await rename(temporary, configPath)
+    } else {
+      await unlink(configPath).catch((error) => { if (error.code !== 'ENOENT') throw error })
+    }
+    return config
+  } finally {
+    try { await unlink(temporary).catch((error) => { if (error.code !== 'ENOENT') throw error }) }
+    finally { await release() }
+  }
+}
+
+async function discovery(baseUrl) {
+  const response = await fetch(new URL('/.well-known/oauth-authorization-server', baseUrl), { signal: AbortSignal.timeout(30_000) })
+  if (!response.ok) {
+    throw new CliError(
+      `OAuth discovery failed: HTTP ${response.status}.`,
+      `Check ${new URL('/.well-known/oauth-authorization-server', baseUrl)}.`
+    )
+  }
+  return await response.json()
+}
+
+async function exchangeToken(baseUrl, metadata, grant, config = {}) {
+  const body = new URLSearchParams({
+    client_id: CLIENT_ID,
+    resource: new URL('/api/mcp', baseUrl).href,
+    ...grant
+  })
+  const response = await fetch(metadata.token_endpoint, {
+    method: 'POST',
+    headers: { 'content-type': 'application/x-www-form-urlencoded' },
+    body,
+    signal: AbortSignal.timeout(30_000)
+  })
+  const payload = await response.json()
+  if (!response.ok) {
+    const error = new CliError(payload.error_description || payload.error || 'OAuth token exchange failed.', 'Run: giz auth login')
+    error.oauthError = payload.error
+    throw error
+  }
+  return {
+    ...config,
+    baseUrl,
+    ...payload,
+    refresh_token: payload.refresh_token || config.refresh_token,
+    expires_at: Date.now() + Number(payload.expires_in || 3600) * 1000
+  }
+}
+
+async function credentials(baseUrl, rejectedToken) {
+  if (process.env.GIZ_TOKEN) return { access_token: process.env.GIZ_TOKEN, baseUrl }
+  const config = await readConfig()
+  if (!config?.access_token) {
+    const computer = await computerIdentity(rejectedToken)
+    if (!computer) throw new CliError('Not authenticated.', 'Run: giz auth login')
+    if (computer.baseUrl !== baseUrl) throw new CliError('A Computer identity cannot be used with another server.', 'Run giz auth login with your user account.')
+    return computer
+  }
+  if (String(config.baseUrl).replace(/\/+$/, '') !== baseUrl) {
+    throw new CliError(
+      `Credentials belong to ${config.baseUrl}.`,
+      `Run: giz auth login --base-url ${baseUrl}`
+    )
+  }
+  const expired = (value) => value.access_token === rejectedToken || Number(value.expires_at || 0) <= Date.now() + 60_000
+  if (expired(config)) {
+    return await updateConfig(async (config) => {
+      if (config?.baseUrl !== baseUrl) throw new CliError('Giz credentials changed.', 'Run: giz auth login')
+      if (expired(config)) {
+        if (!config.refresh_token) throw new CliError('Giz session expired.', 'Run: giz auth login')
+        return await exchangeToken(baseUrl, await discovery(baseUrl), {
+          grant_type: 'refresh_token', refresh_token: config.refresh_token
+        }, config)
+      }
+      return config
+    })
+  }
+  return config
+}
+
+async function authenticatedFetch(baseUrl, url, init = {}) {
+  const headers = new Headers(init.headers)
+  let auth = await credentials(baseUrl)
+  const signal = AbortSignal.timeout(25 * 60_000)
+  const send = () => {
+    headers.set('authorization', `Bearer ${auth.access_token}`)
+    // The server resolves membership and roles; the CLI only names the organization, as the web's selector does.
+    if (process.env.GIZ_ORGANIZATION) headers.set('x-giz-organization', process.env.GIZ_ORGANIZATION)
+    return fetch(url, { ...init, headers, signal: init.signal ? AbortSignal.any([init.signal, signal]) : signal })
+  }
+  let response = await send()
+  if (response.status === 401 && !process.env.GIZ_TOKEN) {
+    await response.body?.cancel()
+    auth = await credentials(baseUrl, auth.access_token)
+    response = await send()
+  }
+  return response
+}
+
+async function jsonResponse(response, baseUrl) {
+  const text = await response.text()
+  let payload
+  try { payload = JSON.parse(text) } catch {
+    if (response.ok) throw new CliError('Giz API returned invalid JSON.', `Request: ${new URL(response.url).pathname}`)
+    payload = { message: text.slice(0, 500) }
+  }
+  if (!response.ok) {
+    const message = payload?.message || payload?.error?.message || `Giz API returned HTTP ${response.status}.`
+    // Older servers have only the legacy message; classify that exact contract without hiding other 404s.
+    if (response.status === 404 && (payload?.code === 'EXTERNAL_TOOL_UNAVAILABLE' ||
+        (new URL(response.url).pathname.startsWith('/api/tools/') && /^Unknown Giz tool: /.test(message)))) {
+      const compatibility = payload?.code === 'EXTERNAL_TOOL_UNAVAILABLE'
+        ? message : 'The server version is unknown (older server).'
+      throw new CliError(
+        `This server does not support the requested command. CLI ${CLI_VERSION}. ${compatibility}`,
+        `Check the server address (${baseUrl}) and its supported version; choose a supporting server with --base-url.`,
+        response.status
+      )
+    }
+    throw new CliError(
+      message,
+      response.status === 403 && /scope/i.test(message)
+        ? (process.env.GIZ_TOKEN ? 'Provide a GIZ_TOKEN with the required scope.' : `Run: giz auth login --base-url ${baseUrl}`)
+        : `Request: ${new URL(response.url).pathname}`,
+      response.status
+    )
+  }
+  return payload
+}
+
+async function api(baseUrl, pathname, data, options = {}) {
+  const response = await authenticatedFetch(baseUrl, new URL(pathname, baseUrl), {
+    method: options.method || (data === undefined ? 'GET' : 'POST'),
+    headers: { accept: 'application/json', ...(data === undefined ? {} : { 'content-type': 'application/json' }) },
+    ...(data === undefined ? {} : { body: JSON.stringify(data) })
+  })
+  const payload = await jsonResponse(response, baseUrl)
+  if (pathname === '/api/external/me' && payload.minimumCliVersion) {
+    const current = CLI_VERSION.split('.').map(Number)
+    const minimum = String(payload.minimumCliVersion).split('.').map(Number)
+    const differing = minimum.findIndex((part, index) => part !== current[index])
+    if (differing >= 0 && current[differing] < minimum[differing]) {
+      process.stderr.write(`Warning: Giz CLI ${CLI_VERSION} is below minimum ${payload.minimumCliVersion}; update @gizai/cli.\n`)
+    }
+  }
+  return payload
+}
+
+async function uploadMedia(baseUrl, localFile) {
+  const filePath = path.resolve(String(localFile))
+  // openAsBlob reports a missing or unreadable path only as "Unable to open file as blob".
+  let isFile = false
+  try { isFile = statSync(filePath).isFile() } catch {}
+  if (!isFile) throw new CliError(`Cannot read the file to upload: ${filePath}`, 'Check the path; it is resolved from the current directory.')
+  const body = new FormData()
+  body.append('file', await openAsBlob(filePath), path.basename(filePath))
+  const response = await authenticatedFetch(baseUrl, new URL('/api/storage/media', baseUrl), {
+    method: 'POST', headers: { accept: 'application/json' }, body
+  })
+  const payload = await jsonResponse(response, baseUrl)
+  const url = String(payload?.url || '').trim()
+  const drivePath = String(payload?.path || '').trim()
+  if (!url || !drivePath) throw new CliError('Giz upload returned an incomplete file reference.', 'Try the upload again.')
+  return { ...payload, url: new URL(url, baseUrl).href }
+}
+
+async function login(baseUrl, options) {
+  const metadata = await discovery(baseUrl)
+  if (options.device === true) return await deviceLogin(baseUrl, metadata)
+  const verifier = randomBytes(48).toString('base64url')
+  const challenge = createHash('sha256').update(verifier).digest('base64url')
+  const state = randomBytes(24).toString('base64url')
+  const callback = await waitForCallback(state)
+  const authorization = new URL(metadata.authorization_endpoint)
+  for (const [name, value] of Object.entries({
+    response_type: 'code',
+    client_id: CLIENT_ID,
+    redirect_uri: callback.url,
+    scope: SCOPES.join(' '),
+    resource: new URL('/api/mcp', baseUrl).href,
+    code_challenge: challenge,
+    code_challenge_method: 'S256',
+    prompt: 'consent',
+    state
+  })) authorization.searchParams.set(name, value)
+  process.stderr.write(`Opening Giz sign-in:\n${authorization}\n`)
+  if (options.open !== 'false' && options['no-open'] !== true) openBrowser(authorization.href)
+  const code = await callback.code
+  await updateConfig(() => exchangeToken(baseUrl, metadata, {
+    grant_type: 'authorization_code', redirect_uri: callback.url, code, code_verifier: verifier
+  }))
+  return await api(baseUrl, '/api/external/me')
+}
+
+async function deviceLogin(baseUrl, metadata) {
+  if (!metadata.device_authorization_endpoint) throw new CliError('OAuth device authorization is not supported.')
+  const response = await fetch(metadata.device_authorization_endpoint, {
+    method: 'POST', headers: { 'content-type': 'application/x-www-form-urlencoded' },
+    body: new URLSearchParams({ client_id: CLIENT_ID, scope: SCOPES.join(' '), resource: new URL('/api/mcp', baseUrl).href }),
+    signal: AbortSignal.timeout(30_000)
+  })
+  const device = await response.json()
+  if (!response.ok) throw new CliError(device.error_description || device.error || 'OAuth device authorization failed.')
+  if (!device.device_code || !device.user_code || !device.verification_uri || !(Number(device.expires_in) > 0)) {
+    throw new CliError('OAuth device authorization returned an incomplete response.')
+  }
+  process.stderr.write(`Giz sign-in: ${device.verification_uri_complete || device.verification_uri}\nCode: ${device.user_code}\n`)
+  let interval = Number(device.interval ?? 5) * 1000
+  if (!Number.isFinite(interval) || interval <= 0) throw new CliError('OAuth device authorization returned an invalid interval.')
+  const deadline = Date.now() + Number(device.expires_in) * 1000
+  while (Date.now() < deadline) {
+    const remaining = deadline - Date.now()
+    await new Promise((resolve) => setTimeout(resolve, Math.min(interval, remaining)))
+    if (interval >= remaining || Date.now() >= deadline) break
+    try {
+      await updateConfig(() => exchangeToken(baseUrl, metadata, {
+        grant_type: 'urn:ietf:params:oauth:grant-type:device_code', device_code: device.device_code
+      }))
+    } catch (error) {
+      if (error.oauthError === 'slow_down') interval += 5000
+      else if (error.name === 'TimeoutError') interval *= 2
+      else if (error.oauthError !== 'authorization_pending') throw error
+      continue
+    }
+    return await api(baseUrl, '/api/external/me')
+  }
+  throw new CliError('expired_token: Giz device code expired.', 'Run: giz auth login --device')
+}
+
+async function waitForCallback(expectedState) {
+  const server = createServer()
+  server.listen(0, '127.0.0.1')
+  await once(server, 'listening')
+  const callbackUrl = `http://127.0.0.1:${server.address().port}/callback`
+  const code = new Promise((resolve, reject) => {
+    const finish = (error, value) => {
+      clearTimeout(timer)
+      server.close()
+      error ? reject(error) : resolve(value)
+    }
+    const timer = setTimeout(() => finish(new CliError('Giz sign-in timed out.', 'Run: giz auth login')), 5 * 60 * 1000)
+    server.on('request', (request, response) => {
+      const url = new URL(request.url || '/', callbackUrl)
+      if (url.pathname !== '/callback') {
+        response.writeHead(404).end('Not found')
+        return
+      }
+      if (url.searchParams.get('state') !== expectedState) {
+        response.writeHead(400).end('This sign-in link has expired. Use the link from your current giz auth login.')
+        return
+      }
+      const code = url.searchParams.get('code')
+      const error = url.searchParams.get('error') || !code
+        ? new CliError(url.searchParams.get('error_description') || url.searchParams.get('error') || 'OAuth callback did not include a code.', 'Run: giz auth login')
+        : undefined
+      response.setHeader('content-type', 'text/html; charset=utf-8')
+      response.setHeader('connection', 'close')
+      response.end(error
+        ? '<h1>Giz connection failed</h1><p>Return to the terminal for details.</p>'
+        : '<h1>Giz connected</h1><p>You can close this window and return to the terminal.</p>')
+      finish(error, code)
+    })
+    server.on('error', finish)
+  })
+  return { url: callbackUrl, code }
+}
+
+function openBrowser(url) {
+  // Not `cmd /c start`: cmd splits the URL at its first `&`, so Windows sign-in lost client_id and every later parameter.
+  const command = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'rundll32' : 'xdg-open'
+  const args = process.platform === 'win32' ? ['url.dll,FileProtocolHandler', url] : [url]
+  const child = spawn(command, args, { detached: true, stdio: 'ignore' })
+  child.on('error', () => {})
+  child.unref()
+}
+
+// --input @FILE and --input - (stdin) carry JSON too large for one process argument (Linux caps one at 128 KiB).
+async function inputText(value) {
+  if (value === '-') {
+    let text = ''
+    for await (const chunk of process.stdin) text += chunk
+    return text
+  }
+  if (typeof value === 'string' && value.startsWith('@')) {
+    try {
+      return await readFile(value.slice(1), 'utf8')
+    } catch {
+      throw new CliError(`Could not read ${value.slice(1)}.`, 'Pass --input @PATH to an existing JSON file.')
+    }
+  }
+  return value
+}
+
+function jsonInput(value) {
+  if (value === undefined || value === true) return {}
+  try {
+    const parsed = JSON.parse(value)
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error()
+    return parsed
+  } catch {
+    throw new CliError('--input must be one JSON object.', 'Example: --input \'{"prompt":"A quiet ocean"}\'')
+  }
+}
+
+function required(value, name, example) {
+  if (value) return value
+  throw new CliError(`${name} is required.`, example)
+}
+
+async function applyUploads(baseUrl, input, values = []) {
+  for (const value of values.filter((item) => item !== undefined)) {
+    const separator = String(value).indexOf('=')
+    if (separator < 1 || separator === String(value).length - 1) {
+      throw new CliError(
+        '--upload must be FIELD=LOCAL_PATH.',
+        'Example: --upload image=./first-frame.png'
+      )
+    }
+    const field = String(value).slice(0, separator).trim()
+    const localFile = String(value).slice(separator + 1).trim()
+    const stored = await uploadMedia(baseUrl, localFile)
+    const current = input[field]
+    input[field] = current === undefined ? stored.url : Array.isArray(current) ? [...current, stored.url] : [current, stored.url]
+  }
+  return input
+}
+
+// Mutations use the user's reviewed App revision; fetching it silently would bypass conflict protection.
+function appRevision(options) {
+  const raw = options['expected-revision']
+  if (raw === undefined || raw === '') {
+    throw new CliError('A revision is required.', 'Pass the revision from giz app list as --expected-revision.')
+  }
+  const revision = Number(raw)
+  if (typeof raw !== 'string' || !/^\d+$/.test(raw) || !Number.isSafeInteger(revision) || revision < 1 || revision > 9_007_199_254_740_990) {
+    throw new CliError('The revision must be a safe integer of 1 or more.', 'Check the current revision with giz app list.')
+  }
+  return revision
+}
+
+async function invoke(baseUrl, tool, input) {
+  return await api(baseUrl, `/api/tools/${encodeURIComponent(tool)}`, input)
+}
+
+function mcpTransport(baseUrl) {
+  return new StreamableHTTPClientTransport(new URL('/api/mcp', baseUrl), {
+    fetch: (url, init) => authenticatedFetch(baseUrl, url, init)
+  })
+}
+
+async function serveMcp(baseUrl) {
+  const remote = mcpTransport(baseUrl)
+  const stdio = new StdioServerTransport()
+  try {
+    await remote.start()
+    await new Promise((resolve, reject) => {
+      remote.onerror = stdio.onerror = reject
+      remote.onmessage = (message) => {
+        if (message.result?.protocolVersion) remote.setProtocolVersion(message.result.protocolVersion)
+        stdio.send(message).catch(reject)
+      }
+      stdio.onmessage = (message) => { remote.send(message).catch(reject) }
+      process.stdin.once('end', resolve)
+      stdio.start().catch(reject)
+    })
+  } finally {
+    await remote.close()
+    await stdio.close()
+  }
+}
+
+async function runCommand(baseUrl, positionals, options) {
+  const [command, subcommand, ...rest] = positionals
+  if (command === '__update-check') {
+    await checkForUpdate({ file: options.cache, url: options.registry })
+    return undefined
+  }
+  if (command === 'update' && options.help === true) return { kind: 'help', value: help('update') }
+  if (command === 'update' && !subcommand) {
+    const result = await explicitUpdate({ version: CLI_VERSION, source: installSource() })
+    return { kind: 'message', value: result.message }
+  }
+  if (options.version === true) {
+    const revision = await managedRevision()
+    return { kind: 'message', value: CLI_VERSION + (revision ? ` (region ${revision.trim()})` : '') }
+  }
+  if (!command || command === 'help' || options.help === true) {
+    // A script that asks for help on a command that does not exist must fail, not read the overview as success.
+    if (command && !gizCommand(command)) {
+      throw new CliError(`Unknown command "${command}".`, 'Run: giz --help')
+    }
+    return { kind: 'help', value: help(command) }
+  }
+  if (command === 'engine' && subcommand === 'run') {
+    if (rest[0] !== 'claude') throw new CliError('Only Claude Code is an engine connection.')
+    await api(baseUrl, '/api/external/engine/claude/authorization')
+    const { runEngine } = await import('./engine.mjs')
+    const result = await runEngine(rest[0], required(rest[1], 'INSTRUCTION', 'Run: giz engine run claude "instruction"'), options.dir,
+      event => process.stdout.write(JSON.stringify(event) + '\n'))
+    if (result.status !== 'completed') process.exitCode = 1
+    return { kind: 'result', value: result }
+  }
+  if (command === 'auth' && subcommand === 'login') {
+    return { kind: 'auth', value: await login(baseUrl, options) }
+  }
+  if (command === 'auth' && subcommand === 'status') {
+    return { kind: 'auth', value: await api(baseUrl, '/api/external/me') }
+  }
+  if (command === 'auth' && subcommand === 'logout') {
+    await updateConfig(async (config) => {
+      if (config?.refresh_token) {
+        const metadata = await discovery(config.baseUrl)
+        const response = await fetch(metadata.revocation_endpoint, {
+          method: 'POST', signal: AbortSignal.timeout(30_000),
+          headers: { 'content-type': 'application/x-www-form-urlencoded' },
+          body: new URLSearchParams({ token: config.refresh_token, token_type_hint: 'refresh_token', client_id: CLIENT_ID })
+        })
+        if (!response.ok) throw new CliError(`Giz sign-out failed: HTTP ${response.status}.`, 'Run: giz auth logout')
+      }
+    })
+    return { kind: 'message', value: 'Signed out of Giz on this device.' }
+  }
+  if (command === 'api-key' && subcommand === 'list') {
+    return { kind: 'result', value: await api(baseUrl, '/api/external/api-keys') }
+  }
+  if (command === 'api-key' && subcommand === 'create') {
+    const name = required(rest.join(' ') || options.name, 'NAME', 'Run: giz api-key create "My app"')
+    const scopes = options.scopes
+      ? String(options.scopes).split(',').map((scope) => scope.trim()).filter(Boolean)
+      : undefined
+    return {
+      kind: 'result',
+      value: await api(baseUrl, '/api/external/api-keys', {
+        name,
+        ...(scopes ? { scopes } : {}),
+        ...(options.expires ? { expiresAt: options.expires } : {})
+      })
+    }
+  }
+  if (command === 'api-key' && subcommand === 'revoke') {
+    const id = required(rest[0], 'KEY', 'Run: giz api-key revoke key_...')
+    return {
+      kind: 'result',
+      value: await api(baseUrl, `/api/external/api-keys/${encodeURIComponent(id)}`, undefined, { method: 'DELETE' })
+    }
+  }
+
+  if (command === 'credits') {
+    // Batch scripts read the balance before paid work instead of learning it from a refusal (MCP-TOOL-SCHEMA-LIMITS).
+    if (subcommand) throw new CliError(`Unknown command "credits ${subcommand}".`, 'Run: giz credits')
+    return { kind: 'result', value: await invoke(baseUrl, 'account.credits', {}) }
+  }
+  if (command === 'model' && subcommand === 'list') {
+    return {
+      kind: 'models',
+      value: await invoke(baseUrl, 'model.list', {
+        ...(options.type ? { type: options.type } : {}),
+        ...(options.search ? { search: options.search } : {})
+      })
+    }
+  }
+  if (command === 'model' && subcommand === 'get') {
+    const model = required(rest[0] || options.model, 'MODEL', 'Run: giz model get MODEL')
+    return { kind: 'model', value: await invoke(baseUrl, 'model.get', { model }) }
+  }
+  if (command === 'model' && subcommand === 'run') {
+    const model = required(rest[0] || options.model, 'MODEL', 'Run: giz model run MODEL --input JSON')
+    const input = await applyUploads(baseUrl, jsonInput(options.input), options.upload)
+    return { kind: 'job', value: await invoke(baseUrl, 'model.run', { model, input }) }
+  }
+  if (command === 'models') {
+    throw new CliError('Unknown command "models".', 'Did you mean: giz model list')
+  }
+  if (command === 'chat') {
+    const model = required(options.model || subcommand, 'MODEL', 'Run: giz chat MODEL "your prompt"')
+    const input = jsonInput(options.input)
+    const prompt = rest.join(' ').trim()
+    const messages = input.messages || (prompt ? [{ role: 'user', content: prompt }] : undefined)
+    required(messages, 'MESSAGES', 'Pass a prompt or --input \'{"messages":[...]}\'')
+    return {
+      kind: 'result',
+      value: await api(baseUrl, '/v1/chat/completions', {
+        ...input,
+        model,
+        messages,
+        stream: false
+      })
+    }
+  }
+
+  if (command === 'generate' && ['image', 'video', 'audio', 'music', 'talking-head'].includes(subcommand)) {
+    const tool = {
+      image: 'generateImage',
+      video: 'generateVideo',
+      audio: 'generateAudio',
+      music: 'generateMusic',
+      'talking-head': 'generateTalkingHead'
+    }[subcommand]
+    const uploads = [
+      ...(Array.isArray(options.upload) ? options.upload : []),
+      ...(options.image ? [`references=${options.image}`] : []),
+      ...(options.audio ? [`audio=${options.audio}`] : [])
+    ]
+    const input = await applyUploads(baseUrl, {
+      ...jsonInput(options.input),
+      ...(rest.length ? { prompt: rest.join(' ') } : {}),
+      ...(options.model ? { model: options.model } : {})
+    }, uploads)
+    return { kind: 'job', value: await invoke(baseUrl, tool, input) }
+  }
+
+  if (command === 'job' && subcommand === 'list') {
+    return { kind: 'jobs', value: await invoke(baseUrl, 'job.list', options.limit ? { limit: Number(options.limit) } : {}) }
+  }
+  if (command === 'job' && subcommand === 'get') {
+    const job = required(rest[0], 'JOB', 'Run: giz job get JOB')
+    return { kind: 'job', value: await invoke(baseUrl, 'job.get', { job }) }
+  }
+  if (command === 'job' && subcommand === 'cancel') {
+    const job = required(rest[0], 'JOB', 'Run: giz job cancel JOB')
+    return { kind: 'job', value: await invoke(baseUrl, 'job.cancel', { job }) }
+  }
+  if (command === 'job' && subcommand === 'wait') {
+    const id = required(rest[0], 'JOB', 'Run: giz job wait JOB')
+    while (true) {
+      const job = await invoke(baseUrl, 'job.get', { job: id })
+      if (['completed', 'failed', 'cancelled'].includes(job.status)) return { kind: 'job', value: job, exitCode: job.status === 'completed' ? 0 : 1 }
+      if (process.stderr.isTTY) process.stderr.write(`\r${job.id}  ${job.status}  ${job.message || ''}`.slice(0, 120))
+      await new Promise((resolve) => setTimeout(resolve, 1000))
+    }
+  }
+
+  if (command === 'drive') {
+    const mappings = {
+      list: () => ['drive.list', { path: rest[0] || '' }],
+      search: () => ['drive.search', { query: required(rest.join(' '), 'QUERY', 'Run: giz drive search QUERY') }],
+      read: () => ['drive.readFile', { path: required(rest[0], 'PATH', 'Run: giz drive read PATH') }],
+      mkdir: () => ['drive.makeDirectory', { path: required(rest[0], 'PATH', 'Run: giz drive mkdir PATH') }],
+      move: () => ['drive.movePath', {
+        from: required(rest[0], 'FROM', 'Run: giz drive move FROM TO'),
+        to: required(rest[1], 'TO', 'Run: giz drive move FROM TO')
+      }],
+      delete: () => ['drive.deletePath', { path: required(rest[0], 'PATH', 'Run: giz drive delete PATH') }]
+    }
+    if (subcommand === 'write') {
+      const drivePath = required(rest[0], 'PATH', 'Run: giz drive write PATH --content TEXT')
+      let content = options.content
+      let encoding = 'utf8'
+      if (options.file) {
+        const buffer = await readFile(String(options.file))
+        content = buffer.toString('base64')
+        encoding = 'base64'
+      }
+      required(content, 'CONTENT', 'Use --content TEXT or --file LOCAL_PATH.')
+      return {
+        kind: 'result',
+        value: await invoke(baseUrl, 'drive.writeFile', {
+          path: drivePath,
+          content: String(content),
+          encoding,
+          ...(options.computer ? { computer: options.computer } : {})
+        })
+      }
+    }
+    const mapping = mappings[subcommand === 'ls' ? 'list' : subcommand]
+    if (!mapping) throw new CliError(`Unknown drive command "${subcommand || ''}".`, 'Run: giz drive --help')
+    const [tool, input] = mapping()
+    return {
+      kind: 'result',
+      value: await invoke(baseUrl, tool, { ...input, ...(options.computer ? { computer: options.computer } : {}) })
+    }
+  }
+
+  if (command === 'table' && subcommand === 'list') {
+    return { kind: 'result', value: await invoke(baseUrl, 'workspace.objects', {}) }
+  }
+
+  if (command === 'table' && subcommand === 'get') {
+    const object = required(rest[0], 'TABLE', 'Run: giz table get task')
+    return { kind: 'result', value: await invoke(baseUrl, 'workspace.objects', { object }) }
+  }
+
+  if (command === 'table' && subcommand === 'action') {
+    const view = required(rest[0], 'TABLE', 'Run: giz table action TABLE ACTION [--id ID] --input JSON')
+    const action = required(rest[1], 'ACTION', 'Run: giz table get TABLE to see its actions')
+    // Namespaced table tools use their canonical external contract and table ownership checks.
+    if (action.startsWith('table.')) {
+      if (options.id !== undefined) throw new CliError('Table tools do not take --id.', 'Put row IDs in --input.')
+      return { kind: 'result', value: await invoke(baseUrl, action, { ...jsonInput(options.input), table: view }) }
+    }
+    const id = options.id === undefined ? undefined : String(options.id).includes(',') ? String(options.id).split(',') : String(options.id)
+    return {
+      kind: 'result',
+      value: await invoke(baseUrl, 'workspace.executeAction', { view, action, ...(id === undefined ? {} : { dataId: id }), data: jsonInput(options.input) })
+    }
+  }
+
+  if (command === 'table' && ['read', 'write'].includes(subcommand)) {
+    const table = required(rest[0], 'TABLE', `Run: giz table ${subcommand} TABLE_PATH --input JSON`)
+    return {
+      kind: 'result',
+      value: await invoke(baseUrl, subcommand === 'read' ? 'table.readRows' : 'table.writeRows', {
+        ...jsonInput(options.input),
+        table,
+        ...(options.computer ? { computer: options.computer } : {})
+      })
+    }
+  }
+
+  if (command === 'upload') {
+    const localFile = required(subcommand, 'LOCAL_PATH', 'Run: giz upload ./reference.png')
+    return { kind: 'result', value: await uploadMedia(baseUrl, localFile) }
+  }
+
+  if (command === 'computer') {
+    if (subcommand === 'list') return { kind: 'computers', value: await invoke(baseUrl, 'computer.list', {}) }
+    const computer = options.computer || (subcommand === 'exec' ? undefined : rest[0])
+    if (subcommand === 'get') return { kind: 'result', value: await invoke(baseUrl, 'computer.get', computer ? { computer } : {}) }
+    if (subcommand === 'start' || subcommand === 'stop') {
+      return {
+        kind: 'result',
+        value: await invoke(baseUrl, `computer.${subcommand}`, computer ? { computer } : {})
+      }
+    }
+    if (subcommand === 'exec') {
+      if (!rest.length) throw new CliError('COMMAND is required.', 'Run: giz computer exec -- ls -la')
+      const stdin = options['stdin-file'] ? await readFile(String(options['stdin-file']), 'utf8') : options.stdin
+      const value = await invoke(baseUrl, 'computer.exec', {
+        command: rest,
+        ...(stdin !== undefined ? { stdin: String(stdin) } : {}),
+        ...(options['deadline-ms'] !== undefined ? { deadlineMs: Number(options['deadline-ms']) } : {}),
+        ...(options.cwd ? { cwd: options.cwd } : {}),
+        ...(computer ? { computer } : {})
+      })
+      return { kind: 'result', value, exitCode: value.exitCode }
+    }
+    throw new CliError(`Unknown computer command "${subcommand || ''}".`, 'Run: giz computer --help')
+  }
+
+  if (command === 'app') {
+    const computer = options.computer ? { computer: options.computer } : {}
+    if (subcommand === 'list') {
+      return { kind: 'result', value: await invoke(baseUrl, 'app.list', computer) }
+    }
+    if (subcommand === 'save' || subcommand === 'create') {
+      const input = jsonInput(options.input)
+      return { kind: 'result', value: await invoke(baseUrl, 'app.save', { ...input, ...computer }) }
+    }
+    if (subcommand === 'run') {
+      const id = required(rest[0], 'APP_ID', 'Run: giz app run APP_ID --expected-revision REVISION')
+      return { kind: 'result', value: await invoke(baseUrl, 'app.run', { ...computer, id, expectedRevision: appRevision(options) }) }
+    }
+    if (subcommand === 'publish') {
+      const id = required(rest[0], 'APP_ID', 'Run: giz app publish APP_ID private|workspace|public')
+      const visibility = required(rest[1] || options.visibility, 'VISIBILITY', 'Run: giz app publish APP_ID private|workspace|public')
+      return { kind: 'result', value: await invoke(baseUrl, 'app.publish', { ...computer, id, visibility, expectedRevision: appRevision(options) }) }
+    }
+    if (subcommand === 'open') {
+      const id = required(rest[0], 'APP_ID', 'Run: giz app open APP_ID')
+      return { kind: 'result', value: await invoke(baseUrl, 'app.open', { ...computer, id }) }
+    }
+    if (subcommand === 'delete') {
+      const id = required(rest[0], 'APP_ID', 'Run: giz app delete APP_ID')
+      return { kind: 'result', value: await invoke(baseUrl, 'app.delete', { ...computer, id, expectedRevision: appRevision(options) }) }
+    }
+    throw new CliError(`Unknown app command "${subcommand || ''}".`, 'Run: giz app --help')
+  }
+
+  if (command === 'connection') {
+    if (subcommand === 'list') {
+      return {
+        kind: 'result',
+        value: await invoke(baseUrl, 'capability.status', {
+          ...(options.computer ? { computer: options.computer } : {})
+        })
+      }
+    }
+    throw new CliError(`Unknown connection command "${subcommand || ''}".`, 'Run: giz connection --help')
+  }
+
+  if (command === 'plugin') {
+    const computer = options.computer ? { computer: options.computer } : {}
+    if (subcommand === 'list' || subcommand === 'search') {
+      const query = subcommand === 'search'
+        ? required(rest.join(' '), 'QUERY', 'Run: giz plugin search QUERY [--origin catalog|skill|mcp]')
+        : undefined
+      return {
+        kind: 'result',
+        value: await invoke(baseUrl, 'plugin.catalog', {
+          ...(query ? { query } : { origin: 'installed' }),
+          ...(query && options.origin ? { origin: options.origin } : {}),
+          ...(options.limit ? { limit: Number(options.limit) } : {}),
+          ...computer
+        })
+      }
+    }
+    if (subcommand === 'inspect') {
+      const drivePath = required(rest[0], 'PATH', 'Run: giz plugin inspect DRIVE_PATH')
+      return { kind: 'result', value: await invoke(baseUrl, 'plugin.catalog', { path: drivePath, ...computer }) }
+    }
+    if (subcommand === 'install') {
+      const source = options.path
+        ? { path: options.path }
+        : { id: required(rest[0], 'ID', 'Run: giz plugin install ID --query QUERY, or giz plugin install --path DRIVE_PATH') }
+      return {
+        kind: 'result',
+        value: await invoke(baseUrl, 'plugin.install', {
+          ...source,
+          ...(options.query ? { query: options.query } : {}),
+          ...computer
+        })
+      }
+    }
+    if (['update', 'enable', 'disable', 'remove'].includes(subcommand)) {
+      const name = required(rest[0], 'NAME', `Run: giz plugin ${subcommand} NAME`)
+      return { kind: 'result', value: await invoke(baseUrl, 'plugin.manage', { operation: subcommand, name, ...computer }) }
+    }
+    if (subcommand === 'publish') {
+      const drivePath = required(rest[0], 'PATH', 'Run: giz plugin publish DRIVE_PATH --visibility organization|public')
+      const visibility = required(options.visibility, 'VISIBILITY', 'Add --visibility organization|public.')
+      return {
+        kind: 'result',
+        value: await invoke(baseUrl, 'plugin.manage', {
+          operation: 'publish',
+          path: drivePath,
+          visibility,
+          ...(options.organization ? { organizationId: options.organization } : {}),
+          ...computer
+        })
+      }
+    }
+    if (subcommand === 'unpublish') {
+      const releaseId = required(rest[0], 'RELEASE', 'Run: giz plugin unpublish RELEASE')
+      return { kind: 'result', value: await invoke(baseUrl, 'plugin.manage', { operation: 'unpublish', releaseId }) }
+    }
+    throw new CliError(`Unknown plugin command "${subcommand || ''}".`, 'Run: giz plugin --help')
+  }
+
+  if (command === 'agent') {
+    if (subcommand === 'start') {
+      return {
+        kind: 'result',
+        value: await invoke(baseUrl, 'agent.start', {
+          ...jsonInput(options.input),
+          ...(options.computer ? { computer: options.computer } : {})
+        })
+      }
+    }
+    if (subcommand === 'status' || subcommand === 'cancel') {
+      const turnId = required(rest[0], 'TURN', `Run: giz agent ${subcommand} TURN`)
+      return {
+        kind: 'result',
+        value: await invoke(baseUrl, `agent.${subcommand}`, {
+          turnId,
+          ...(subcommand === 'status' && options.wait ? { wait: true } : {})
+        })
+      }
+    }
+    throw new CliError(`Unknown agent command "${subcommand || ''}".`, 'Run: giz agent --help')
+  }
+
+  if (command === 'invoke') {
+    const tool = required(subcommand, 'TOOL', 'Run: giz invoke TOOL --input JSON')
+    return { kind: 'result', value: await invoke(baseUrl, tool, jsonInput(options.input)) }
+  }
+
+  if (command === 'mcp' && subcommand === 'url') {
+    return { kind: 'message', value: new URL('/api/mcp', baseUrl).href }
+  }
+  if (command === 'mcp' && subcommand === 'serve') {
+    await serveMcp(baseUrl)
+    return
+  }
+  if (command === 'mcp' && subcommand === 'check') {
+    const client = new Client({ name: 'giz-cli', version: CLI_VERSION })
+    try {
+      await client.connect(mcpTransport(baseUrl))
+      const { tools } = await client.listTools()
+      if (!tools.length) throw new CliError('Giz MCP returned zero tools.', 'Check your Giz connection and scopes.')
+      return { kind: 'result', value: { server: client.getServerVersion(), tools: tools.map((tool) => tool.name) } }
+    } finally { await client.close() }
+  }
+  if (command === 'mcp' && subcommand === 'add') {
+    const client = required(rest[0], 'CLIENT', 'Run: giz mcp add codex|claude')
+    if (!['codex', 'claude'].includes(client)) throw new CliError(`Unsupported MCP client "${client}".`, 'Supported clients: codex, claude')
+    const transport = options.transport || 'stdio'
+    if (!['stdio', 'http'].includes(transport)) throw new CliError('MCP transport must be stdio or http.')
+    const endpoint = new URL('/api/mcp', baseUrl).href
+    const target = transport === 'stdio'
+      ? ['--env', `GIZ_CONFIG=${configPath}`, '--', process.execPath, fileURLToPath(import.meta.url), 'mcp', 'serve', '--base-url', baseUrl]
+      : client === 'codex' ? ['--url', endpoint, '--oauth-resource', endpoint] : [endpoint]
+    runExternal(client, ['mcp', 'add', ...(client === 'claude' ? ['--scope', 'user', '--transport', transport] : []), 'giz', ...target],
+      `Install ${client === 'codex' ? 'Codex: npm install -g @openai/codex' : 'Claude Code: npm install -g @anthropic-ai/claude-code'}`, transport === 'http')
+    return { kind: 'message', value: `Giz was added to ${client} (${transport}). ${transport === 'stdio'
+      ? 'Run giz auth login, then giz mcp check --json before starting a headless session.'
+      : client === 'claude' ? 'Open Claude Code and run /mcp to sign in.' : 'Complete the browser approval opened by Codex.'}` }
+  }
+
+  if (command === 'skill' && subcommand === 'install') {
+    const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'skills')
+    runExternal('npx', ['--yes', 'skills', 'add', root, '--skill', '*', '--agent', 'universal', '--copy', '-y'], 'Install Node.js 20 or newer first.')
+    return { kind: 'message', value: 'Giz Skill installed for available AI agents.' }
+  }
+
+  throw new CliError(`Unknown command "${[command, subcommand].filter(Boolean).join(' ')}".`, 'Run: giz --help')
+}
+
+function runExternal(command, args, hint, interactive = false) {
+  const result = spawnSync(command, args, { encoding: 'utf8', stdio: interactive ? ['inherit', 2, 2] : ['inherit', 'pipe', 'pipe'] })
+  if (result.error?.code === 'ENOENT') throw new CliError(`${command} is not installed.`, hint)
+  if (result.error || result.status !== 0) throw new CliError(
+    `${command} failed (${result.error?.code || result.signal || result.status}): ${(result.stderr || result.stdout || result.error?.message || '').trim()}`
+  )
+  if (result.stderr || result.stdout) process.stderr.write(result.stderr + result.stdout)
+}
+
+function print(kind, value, json, output = process.stdout) {
+  if (json) {
+    output.write(`${JSON.stringify(value, null, 2)}\n`)
+    return
+  }
+  if (kind === 'help' || kind === 'message') {
+    output.write(`${value}\n`)
+    return
+  }
+  if (kind === 'auth' && value.identity?.type === 'computer') {
+    output.write(`Signed in as a Computer identity (owner ${value.email || value.name})\n`)
+    return
+  }
+  if (kind === 'models') {
+    const rows = value.models || []
+    for (const model of rows) output.write(`${model.id}\t${model.type}\t${model.provider || '-'}\t${model.label}\n`)
+    output.write(`\n${rows.length} models\n`)
+    return
+  }
+  if (kind === 'jobs') {
+    for (const job of value.jobs || []) output.write(`${job.id}\t${job.status}\t${job.tool}\t${job.createdAt}\n`)
+    return
+  }
+  if (kind === 'computers') {
+    for (const computer of value.computers || []) {
+      output.write(`${computer.id}\t${computer.status || '-'}\t${computer.isDefault ? 'default' : '-'}\t${computer.name}\n`)
+    }
+    return
+  }
+  if (kind === 'job') {
+    output.write(`${value.id}  ${value.status}\n`)
+    if (value.message) output.write(`${value.message}\n`)
+    if (value.error) output.write(`Error: ${value.error}\n`)
+    if (value.result) output.write(`${JSON.stringify(value.result, null, 2)}\n`)
+    if (!['completed', 'failed', 'cancelled'].includes(value.status)) {
+      output.write(`Run: giz job wait ${value.id}\n`)
+    }
+    return
+  }
+  output.write(`${JSON.stringify(value, null, 2)}\n`)
+}
+
+function help(command) {
+  if (command === 'engine') return `Usage
+  giz engine run claude "instruction" [--dir path]
+
+Runs the official Claude Code in an isolated worktree. Connect Claude Code in Giz first.
+Progress and the final diff, files and summary are returned. Interrupting stops the engine.`
+  if (command === 'api-key') return `Usage
+  giz api-key list
+  giz api-key create "My app" [--scopes giz.inference,giz.read] [--expires ISO_TIMESTAMP]
+  giz api-key revoke KEY_ID
+
+The secret is shown only when the key is created.`
+  if (command === 'credits') return `Usage
+  giz credits
+
+Prints your remaining credit (purchased and plan), when plan credit resets, and this month's spend and charges.
+In a workspace it prints the workspace's monthly budget. Read it before paid batch work.`
+  if (command === 'chat') return `Usage
+  giz chat MODEL "your prompt"
+  giz chat MODEL --input '{"messages":[{"role":"user","content":"Hello"}]}'`
+  if (command === 'model') return `Usage
+  giz model list [--type TYPE] [--search TEXT]
+  giz model get MODEL
+  giz model run MODEL --input JSON [--upload FIELD=LOCAL_PATH]
+
+Run model get first. Its live input schema is the source of truth. Repeat --upload for multiple media inputs.
+model run returns a job immediately. Retrieve the result with giz job wait JOB_ID, or poll with giz job get JOB_ID.
+For speech-to-text, use model run with the audio field returned by model get. Callback/webhook delivery is not supported.`
+  if (command === 'generate') return `Usage
+  giz generate image|video|music|talking-head "PROMPT" [--model MODEL]
+  giz generate audio --input '{"purpose":"speech","script":"Hello"}' [--model MODEL]
+  giz generate audio --input '{"purpose":"sound","prompt":"Rain","duration":5}'
+
+Options
+  --image LOCAL_PATH       Upload a visual reference
+  --audio LOCAL_PATH       Upload speech audio
+  --upload FIELD=PATH      Upload into an exact tool field
+  --input JSON             Input matching the tool schema (@FILE reads a file, - reads stdin)
+
+For model-specific audio options, inspect giz model get MODEL and pass supported fields in settings (for example settings.speed), not at the top level.
+Generation returns a job immediately; use giz job wait JOB_ID for its result.`
+  if (command === 'drive') return `Usage
+  giz drive ls [PATH]  (list alias)
+  giz drive search QUERY
+  giz drive read PATH
+  giz drive write PATH --content TEXT
+  giz drive write PATH --file LOCAL_PATH
+  giz drive mkdir PATH
+  giz drive move FROM TO
+  giz drive delete PATH`
+  if (command === 'table') return `Usage
+  giz table list
+  giz table get TABLE
+  giz table read TABLE [--input JSON] [--computer COMPUTER]
+  giz table write TABLE --input JSON [--computer COMPUTER]
+  giz table action TABLE ACTION [--id ID[,ID...]] --input JSON
+
+TABLE is a table's Drive path (for example Sales/Customers.view.ts) or a business object name from giz table list
+(for example task, issue, requirement). giz table get shows its fields, the row changes it accepts (writes) and its
+actions. Namespaced table actions (such as table.updateSchema) use the table tool contract; an object without a write changes only through its actions. Use --org to work in an organization.
+read input:  {"select":["name"],"filters":[{"field":"status","operator":"eq","value":"open"}],"limit":50}
+write input: {"create":[{"name":"Acme"}],"update":[{"id":"ROW_ID","status":"done"}],"remove":["ROW_ID"]}
+One write is one change people can undo in the table. At most 200 rows per write.`
+  if (command === 'computer') return `Usage
+  giz computer list
+  giz computer get|start|stop [COMPUTER]
+  giz computer exec [--computer COMPUTER] [--cwd PATH] [--deadline-ms MS] [--stdin TEXT|--stdin-file PATH] -- COMMAND [ARGS...]`
+  if (command === 'app') return `Usage
+  giz app list [--computer COMPUTER]
+  giz app create|save [--computer COMPUTER] --input JSON
+  giz app run APP_ID --expected-revision REVISION [--computer COMPUTER]
+  giz app publish APP_ID private|workspace|public --expected-revision REVISION [--computer COMPUTER]
+  giz app open APP_ID [--computer COMPUTER]
+  giz app delete APP_ID --expected-revision REVISION [--computer COMPUTER]`
+  if (command === 'plugin') return `Usage
+  giz plugin list [--computer COMPUTER]
+  giz plugin search QUERY [--origin catalog|skill|mcp] [--limit N]
+  giz plugin inspect DRIVE_PATH
+  giz plugin install ID --query QUERY [--computer COMPUTER]
+  giz plugin install --path DRIVE_PATH [--computer COMPUTER]
+  giz plugin update|enable|disable|remove NAME [--computer COMPUTER]
+  giz plugin publish DRIVE_PATH --visibility organization|public [--organization ORG]
+  giz plugin unpublish RELEASE
+
+A plugin (Agent Plugins 1.0) bundles skills, MCP servers and Agents; it is what you install, turn off and share.`
+  if (command === 'connection') return `Usage
+  giz connection list [--computer COMPUTER]`
+  if (command === 'agent') return `Usage
+  giz agent start [--computer COMPUTER] --input JSON
+  giz agent status TURN [--wait]
+  giz agent cancel TURN`
+  if (command === 'mcp') return `Usage
+  giz mcp url
+  giz mcp serve
+  giz mcp check --json
+  giz mcp add codex|claude [--transport stdio|http]
+
+stdio (default) shares giz auth login and refreshes tokens automatically.
+http uses the client's own OAuth login. Install the chosen client first.`
+  if (command === 'update') return `Usage\n  giz update\n\nUpdates @gizai/cli with its owning package manager.`
+  if (command === 'auth') return `Usage
+  giz auth login [--device]
+  giz auth status
+  giz auth logout`
+  return `Giz CLI — AI models, Drive, and Computer from any terminal
+
+Usage
+  giz auth login [--device]
+  giz update
+  giz api-key list|create|revoke
+  giz chat MODEL "your prompt"
+  giz model list [--type TYPE] [--search TEXT]
+  giz model get MODEL
+  giz model run MODEL --input JSON [--upload FIELD=LOCAL_PATH]
+  giz generate image|video|music|talking-head "PROMPT" [--model MODEL]
+  giz generate audio --input JSON [--model MODEL]
+  giz job list|get|wait|cancel [JOB]
+  giz credits
+  giz drive ls|list|search|read|write|mkdir|move|delete
+  giz table list|get|read|write|action
+  giz upload LOCAL_PATH
+  giz computer list|get|start|stop|exec
+  giz app list|create|save|run|publish|open|delete
+  giz plugin list|search|inspect|install|update|enable|disable|remove|publish|unpublish
+  giz connection list
+  giz agent start|status|cancel
+  giz engine run claude "instruction" [--dir path]
+  giz mcp url|serve|check|add
+  giz skill install
+  giz invoke TOOL --input JSON
+
+Use giz COMMAND --help for parameters and examples.
+
+Gizlang (the toolchain is installed on first use, with its size shown)
+  init, run, build, test, check, deploy, and every other command; gizdb runs the database server.
+  Docs: https://gizstack.com/docs
+
+Global options
+  --json                 Machine-readable JSON output
+  --base-url URL         Another Giz deployment
+  --org ORGANIZATION     Organization id to work in (or GIZ_ORGANIZATION)
+  --no-open              Print the login URL without opening a browser
+
+Docs: https://www.giz.ai/mcp/`
+}
+
+// giz.ai's commands are the ones its overview lists; every other command is the Gizlang toolchain's (toolchain.mjs).
+function gizCommand(name) {
+  return ['help', 'models', '__update-check'].includes(name) ||
+    help().split('\n').some((line) => line.startsWith('  giz ') && line.trim().split(' ')[1] === name)
+}
+
+async function main() {
+  const { positionals, options } = parse(process.argv.slice(2))
+  const [first, second] = positionals
+  const asked = first === 'help' ? second : first
+  if (asked && !gizCommand(asked) && toolchainCommand(asked)) {
+    await runToolchain('giz', process.argv.slice(2))
+    return
+  }
+  if (positionals[0] === '__update-check') {
+    await runCommand('', positionals, options)
+    return
+  }
+  const source = installSource()
+  const saved = await readConfig()
+  const updateMode = ['notify', 'off'].includes(saved?.updates?.mode) ? saved.updates.mode : 'notify'
+  void maybeNotify({ version: CLI_VERSION, source, mode: updateMode, env: { ...process.env, GIZ_JSON: options.json === true ? '1' : process.env.GIZ_JSON } }).catch(() => {})
+  const requiresAuth = positionals.length && !options.help && !options.version &&
+    !(positionals[0] === 'auth' && ['login', 'logout'].includes(positionals[1])) &&
+    !['update', '__update-check'].includes(positionals[0])
+  const computer = requiresAuth && !process.env.GIZ_TOKEN && !saved?.access_token ? await computerIdentity() : undefined
+  const baseUrl = String(options['base-url'] || process.env.GIZ_URL || saved?.baseUrl || computer?.baseUrl || DEFAULT_URL).replace(/\/+$/, '')
+  if (typeof options.org === 'string') process.env.GIZ_ORGANIZATION = options.org
+  options.input = await inputText(options.input)
+  const output = await runCommand(baseUrl, positionals, options)
+  if (output) {
+    print(output.kind, output.value, options.json === true)
+    process.exitCode = output.exitCode ?? (output.value?.isError ? 1 : 0)
+  }
+}
+
+main().catch((error) => {
+  const { options } = parse(process.argv.slice(2))
+  const json = options.json === true
+  const failure = { message: String(error?.message || error), hint: error?.hint, status: error?.status }
+  print('message', json ? { error: failure } : `Error: ${failure.message}${failure.hint ? `\nHint: ${failure.hint}` : ''}`, json, process.stderr)
+  process.exitCode = 1
+})