How to generate avatar video from the terminal with the Sume CLI

The Sume CLI (sume) is an agent-first command-line wrapper over the api.sume.com/v1 Developer API. From a terminal it creates avatars and talking avatar videos with Avatar 1.0 and Avatar Video 1.0, then watches, fetches, and downloads the resulting jobs. Image 1.0, Video 1.0, and Music 1.0 have no CLI subcommand today: submit those over the API, and the CLI can still recover the job.

Commands and flags below are from the CLI overview and its pages on install, authentication, generation, jobs, agent skills, and security.

How do I install the Sume CLI?

The hosted installer is the recommended path, with the commands below. What it does, and how to update:

• It resolves the latest sumelabs/cli GitHub Release and downloads the binary for your OS and architecture.
• It verifies the binary against checksums.txt.
• It installs sume under ~/.sume-com/bin without silently overwriting a different sume already on your PATH.
• sume update --check reports whether a newer GitHub Release exists without modifying local files. Re-run the hosted installer when you choose to upgrade.

# macOS or Linux
curl https://cli.sume.com/install -fsS | bash

# Windows PowerShell
irm https://cli.sume.com/install.ps1 | iex

# Verify
sume version
sume doctor --agent --json
sume update --check

How do I sign in?

Run sume login, then sume auth status. The CLI opens the device approval page at www.sume.com/cli/login with a user_code, waits for approval, and stores a CLI-scoped API key in local config, ~/.sume-com/config.json by default. On a remote or headless machine, sume login --no-browser prints the approval URL instead of opening a browser.

For CI and server automation, set a key yourself with sume auth setup --api-key "$SUME_API_KEY", or with the SUME_API_KEY, SUME_API_BASE_URL, and SUME_API_AUTH_MODE environment variables. The CLI sends x-api-key by default, and SUME_API_AUTH_MODE=bearer switches it to Authorization: Bearer. Manual keys come from the API Keys dashboard; how Sume API keys work covers scopes and rotation.

Which generation commands does the CLI have?

Generation coverage is Avatar-heavy. Two families have first-class submit commands; the others are API-first, and the docs say not to invent CLI commands for them.

The hosted MCP server is a separate surface that does have generate_image, generate_video, and music_create tools. See how to connect it to Claude Code, Cursor, or Codex.

How do I make a talking avatar video from the terminal?

Read avatar handles with sume avatars list --agent --json, then submit with sume avatar-videos create, as in the example below. The API version of the same request is in talking avatar video from a script.

• --confirm-paid is required, because the command can reserve or spend credits.
• The script must estimate to 4-60 seconds inclusive. The CLI validates this before submission.
• --quality accepts standard, plus, or max, and defaults to plus, the same as the public API. The docs point to standard for speed and max when quality matters more than turnaround.
• To make a new avatar, sume avatars create takes --type prompt, --type photo, or --type props. --payload-json or --payload-file sends an exact request body.

sume avatar-videos create \
  --confirm-paid \
  --avatar-handle product_host \
  --product-image https://example.com/product.png \
  --script "Say hello to the Sume developer platform." \
  --quality plus \
  --json

How do I get the finished video?

Every submit command returns or prints a job id. When a process restarts or a local timeout occurs, recover the job with the commands below instead of resubmitting paid work.

• sume jobs watch polls until the job is terminal or the wait times out.
• sume jobs download writes completed media artifacts into a local directory.
• sume jobs cancel <job_id> --confirm-submit cancels a job.
• The same job commands work for Image, Video, and Music jobs you created over the API.

sume jobs status <job_id> --agent --json
sume jobs events <job_id> --agent --json
sume jobs result <job_id> --agent --json
sume jobs watch <job_id>
sume jobs download <job_id> --output-dir ./out

Can a coding agent run the Sume CLI safely?

The CLI is designed for agent use. Its docs recommend one loop: inspect the catalog and local readiness, validate the payload with a read-only schema command such as sume tools schema avatar-videos.create --json, ask for confirmation before writes or paid work, submit one bounded job, recover it through job commands, and summarize outputs without pasting secrets or signed URLs.

• --confirm-submit gates non-paid writes such as job cancellation or asset registration. --confirm-paid gates Avatar and Avatar Video generation.
• --json gives stable machine-readable output. --agent --json also redacts or summarizes URL-like fields and account or workspace details where supported.
• sume skills install writes the bundled Sume skill into .agents/skills or .claude/skills. sume skills export sume lets you review the files first.
• Never print or commit SUME_API_KEY, ~/.sume-com/config.json, or raw provider payloads. Result media URLs are public, but they are still user data.