@swarmclawai/swarmclaw 1.5.31 → 1.5.33

package/README.md

@@ -371,6 +371,11 @@ Operational docs: https://swarmclaw.ai/docs/observability
 
 ## Releases
 
+### v1.5.33 Highlights
+
+- **CLI global flag compatibility**: legacy-routed commands now honor the documented `--access-key` and `--base-url` aliases even when they appear after the subcommand, so authenticated CLI automation works the same across binary entry points.
+- **Docker build memory hardening**: production Next.js builds now size `--max-old-space-size` from the detected container/cgroup memory limit, with `SWARMCLAW_BUILD_MAX_OLD_SPACE_SIZE_MB` available as an explicit override for constrained Docker Desktop and CI environments.
+
 ### v1.5.31 Highlights
 
 - **Fix Docker first-run crash**: resolved `EISDIR: illegal operation on a directory, read` error when running `docker compose up` without a pre-existing `.env.local` file. Docker was creating a directory mount instead of a file, which crashed Next.js on startup. Replaced the file bind mount with `env_file` directive using `required: false`.

package/bin/swarmclaw.js

@@ -19,6 +19,11 @@ const TS_CLI_ACTIONS = Object.freeze({
   webhooks: new Set(['list', 'get', 'create', 'update', 'delete', 'trigger']),
 })
 
+const LEGACY_TS_CLI_ALIAS_MAP = Object.freeze({
+  '--base-url': '--url',
+  '--access-key': '--key',
+})
+
 function shouldUseLegacyTsCli(argv) {
   const group = argv[0]
   const action = argv[1]
@@ -62,9 +67,37 @@ function buildLegacyTsCliArgs(cliPath, argv, options = {}) {
   return null
 }
 
+function normalizeLegacyTsCliArgv(argv) {
+  const normalized = []
+
+  for (const token of argv) {
+    if (!token.startsWith('--')) {
+      normalized.push(token)
+      continue
+    }
+
+    const eqIndex = token.indexOf('=')
+    const flag = eqIndex > -1 ? token.slice(0, eqIndex) : token
+    const mappedFlag = LEGACY_TS_CLI_ALIAS_MAP[flag]
+
+    if (!mappedFlag) {
+      normalized.push(token)
+      continue
+    }
+
+    if (eqIndex > -1) {
+      normalized.push(`${mappedFlag}=${token.slice(eqIndex + 1)}`)
+    } else {
+      normalized.push(mappedFlag)
+    }
+  }
+
+  return normalized
+}
+
 function runLegacyTsCli(argv) {
   const cliPath = path.join(__dirname, '..', 'src', 'cli', 'index.ts')
-  const args = buildLegacyTsCliArgs(cliPath, argv)
+  const args = buildLegacyTsCliArgs(cliPath, normalizeLegacyTsCliArgv(argv))
   const env = normalizeLegacyCliEnv(process.env)
   if (!args) {
     process.stderr.write('Legacy CLI commands require Node 22.6+ or an available local tsx runtime.\n')
@@ -237,6 +270,7 @@ if (require.main === module) {
 module.exports = {
   buildLegacyTsCliArgs,
   hasTsxRuntime,
+  normalizeLegacyTsCliArgv,
   TS_CLI_ACTIONS,
   normalizeLegacyCliEnv,
   printPackageVersion,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmclawai/swarmclaw",
-  "version": "1.5.31",
+  "version": "1.5.33",
   "description": "Build and run autonomous AI agents with OpenClaw, Hermes, multiple model providers, orchestration, delegation, memory, skills, schedules, and chat connectors.",
   "license": "MIT",
   "publishConfig": {
@@ -72,7 +72,7 @@
     "lint:baseline:update": "node ./scripts/lint-baseline.mjs update",
     "cli": "node ./bin/swarmclaw.js",
     "test:cli": "node --test src/cli/*.test.js bin/*.test.js scripts/postinstall.test.mjs scripts/run-next-build.test.mjs scripts/run-next-typegen.test.mjs",
-    "test:setup": "tsx --test src/app/api/setup/check-provider/route.test.ts src/lib/server/provider-model-discovery.test.ts src/components/auth/setup-wizard/utils.test.ts src/components/auth/setup-wizard/types.test.ts src/hooks/setup-done-detection.test.ts src/lib/setup-defaults.test.ts",
+    "test:setup": "tsx --test src/app/api/setup/check-provider/route.test.ts src/lib/server/provider-model-discovery.test.ts src/components/auth/setup-wizard/utils.test.ts src/components/auth/setup-wizard/types.test.ts src/hooks/setup-done-detection.test.ts src/lib/setup-defaults.test.ts src/lib/server/storage-auth.test.ts src/lib/server/storage-auth-docker.test.ts",
     "test:openclaw": "tsx --test src/lib/openclaw/openclaw-agent-id.test.ts src/lib/openclaw/openclaw-endpoint.test.ts src/lib/server/agents/agent-runtime-config.test.ts src/lib/server/build-llm.test.ts src/lib/server/connectors/connector-routing.test.ts src/lib/server/connectors/openclaw.test.ts src/lib/server/connectors/swarmdock.test.ts src/lib/server/gateway/protocol.test.ts src/lib/server/llm-response-cache.test.ts src/lib/server/mcp-conformance.test.ts src/lib/server/openclaw/agent-resolver.test.ts src/lib/server/openclaw/deploy.test.ts src/lib/server/openclaw/skills-normalize.test.ts src/lib/server/session-tools/openclaw-nodes.test.ts src/lib/server/session-tools/swarmdock.test.ts src/lib/server/tasks/task-quality-gate.test.ts src/lib/server/tasks/task-validation.test.ts src/lib/server/tool-capability-policy.test.ts src/lib/providers/openclaw-exports.test.ts src/app/api/openclaw/dashboard-url/route.test.ts",
     "test:runtime": "tsx --test src/lib/server/knowledge-sources.test.ts src/lib/server/chat-execution/chat-execution-grounding.test.ts src/lib/server/protocols/protocol-service.test.ts src/lib/server/runtime/run-ledger.test.ts src/lib/server/observability/otel-config.test.ts src/lib/server/safe-parse-body.test.ts src/app/api/approvals/route.test.ts src/app/api/chats/chat-route.test.ts src/app/api/connectors/connector-doctor-route.test.ts src/app/api/healthz/route.test.ts src/app/api/logs/route.test.ts src/app/api/tts/route.test.ts",
     "test:builder": "tsx --test src/features/protocols/builder/utils/nodes-to-template.test.ts src/features/protocols/builder/utils/template-to-nodes.test.ts src/features/protocols/builder/validators/dag-validator.test.ts",

package/scripts/run-next-build.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 import fs from 'node:fs'
+import os from 'node:os'
 import path from 'node:path'
 import { spawnSync } from 'node:child_process'
 import { createRequire } from 'node:module'
@@ -11,6 +12,17 @@ import { ensureBuildBootstrapPaths } from './build-bootstrap-env.mjs'
 const require = createRequire(import.meta.url)
 
 export const DEFAULT_MAX_OLD_SPACE_SIZE_MB = '8192'
+export const MIN_MAX_OLD_SPACE_SIZE_MB = 1024
+export const FALLBACK_MIN_MAX_OLD_SPACE_SIZE_MB = 512
+export const RESERVED_BUILD_MEMORY_MB = 768
+export const MAX_OLD_SPACE_RATIO = 0.75
+export const LOW_MEMORY_RATIO = 0.6
+export const BUILD_MAX_OLD_SPACE_SIZE_ENV = 'SWARMCLAW_BUILD_MAX_OLD_SPACE_SIZE_MB'
+export const CGROUP_MEMORY_LIMIT_PATHS = [
+  '/sys/fs/cgroup/memory.max',
+  '/sys/fs/cgroup/memory/memory.limit_in_bytes',
+]
+export const UNBOUNDED_MEMORY_LIMIT_BYTES = 1n << 60n
 export const TRACE_COPY_WARNING = 'Failed to copy traced files'
 export const NEXT_STANDALONE_METADATA_RELATIVE_DIR = path.join(
   'node_modules',
@@ -24,6 +36,74 @@ export const REQUIRED_NEXT_METADATA_FILES = [
   'is-metadata-route.js',
 ]
 
+function parsePositiveInteger(value) {
+  const parsed = Number.parseInt(String(value ?? '').trim(), 10)
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : null
+}
+
+export function readCgroupMemoryLimitBytes(
+  paths = CGROUP_MEMORY_LIMIT_PATHS,
+  existsSync = fs.existsSync,
+  readFileSync = fs.readFileSync,
+) {
+  for (const filePath of paths) {
+    if (!existsSync(filePath)) continue
+
+    let raw = ''
+    try {
+      raw = String(readFileSync(filePath, 'utf8')).trim()
+    } catch {
+      continue
+    }
+
+    if (!raw || raw === 'max') continue
+
+    try {
+      const bytes = BigInt(raw)
+      if (bytes <= 0n || bytes >= UNBOUNDED_MEMORY_LIMIT_BYTES) continue
+      return Number(bytes)
+    } catch {
+      continue
+    }
+  }
+
+  return null
+}
+
+export function deriveMaxOldSpaceSizeMb(memoryLimitBytes, defaultMaxOldSpaceSizeMb = DEFAULT_MAX_OLD_SPACE_SIZE_MB) {
+  const defaultMb = parsePositiveInteger(defaultMaxOldSpaceSizeMb) ?? Number.parseInt(DEFAULT_MAX_OLD_SPACE_SIZE_MB, 10)
+  const limitMb = Math.floor(Number(memoryLimitBytes) / (1024 * 1024))
+  if (!Number.isFinite(limitMb) || limitMb <= 0) return String(defaultMb)
+
+  const constrainedCandidate = Math.min(
+    defaultMb,
+    limitMb - RESERVED_BUILD_MEMORY_MB,
+    Math.floor(limitMb * MAX_OLD_SPACE_RATIO),
+  )
+  if (constrainedCandidate >= MIN_MAX_OLD_SPACE_SIZE_MB) {
+    return String(constrainedCandidate)
+  }
+
+  return String(Math.max(
+    FALLBACK_MIN_MAX_OLD_SPACE_SIZE_MB,
+    Math.min(defaultMb, Math.floor(limitMb * LOW_MEMORY_RATIO)),
+  ))
+}
+
+export function resolveNextBuildMaxOldSpaceSizeMb(
+  env = process.env,
+  options = {},
+) {
+  const explicit = parsePositiveInteger(env[BUILD_MAX_OLD_SPACE_SIZE_ENV])
+  if (explicit) return String(explicit)
+
+  const readLimitBytes = options.readCgroupMemoryLimitBytes ?? readCgroupMemoryLimitBytes
+  const totalMemFn = options.totalMem ?? os.totalmem
+  const memoryLimitBytes = readLimitBytes() ?? totalMemFn()
+
+  return deriveMaxOldSpaceSizeMb(memoryLimitBytes, DEFAULT_MAX_OLD_SPACE_SIZE_MB)
+}
+
 export function mergeNodeOptions(nodeOptions = '', maxOldSpaceSizeMb = DEFAULT_MAX_OLD_SPACE_SIZE_MB) {
   const trimmed = nodeOptions.trim()
   if (/(^|\s)--max-old-space-size(?:=|\s|$)/.test(trimmed)) return trimmed
@@ -120,12 +200,17 @@ export function repairStandaloneNextMetadata(cwd = process.cwd()) {
   return true
 }
 
-export function runNextBuild(args = process.argv.slice(2), env = process.env, cwd = process.cwd()) {
+export function runNextBuild(
+  args = process.argv.slice(2),
+  env = process.env,
+  cwd = process.cwd(),
+  maxOldSpaceSizeMb = resolveNextBuildMaxOldSpaceSizeMb(env),
+) {
   const nextBin = require.resolve('next/dist/bin/next')
   return spawnSync(process.execPath, [nextBin, 'build', '--webpack', ...args], {
     stdio: 'pipe',
     encoding: 'utf-8',
-    env: buildNextBuildEnv(env, DEFAULT_MAX_OLD_SPACE_SIZE_MB, cwd),
+    env: buildNextBuildEnv(env, maxOldSpaceSizeMb, cwd),
     cwd,
   })
 }

package/src/app/api/agents/[id]/route.ts

@@ -1,9 +1,17 @@
 import { NextResponse } from 'next/server'
 import { notFound } from '@/lib/server/collection-helpers'
 import { trashAgent, updateAgent } from '@/lib/server/agents/agent-service'
+import { loadAgent } from '@/lib/server/agents/agent-repository'
 import { notify } from '@/lib/server/ws-hub'
 import { safeParseBody } from '@/lib/server/safe-parse-body'
 
+export async function GET(_req: Request, { params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params
+  const agent = loadAgent(id)
+  if (!agent) return notFound()
+  return NextResponse.json(agent)
+}
+
 export async function PUT(req: Request, { params }: { params: Promise<{ id: string }> }) {
   const { id } = await params
   const { data: body, error } = await safeParseBody(req)

package/src/app/api/agents/agents-route.test.ts

@@ -0,0 +1,114 @@
+import assert from 'node:assert/strict'
+import test, { afterEach } from 'node:test'
+
+// Disable daemon autostart during tests
+process.env.SWARMCLAW_DAEMON_AUTOSTART = '0'
+
+import { GET as getAgent } from './[id]/route'
+import { POST as createAgent } from './route'
+import { loadAgents, saveAgents } from '@/lib/server/storage'
+
+const originalAgents = loadAgents()
+
+function routeParams(id: string) {
+  return { params: Promise.resolve({ id }) }
+}
+
+function seedAgent(id: string, overrides: Record<string, unknown> = {}) {
+  const agents = loadAgents()
+  const now = Date.now()
+  agents[id] = {
+    id,
+    name: 'Test Agent',
+    description: 'Route test',
+    systemPrompt: '',
+    provider: 'ollama',
+    model: 'qwen3.5',
+    credentialId: null,
+    fallbackCredentialIds: [],
+    apiEndpoint: null,
+    gatewayProfileId: null,
+    extensions: [],
+    createdAt: now,
+    updatedAt: now,
+    ...overrides,
+  }
+  saveAgents(agents)
+}
+
+afterEach(() => {
+  saveAgents(originalAgents)
+})
+
+// --- GET /api/agents/:id ---
+
+test('GET /api/agents/:id returns the agent when it exists', async () => {
+  seedAgent('agent-get-test', { name: 'GetMe' })
+
+  const response = await getAgent(
+    new Request('http://local/api/agents/agent-get-test'),
+    routeParams('agent-get-test'),
+  )
+
+  assert.equal(response.status, 200)
+  const body = await response.json()
+  assert.equal(body.id, 'agent-get-test')
+  assert.equal(body.name, 'GetMe')
+})
+
+test('GET /api/agents/:id returns 404 for a non-existent agent', async () => {
+  const response = await getAgent(
+    new Request('http://local/api/agents/does-not-exist'),
+    routeParams('does-not-exist'),
+  )
+
+  assert.equal(response.status, 404)
+  const body = await response.json()
+  assert.equal(body.error, 'Not found')
+})
+
+// --- POST /api/agents (provider validation) ---
+
+test('POST /api/agents rejects an unknown provider with a 400', async () => {
+  const response = await createAgent(new Request('http://local/api/agents', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ name: 'Bad Provider Agent', provider: 'nonexistent_provider', model: 'x' }),
+  }))
+
+  assert.equal(response.status, 400)
+  const body = await response.json()
+  assert.equal(body.error, 'Validation failed')
+  assert.ok(body.issues.some((i: { path: string; message: string }) => i.path === 'provider'))
+})
+
+test('POST /api/agents accepts a valid provider and creates the agent', async () => {
+  const response = await createAgent(new Request('http://local/api/agents', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ name: 'Good Agent', provider: 'ollama', model: 'qwen3.5' }),
+  }))
+
+  assert.equal(response.status, 200)
+  const body = await response.json()
+  assert.equal(body.name, 'Good Agent')
+  assert.equal(body.provider, 'ollama')
+  assert.ok(body.id)
+
+  // Clean up
+  const agents = loadAgents()
+  delete agents[body.id]
+  saveAgents(agents)
+})
+
+test('POST /api/agents rejects missing required fields with a 400', async () => {
+  const response = await createAgent(new Request('http://local/api/agents', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({}),
+  }))
+
+  assert.equal(response.status, 400)
+  const body = await response.json()
+  assert.equal(body.error, 'Validation failed')
+})

package/src/app/api/agents/route.ts

@@ -3,6 +3,7 @@ import { perf } from '@/lib/server/runtime/perf'
 import { listAgentsForApi, createAgent } from '@/lib/server/agents/agent-service'
 import { AgentCreateSchema, formatZodError } from '@/lib/validation/schemas'
 import { ensureDaemonProcessRunning } from '@/lib/server/daemon/controller'
+import { getProvider } from '@/lib/providers'
 import { z } from 'zod'
 import { safeParseBody } from '@/lib/server/safe-parse-body'
 import { loadSettings } from '@/lib/server/storage'
@@ -40,6 +41,15 @@ export async function POST(req: Request) {
   }
   const body = parsed.data as unknown as Record<string, unknown>
 
+  // Validate provider exists
+  const providerId = String(body.provider || '')
+  if (providerId && !getProvider(providerId)) {
+    return NextResponse.json(
+      { error: 'Validation failed', issues: [{ path: 'provider', message: `Unknown provider: "${providerId}"` }] },
+      { status: 400 },
+    )
+  }
+
   // Check approval policy — if enabled, create an approval request instead of the agent
   const settings = loadSettings()
   if (settings.approvalPolicies?.requireApprovalForAgentCreate) {

package/src/app/api/connectors/route.ts

@@ -13,21 +13,33 @@ import { ensureDaemonProcessRunning } from '@/lib/server/daemon/controller'
 export const dynamic = 'force-dynamic'
 
 export async function GET() {
-  const endPerf = perf.start('api', 'GET /api/connectors')
-  const connectors = await listConnectorsWithRuntime()
-  endPerf({ count: Object.keys(connectors).length })
-  return NextResponse.json(connectors)
+  try {
+    const endPerf = perf.start('api', 'GET /api/connectors')
+    const connectors = await listConnectorsWithRuntime()
+    endPerf({ count: Object.keys(connectors).length })
+    return NextResponse.json(connectors)
+  } catch (err) {
+    return NextResponse.json({ error: err instanceof Error ? err.message : String(err) }, { status: 500 })
+  }
 }
 
 export async function POST(req: Request) {
-  await ensureDaemonProcessRunning('api/connectors:post')
-  const { data: raw, error } = await safeParseBody<Record<string, unknown>>(req)
-  if (error) return error
-  const parsed = ConnectorCreateSchema.safeParse(raw)
-  if (!parsed.success) {
-    return NextResponse.json(formatZodError(parsed.error as z.ZodError), { status: 400 })
+  try {
+    await ensureDaemonProcessRunning('api/connectors:post')
+    const { data: raw, error } = await safeParseBody<Record<string, unknown>>(req)
+    if (error) return error
+    const parsed = ConnectorCreateSchema.safeParse(raw)
+    if (!parsed.success) {
+      return NextResponse.json(formatZodError(parsed.error as z.ZodError), { status: 400 })
+    }
+    const connector = createConnector(parsed.data as unknown as Record<string, unknown>)
+    try {
+      await autoStartConnectorIfNeeded(connector, parsed.data as unknown as Record<string, unknown>)
+    } catch {
+      // Auto-start failure is non-fatal — the connector is still saved.
+    }
+    return NextResponse.json(await getConnectorWithRuntime(connector.id) || connector)
+  } catch (err) {
+    return NextResponse.json({ error: err instanceof Error ? err.message : String(err) }, { status: 500 })
   }
-  const connector = createConnector(parsed.data as unknown as Record<string, unknown>)
-  await autoStartConnectorIfNeeded(connector, parsed.data as unknown as Record<string, unknown>)
-  return NextResponse.json(await getConnectorWithRuntime(connector.id) || connector)
 }

package/src/app/api/credentials/[id]/route.ts

@@ -1,11 +1,18 @@
 import { NextResponse } from 'next/server'
-import { deleteCredentialRecord } from '@/lib/server/credentials/credential-service'
+import { deleteCredentialRecord, getCredentialSummary } from '@/lib/server/credentials/credential-service'
 import { notFound } from '@/lib/server/collection-helpers'
 import { log } from '@/lib/server/logger'
 import { logActivity } from '@/lib/server/activity/activity-log'
 
 const TAG = 'api-credentials'
 
+export async function GET(_req: Request, { params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params
+  const summary = getCredentialSummary(id)
+  if (!summary) return notFound()
+  return NextResponse.json(summary)
+}
+
 export async function DELETE(_req: Request, { params }: { params: Promise<{ id: string }> }) {
   const { id: credId } = await params
   if (!deleteCredentialRecord(credId)) {

package/src/app/api/schedules/[id]/route.ts

@@ -1,11 +1,19 @@
 import { NextResponse } from 'next/server'
 import { notFound } from '@/lib/server/collection-helpers'
 import { safeParseBody } from '@/lib/server/safe-parse-body'
+import { loadSchedule } from '@/lib/server/schedules/schedule-repository'
 import {
   deleteScheduleFromRoute,
   updateScheduleFromRoute,
 } from '@/lib/server/schedules/schedule-route-service'
 
+export async function GET(_req: Request, { params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params
+  const schedule = loadSchedule(id)
+  if (!schedule) return notFound()
+  return NextResponse.json(schedule)
+}
+
 export async function PUT(req: Request, { params }: { params: Promise<{ id: string }> }) {
   const { id } = await params
   const { data: body, error } = await safeParseBody(req)

package/src/app/api/secrets/[id]/route.ts

@@ -6,6 +6,16 @@ import { safeParseBody } from '@/lib/server/safe-parse-body'
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 const ops: CollectionOps<any> = { load: loadSecrets, save: saveSecrets }
 
+export async function GET(_req: Request, { params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params
+  const secrets = loadSecrets()
+  const secret = secrets[id]
+  if (!secret) return notFound()
+  // Never expose the encrypted value
+  const { encryptedValue, ...safe } = secret as Record<string, unknown>
+  return NextResponse.json(safe)
+}
+
 export async function DELETE(_req: Request, { params }: { params: Promise<{ id: string }> }) {
   const { id } = await params
   if (!deleteItem(ops, id)) return notFound()

package/src/app/api/setup/check-provider/route.ts

@@ -1,11 +1,20 @@
 import { NextResponse } from 'next/server'
 import { loadCredentials, decryptKey } from '@/lib/server/storage'
 import { getDeviceId, wsConnect, rpcOnConnectedGateway } from '@/lib/providers/openclaw'
+import { buildCliEnv, probeCliAuth, resolveCliBinary } from '@/lib/providers/cli-utils'
 import { OPENAI_COMPATIBLE_DEFAULTS } from '@/lib/server/provider-health'
 import { resolveOllamaRuntimeConfig } from '@/lib/server/ollama-runtime'
 import { normalizeOllamaSetupEndpoint, normalizeOpenClawUrl, parseErrorMessage } from './helpers'
 
 type SetupProvider =
+  | 'claude-cli'
+  | 'codex-cli'
+  | 'opencode-cli'
+  | 'gemini-cli'
+  | 'copilot-cli'
+  | 'cursor-cli'
+  | 'qwen-code-cli'
+  | 'goose'
   | 'openai'
   | 'openrouter'
   | 'anthropic'
@@ -22,6 +31,8 @@ type SetupProvider =
   | 'openclaw'
   | 'hermes'
 
+type CliSetupProvider = 'claude-cli' | 'codex-cli' | 'opencode-cli' | 'gemini-cli' | 'copilot-cli' | 'cursor-cli' | 'qwen-code-cli' | 'goose'
+
 interface SetupCheckBody {
   provider?: string
   apiKey?: string
@@ -266,6 +277,34 @@ async function checkOpenClaw(apiKey: string, endpointRaw: string): Promise<{ ok:
   return { ok: true, message: 'Connected to OpenClaw gateway.', normalizedEndpoint, deviceId, recommendedModel }
 }
 
+function checkCliProvider(provider: CliSetupProvider): { ok: boolean; message: string } {
+  const env = buildCliEnv()
+  const config = {
+    'claude-cli': { binary: 'claude', backend: 'claude' as const, label: 'Claude Code CLI' },
+    'codex-cli': { binary: 'codex', backend: 'codex' as const, label: 'OpenAI Codex CLI' },
+    'opencode-cli': { binary: 'opencode', backend: 'opencode' as const, label: 'OpenCode CLI' },
+    'gemini-cli': { binary: 'gemini', backend: 'gemini' as const, label: 'Gemini CLI' },
+    'copilot-cli': { binary: 'copilot', backend: 'copilot' as const, label: 'GitHub Copilot CLI' },
+    'cursor-cli': { binary: 'cursor-agent', backend: 'cursor' as const, label: 'Cursor Agent CLI' },
+    'qwen-code-cli': { binary: 'qwen', backend: 'qwen' as const, label: 'Qwen Code CLI' },
+    goose: { binary: 'goose', backend: 'goose' as const, label: 'Goose CLI' },
+  }[provider]
+
+  if (!config) return { ok: false, message: 'Unknown CLI provider.' }
+  const binary = resolveCliBinary(config.binary)
+  if (!binary) {
+    return {
+      ok: false,
+      message: `${config.label} is not installed. Install \`${config.binary}\` and ensure it is on your PATH.`,
+    }
+  }
+  const auth = probeCliAuth(binary, config.backend, env, process.cwd())
+  if (!auth.authenticated) {
+    return { ok: false, message: auth.errorMessage || `${config.label} is not configured.` }
+  }
+  return { ok: true, message: `${config.label} is installed and ready.` }
+}
+
 export async function POST(req: Request) {
   const body = parseBody(await req.json().catch(() => ({})))
   const provider = clean(body.provider) as SetupProvider
@@ -273,6 +312,7 @@ export async function POST(req: Request) {
   const credentialId = clean(body.credentialId)
   const endpoint = clean(body.endpoint)
   const model = clean(body.model)
+  const CLI_PROVIDERS = new Set<CliSetupProvider>(['claude-cli', 'codex-cli', 'opencode-cli', 'gemini-cli', 'copilot-cli', 'cursor-cli', 'qwen-code-cli', 'goose'])
 
   // Resolve credentialId to an API key if no raw key was provided
   if (!apiKey && credentialId) {
@@ -287,6 +327,11 @@ export async function POST(req: Request) {
     }
   }
 
+  if (CLI_PROVIDERS.has(provider as CliSetupProvider)) {
+    const result = checkCliProvider(provider as CliSetupProvider)
+    return NextResponse.json(result)
+  }
+
   if (!provider) {
     return NextResponse.json({ ok: false, message: 'Provider is required.' }, { status: 400 })
   }

package/src/app/api/setup/doctor/route.ts

@@ -171,6 +171,11 @@ export async function GET(req: Request) {
     { id: 'claude-cli', label: 'Claude Code CLI', command: 'claude' },
     { id: 'codex-cli', label: 'OpenAI Codex CLI', command: 'codex' },
     { id: 'opencode-cli', label: 'OpenCode CLI', command: 'opencode' },
+    { id: 'gemini-cli', label: 'Gemini CLI', command: 'gemini' },
+    { id: 'copilot-cli', label: 'GitHub Copilot CLI', command: 'copilot' },
+    { id: 'cursor-cli', label: 'Cursor Agent CLI', command: 'cursor-agent' },
+    { id: 'qwen-code-cli', label: 'Qwen Code CLI', command: 'qwen' },
+    { id: 'goose', label: 'Goose CLI', command: 'goose' },
     { id: 'google-workspace-cli', label: 'Google Workspace CLI', command: 'gws' },
   ]
 

package/src/cli/binary.test.js

@@ -113,6 +113,17 @@ test('legacy-routed binary commands fall back to platform-api-key.txt', () => {
   fs.rmSync(tmpDir, { recursive: true, force: true })
 })
 
+test('legacy-routed binary commands accept documented global aliases after the subcommand', () => {
+  const { result, capture } = runWithMockedFetch(
+    ['agents', 'list', '--access-key', 'alias-key', '--base-url', 'http://127.0.0.1:4567', '--json'],
+  )
+
+  assert.equal(result.status, 0, result.stderr)
+  assert.equal(result.stdout.trim(), '[]')
+  assert.equal(capture.headers['X-Access-Key'], 'alias-key')
+  assert.equal(capture.url, 'http://127.0.0.1:4567/api/agents')
+})
+
 test('binary server help exits successfully', () => {
   const result = runBinary(['server', '--help'])
   assert.equal(result.status, 0, result.stderr)

package/src/cli/index.js

@@ -15,7 +15,7 @@ const COMMAND_GROUPS = [
     description: 'Manage agents',
     commands: [
       cmd('list', 'GET', '/agents', 'List agents'),
-      cmd('get', 'GET', '/agents/:id', 'Get an agent by id', { virtual: true, clientGetRoute: '/agents' }),
+      cmd('get', 'GET', '/agents/:id', 'Get an agent by id'),
       cmd('create', 'POST', '/agents', 'Create an agent', { expectsJsonBody: true }),
       cmd('update', 'PUT', '/agents/:id', 'Update an agent', { expectsJsonBody: true }),
       cmd('delete', 'DELETE', '/agents/:id', 'Delete an agent'),
@@ -142,7 +142,7 @@ const COMMAND_GROUPS = [
     description: 'Manage encrypted provider credentials',
     commands: [
       cmd('list', 'GET', '/credentials', 'List credentials'),
-      cmd('get', 'GET', '/credentials/:id', 'Get credential metadata by id', { virtual: true, clientGetRoute: '/credentials' }),
+      cmd('get', 'GET', '/credentials/:id', 'Get credential metadata by id'),
       cmd('create', 'POST', '/credentials', 'Create credential', { expectsJsonBody: true }),
       cmd('delete', 'DELETE', '/credentials/:id', 'Delete credential'),
     ],
@@ -541,7 +541,7 @@ const COMMAND_GROUPS = [
     description: 'Manage schedules',
     commands: [
       cmd('list', 'GET', '/schedules', 'List schedules'),
-      cmd('get', 'GET', '/schedules/:id', 'Get schedule by id', { virtual: true, clientGetRoute: '/schedules' }),
+      cmd('get', 'GET', '/schedules/:id', 'Get schedule by id'),
       cmd('create', 'POST', '/schedules', 'Create schedule', { expectsJsonBody: true }),
       cmd('update', 'PUT', '/schedules/:id', 'Update schedule', { expectsJsonBody: true }),
       cmd('delete', 'DELETE', '/schedules/:id', 'Delete schedule'),
@@ -553,7 +553,7 @@ const COMMAND_GROUPS = [
     description: 'Manage reusable encrypted secrets',
     commands: [
       cmd('list', 'GET', '/secrets', 'List secrets metadata'),
-      cmd('get', 'GET', '/secrets/:id', 'Get secret metadata by id', { virtual: true, clientGetRoute: '/secrets' }),
+      cmd('get', 'GET', '/secrets/:id', 'Get secret metadata by id'),
       cmd('create', 'POST', '/secrets', 'Create secret', { expectsJsonBody: true }),
       cmd('update', 'PUT', '/secrets/:id', 'Update secret metadata', { expectsJsonBody: true }),
       cmd('delete', 'DELETE', '/secrets/:id', 'Delete secret'),

package/src/cli/index.test.js

@@ -453,7 +453,10 @@ test('client-side collection lookups fail cleanly when the entity is missing', a
   const stdout = makeWritable()
   const stderr = makeWritable()
 
-  const fetchImpl = async () => jsonResponse([{ id: 'agent-2', name: 'Other Agent' }])
+  const fetchImpl = async () => new Response(JSON.stringify({ error: 'Not found' }), {
+    status: 404,
+    headers: { 'content-type': 'application/json' },
+  })
 
   const exitCode = await runCli(
     ['agents', 'get', 'agent-1'],
@@ -468,7 +471,7 @@ test('client-side collection lookups fail cleanly when the entity is missing', a
 
   assert.equal(exitCode, 1)
   assert.equal(stdout.toString(), '')
-  assert.match(stderr.toString(), /entity not found for id: agent-1/i)
+  assert.match(stderr.toString(), /not found/i)
 })
 
 test('runCli loads request JSON from @file inputs', async () => {