Command reference

This page lists the current developer-platform CLI surface from sumelabs/cli. This page intentionally does not include older consumer-product commands that are not supported. Image/Video/Music generators do not exist as CLI subcommands at this time.

Use these commands to find the exact schemas at runtime:

sume tools list --json
sume tools schema <name> --json

Auth and account

sume login
sume login --device
sume logout
sume auth status
sume auth token
sume auth setup --api-key "$SUME_API_KEY"
sume me
sume account get
sume balance
sume usage get --limit 20

sume me and sume account get both read account context for the configured key.

Read commands

sume catalog list
sume health
sume health service
sume health v1
sume doctor --agent --json
sume jobs list
sume jobs get <job_id>
sume jobs status <job_id>
sume jobs events <job_id>
sume jobs result <job_id>
sume assets list
sume assets get <asset_id>
sume avatars list
sume avatars get <avatar_id>
sume avatar-videos list
sume avatar-videos get <avatar_video_id>
sume tools list --json
sume tools schema jobs.result --json
sume skills list
sume version
sume update --check

sume models list stays as a deprecated alias for sume catalog list.

Jobs helpers

sume jobs watch <job_id>
sume jobs download <job_id> --output-dir ./out
sume jobs cancel <job_id> --confirm-submit

Assets

sume assets create --source-url https://example.com/reference.png --confirm-submit
sume assets upload-url --content-type image/png --size-bytes 12345 --confirm-submit
sume assets complete <asset_id> --confirm-submit
sume assets download-url <asset_id>
sume assets download <asset_id> --output-dir ./assets

Asset registration and upload paths are write-gated. When first-party asset ids are not necessary, it is better to use public HTTPS URLs in generation payloads. Refer to Jobs and media.

Write and paid generation (Avatar)

Each write command must have explicit confirmation. At this time, the paid Avatar generators are the only first-class path to submit a generation in the CLI.

sume avatars create --confirm-paid --avatar-handle studio_presenter --type prompt --prompt "Friendly presenter"
sume avatars create --confirm-paid --avatar-handle reference_presenter --type photo --image-url https://example.com/reference.png
sume avatar-videos create --confirm-paid --avatar-handle sume_clawra --script "Say hello" --quality plus
sume avatar-videos create --confirm-paid --avatar-handle sume_clawra --product-image https://example.com/product.png --script "Introduce this product naturally" --quality plus

When provider execution can spend credits, use --confirm-paid. For non-paid writes such as job cancellation or asset registration, use --confirm-submit. Before you submit, make sure that the estimated length of the avatar-video script is 4-60 seconds inclusive. If you do not send Avatar Video quality, the default is plus.

The CLI also has batch helpers in sume avatars batch and sume avatar-videos batch (plan / create / watch / result against local state files). To examine them, use sume avatars batch --help.

Not available as CLI generators

The CLI does not ship sume image, sume video, sume music, or similar subcommands. For these families, use the HTTP API:

After you use the API to submit those jobs, you can still recover them. Use sume jobs status / sume jobs result / sume jobs download.

MCP (CLI vs hosted)

sume mcp doctor --json

In current releases, local sume mcp reports coming_soon / launched: false. sume mcp install is not available at this time.

For Cursor, Claude, and other remote MCP clients, use the hosted MCP endpoint at https://mcp.sume.com/mcp. That endpoint is a surface that is separate from the local CLI command.

Machine-readable output

sume catalog list --json
sume jobs result <job_id> --agent --json

--agent redacts URL-like and sensitive account/workspace fields where the CLI supports agent-safe output.

Skills

sume skills list
sume skills install <name>
sume skills update
sume skills remove <name>
sume skills export <name>

Refer to Agent skills.