---
title: Command reference
description: Current Sume CLI command groups and safety gates.
---

This page lists the current developer-platform CLI surface from `sumelabs/cli`.
Unsupported older consumer-product commands are intentionally omitted. Do not
assume Image/Video/Music generators exist as CLI subcommands — they do not yet.

Discover exact schemas at runtime:

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

## Auth and account

```bash
sume login
sume login --no-browser
sume logout
sume auth status
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

```bash
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` remains as a deprecated alias for `sume catalog list`.

## Jobs helpers

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

## Assets

```bash
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. Prefer public HTTPS URLs
in generation payloads when you do not need first-party asset ids. See
[Jobs and media](/cli/jobs-assets).

## Write and paid generation (Avatar)

Write commands require explicit confirmation. Paid Avatar generators are the
only first-class generation submit path in the CLI today.

```bash
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
```

Use `--confirm-paid` when provider execution may spend credits. Use
`--confirm-submit` for non-paid writes such as job cancellation or asset
registration.
Avatar-video scripts must estimate to 4-60 seconds inclusive before submission.
Avatar Video `quality` defaults to **`plus`** when omitted.

Batch helpers also exist under `sume avatars batch` and
`sume avatar-videos batch` (plan / create / watch / result against local state
files). Inspect with `sume avatars batch --help`.

## Not available as CLI generators

The CLI does **not** ship `sume image`, `sume video`, `sume music`, or similar
subcommands. Use the HTTP API instead:

| Family | Guide |
|---|---|
| Image 1.0 | [Image](/models/image) |
| Video 1.0 | [Video](/models/video) |
| Music 1.0 | [Music](/models/music) |

After you submit those jobs via API, you can still recover them with
`sume jobs status` / `sume jobs result` / `sume jobs download`.

## MCP (CLI vs hosted)

```bash
sume mcp doctor --json
```

Local `sume mcp` reports `coming_soon` / `launched: false` in current releases.
`sume mcp install` is not available yet.

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

## Machine-readable output

```bash
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

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

See [Agent skills](/cli/agent-skills).