Commands
Use --json on any command whose output will be parsed by an agent or script.
Auth and setup
sume login
sume login --no-browser
sume auth status
sume logout
sume setup --api-key "$SUME_API_KEY"
sume setup --base-url "https://www.sume.so/api/v1"
sume login opens a Sume approval page and stores a scoped local API key. On CI, prefer SUME_API_KEY.
Account and credits
sume me
sume me --json
sume credits
sume credits --json
Use these before generation to confirm the CLI is pointed at the expected account/workspace and has available credits.
Jobs
sume jobs list --limit 5
sume jobs list --status completed --limit 5
sume jobs list --type video_generation --cursor <next_cursor> --json
sume jobs get <job_id> --json
sume jobs result <job_id> --json
sume jobs result <job_id> --download ./outputs/
Options:
| Option | Description |
|---|---|
--limit <n> | Page size. |
--cursor <cursor> | Continue pagination. |
--type <type> | Filter jobs by type. |
--status <status> | Filter jobs by status. |
--download [path] | On jobs result, download safe public media URLs from the result. |
Assets
sume assets list --limit 5 --json
sume assets list --query "product demo" --limit 5 --json
sume assets search "mask application" --source-type generated --limit 5 --json
sume assets search "camera hook" --brand ASARAI --tag "application demo" --max-duration 15 --sort relevance --json
sume assets get <asset_id> --json
sume assets get <asset_id> --download ./assets/
Search options:
| Option | Description |
|---|---|
--limit <n> | Page size. |
--cursor <cursor> | Continue pagination. |
--query <query> | Search query for assets list. |
--search-mode <auto|text> | Public API search mode. |
--source-type <type> | Filter by source video type, such as generated or upload. |
--segment-type <type> | Filter by indexed scene segment role. |
--brand <brand> | Filter by brand mention. |
--product <product> | Filter by product mention. |
--tag <tag> | Filter by reusable tag. |
--keyword <keyword> | Filter by indexed keyword. |
--cta-present <bool> | Filter by CTA presence. |
--min-duration <seconds> / --max-duration <seconds> | Filter by scene duration. |
--created-after <iso> / --created-before <iso> | Filter by creation time. |
--sort <sort> | relevance, created_at_desc, created_at_asc, or duration_desc. |
--download [path] | On assets get, download safe public media URLs. |
Images
sume images generate --prompt "Clean product photo of a white ceramic mug"
sume images generate --prompt "Clean product photo" --aspect-ratio 1:1 --n 1 --wait --json
sume images generate --prompt "Clean product photo" --wait --download ./outputs/
Options include --prompt, --aspect-ratio, --n, --model, --resolution, --quality, --wait, --timeout, and --download.
Videos
sume videos generate --prompt "Four-second product video of a white ceramic mug"
sume videos generate --prompt "Short product video" --duration 4 --resolution 480p --wait --json
sume videos generate --prompt "Short product video" --generate-audio --wait
Options include --prompt, --aspect-ratio, --duration, --resolution, --generate-audio, --model, --wait, --timeout, and --download.
Reference Analysis
sume reference-analysis create --url "https://www.instagram.com/reel/..." --json
sume reference-analysis create --url "https://www.tiktok.com/@user/video/..." --locale ko --wait --json
Reference Analysis creates a job. Read status and results through jobs:
sume jobs get <job_id> --json
sume jobs result <job_id> --json
Tool schemas
sume tools list --json
sume tools schema account.me --json
sume tools schema credits.get --json
sume tools schema jobs.list --json
sume tools schema assets.search --json
sume tools schema images.generate --json
sume tools schema videos.generate --json
Tool schemas are local descriptions of the public API operations the CLI wraps. Agents should inspect schemas before constructing create commands.
Init agent instructions
sume init
sume init --target all
sume init --target claude,cursor,agents-md
sume init --force
Targets:
| Target | Output |
|---|---|
claude | .agents/skills/sume/SKILL.md when .agents/ exists, otherwise .claude/skills/sume/SKILL.md. |
cursor | .cursor/rules/sume.mdc. |
agents-md | A managed <!-- BEGIN sume:sume --> block in AGENTS.md. |
all | All supported targets. |