From cee6dfe7de669055339026d0177118b8c1900b43 Mon Sep 17 00:00:00 2001
From: hbrooks <seanhunterbrooks@gmail.com>
Date: Sat, 25 Jul 2026 13:42:15 -0400
Subject: [PATCH] model: add `agent model list` so config authors can see valid
 model ids

The model registry was only reachable through the connect composer, so
anyone writing `model:` into a config YAML had to guess the id. Exposes
the existing GET /v1/models client method as a command, with `models` as
a group alias.
---
 README.md                |  2 ++
 skills/ellipsis/SKILL.md |  1 +
 src/cli.tsx              |  2 ++
 src/commands/model.ts    | 36 ++++++++++++++++++++++++++++++++++++
 4 files changed, 41 insertions(+)
 create mode 100644 src/commands/model.ts

diff --git a/README.md b/README.md
index aaeb4b3..2d99e6a 100644
--- a/README.md
+++ b/README.md
@@ -74,6 +74,8 @@ agent config default              # the effective default agent for the repo you
 agent config default set <config-id>   # set the account default agent (--repo [owner/name] for one repo)
 agent config default clear        # clear the account default (--repo [owner/name] for one repo)
 
+agent model list                  # list selectable agent models (the account default is marked)
+
 agent integrations                # every connected integration in one table
 agent github repos                # repositories connected to the GitHub installation
 agent github members              # org roster (the logins/ids --author accepts), with linked Slack identities
diff --git a/skills/ellipsis/SKILL.md b/skills/ellipsis/SKILL.md
index 86b8fc3..0d87f93 100644
--- a/skills/ellipsis/SKILL.md
+++ b/skills/ellipsis/SKILL.md
@@ -208,6 +208,7 @@ agent config init                            # scaffold agents/my_agent.yaml
 agent config create --template code-reviewer --repo api   # deploy via PR
 agent config default set <configId>          # the agent a bare start runs (--repo for one repo)
 agent template list                          # browse maintained templates
+agent model list                             # the model ids valid under `claude:`
 agent integrations                           # connected GitHub/Slack/Linear/Sentry
 agent sandbox variable set LINEAR_API_KEY=...
 agent sandbox build start --config-file agents/my_agent.yaml --watch
diff --git a/src/cli.tsx b/src/cli.tsx
index 927e683..6a3f77a 100644
--- a/src/cli.tsx
+++ b/src/cli.tsx
@@ -8,6 +8,7 @@ import { registerSandbox } from './commands/sandbox'
 import { registerAsset } from './commands/asset'
 import { registerHooks } from './commands/hooks'
 import { registerTemplate } from './commands/template'
+import { registerModel } from './commands/model'
 import { registerIntegrations } from './commands/integrations'
 import { registerGithub } from './commands/github'
 import { registerSlack } from './commands/slack'
@@ -38,6 +39,7 @@ registerSandbox(program)
 registerAsset(program)
 registerHooks(program)
 registerTemplate(program)
+registerModel(program)
 registerIntegrations(program)
 registerGithub(program)
 registerSlack(program)
diff --git a/src/commands/model.ts b/src/commands/model.ts
new file mode 100644
index 0000000..df52ca4
--- /dev/null
+++ b/src/commands/model.ts
@@ -0,0 +1,36 @@
+import { type Command } from 'commander'
+import { ApiClient } from '../lib/api'
+import { printJson, printTable, runAction } from '../lib/output'
+
+export function registerModel(program: Command): void {
+  const model = program
+    .command('model')
+    // Resource sub-groups register their plural as an alias so the two
+    // spellings can never diverge into different surfaces.
+    .alias('models')
+    .description('Browse the models your agent can run on')
+
+  model
+    .command('list')
+    .alias('ls')
+    .description('List selectable agent models (GET /v1/models)')
+    .option('--json', 'output raw JSON')
+    .action(async (opts: { json?: boolean }) => {
+      await runAction(async () => {
+        const models = await new ApiClient().listSupportedModels()
+        if (opts.json) {
+          printJson(models)
+          return
+        }
+        if (models.length === 0) {
+          console.log('No models found.')
+          return
+        }
+        printTable(
+          ['ID', 'NAME', 'DEFAULT'],
+          models.map((m) => [m.id, m.display_name, m.is_default_agent_model ? 'yes' : '']),
+        )
+        console.log('\nSelect one by setting `model:` under `claude:` in your agent config YAML.')
+      })
+    })
+}