sume models list is a deprecated alias: use sume catalog list

Use sume catalog list. sume models list still works, because the command reference keeps it as a deprecated alias for sume catalog list, but new scripts should call the catalog name and add --json when a program reads the output.

The rename is easy to miss because the old name reads naturally. Anyone who learned the CLI from an older tutorial, a pasted snippet or a generated script will type sume models list first. This post covers what the alias is, what the command does and does not list, and how to move old scripts safely.

What the docs say, read 2026-10-10

The Command reference puts sume catalog list among the read commands and then states the alias in one sentence: sume models list stays as a deprecated alias. The Agent skills page uses only the new name, with --json, in its read-only planning list.

A deprecated alias is a promise of continued behavior for now, not for ever. The page does not give a removal date, so do not assume one. Treat the alias as a migration aid and plan to change callers. The cost of waiting is small today, but a script that fails on a future release is a poor way to learn the alias is gone.

What the catalog command is, and is not

The name matches the API route. The OpenAPI operation behind GET /v1/catalog is listPublicApiCapabilities, so the catalog is a capability listing from the public API, and the command is the terminal view of the same idea.

Because it is a read, it is safe to run on a schedule, for example to log what the account can see before a nightly job starts. Do not read it as a way to generate media. The command reference says plainly that Image, Video and Music generators do not exist as CLI subcommands at this time. To generate those, call the Developer API or use the SDK. The CLI is for account checks, catalog and health reads, jobs, assets and the Avatar commands.

Migrate an old script

The change is a one-word edit, so the risk is in finding every place. Search your repositories, CI files, README snippets and shell aliases. Then decide whether the caller needs structured output.

Keep the change small and verify with a read-only run. Nothing here spends credits, since the listing and doctor commands are reads.

• Search for models list across scripts, workflow files and docs you maintain.
• Replace it with catalog list, and add --json where a program parses the result.
• Run sume doctor --agent --json first so a missing login fails fast and clearly.
• Leave the alias in place only where you cannot redeploy yet, and note it in a comment.

# Old scripts keep working through the deprecated alias
sume models list

# Write new scripts against the current name
sume catalog list --json

# Read-only preflight for an automation run
sume doctor --agent --json
sume tools list --json

Agents and the read-only habit

The Agent skills page recommends read commands while you plan, and lists the catalog, doctor, tools and jobs reads. Writes need --confirm-submit, and credit-spending Avatar work needs --confirm-paid. A listing never needs either gate.

If an agent runs your old script and gets a deprecation notice or a changed layout, that is the moment to switch to --json, which gives a stable shape to parse. For more on the unattended case, see the CLI in CI and on headless servers and doctor as a CI preflight.