Command reference

Use this page as a map of command groups. Use sume <command> --help and sume tools schema <tool> --json for exact local arguments.

Use --json on any command whose output will be parsed by an agent or script.

Command groups

Command	Purpose	Safety
`setup`	Save local API base/key/update configuration.	Writes local config.
`login` / `logout` / `auth status`	Authenticate or inspect auth.	Writes/removes local config for login/logout.
`me` / `credits`	Read account, workspace, plan, credits, and concurrency.	Read-only.
`brand`	Read or analyze Brand DNA profiles.	`brand analyze` mutates workspace Brand state.
`avatars`	List and inspect avatars.	Read-only, returns media metadata.
`jobs`	List jobs, inspect status, fetch/download results.	Read-only except local downloads.
`assets`	Search/get Asset Library scenes; finalize uploads.	Search/get read; finalize starts processing.
`uploads`	Create temporary upload URLs.	Mutating; returns sensitive signed upload URL.
`images` / `videos`	Create generation jobs.	Paid/provider mutation.
`ads`	Create Paid Ads video jobs.	Paid/provider mutation.
`face-swap`	Create Face Swap jobs from uploaded source video.	Paid/provider mutation.
`reference-analysis`	Analyze public TikTok/Instagram Reel URLs.	Paid/provider mutation.
`mcp`	Start local MCP stdio server.	Default read-only; write/paid toolsets require flags.
`tools`	Inspect CLI and MCP tool schemas.	Read-only local discovery.
`skills` / `init`	Install Sume agent skill instructions.	Writes local project files.
`version` / `update`	Inspect and update the binary.	`update` writes the local binary.

Remote/headless terminals should use:

On CI, prefer SUME_API_KEY.

Use these before generation to confirm the CLI is pointed at the expected account/workspace and has available credits.

brand analyze starts or refreshes workspace Brand DNA analysis for a public website URL. avatars is read-only.

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.

See Jobs and assets for the full workflow.

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.

uploads presign returns a temporary signed upload URL. Treat it as sensitive and do not send the Sume API Authorization header to storage.

Generation commands may spend credits. Confirm explicit user intent before running them from an agent.

Key options:

Command	Key options
`images generate`	`--prompt`, `--aspect-ratio`, `--n`, `--resolution`, `--quality`, `--reference-image-url`, `--wait`, `--timeout`, `--download`
`videos generate`	`--prompt`, `--aspect-ratio`, `--duration`, `--resolution`, `--generate-audio`, `--wait`, `--timeout`, `--download`

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.

If a blank project does not have .agents/ or .claude/, create one before installing Claude-style skills: