Sume CLI

Agent-first CLI for sume.so.

Sume CLI is a thin wrapper over the Sume public API. It works for humans in a terminal and for agents through normal shell commands: human output is concise, and --json returns structured output for automation. The CLI does not connect to Sume databases, Railway services, non-public Sume services, or internal routes.

Default API base:

https://www.sume.so/api/v1

Override it with SUME_API_BASE_URL or sume setup --base-url ... only when you are intentionally testing another public API base.

Install

For Linux and macOS:

curl https://cli.sume.so/install -fsS | bash

For Windows PowerShell:

irm https://cli.sume.so/install.ps1 | iex

Then start with:

sume login
sume me

The installer downloads the latest GitHub Release binary for your platform and verifies it with sume --version. To install a specific release:

SUME_VERSION=0.1.1 curl https://cli.sume.so/install -fsS | bash

To check for CLI updates later:

sume version
sume update --check
sume update

Setup

Browser login

sume login

sume login opens a browser approval page. After you approve access in Sume, the CLI stores a scoped Sume API key in ~/.sume/config.json with owner-only file permissions.

On remote machines or terminals without a browser:

sume login --no-browser --timeout 600

Open the printed URL/code on your local machine, approve access, then let the remote CLI finish polling. Treat login URLs/codes as temporary sensitive auth material and avoid pasting them into logs or reports.

For Hermes, Telegram, Modal, SSH, CI-like, or other agent-controlled remote/headless terminals, do not run the 600-second login waiter as a long foreground command. Start it in the background, read a short-lived log after a few seconds, show the URL/code only to the requesting user, then wait for completion after the user approves:

login_log="$(mktemp -t sume-login.XXXXXX.log)"
(sume login --device --timeout 600 >"$login_log" 2>&1; echo $? >"$login_log.status") &
login_pid=$!
sleep 4
sed -n '1,80p' "$login_log"

# After the user approves:
wait "$login_pid"
sume auth status --json
sume me --json
rm -f "$login_log" "$login_log.status"

If the agent environment cannot background the process or read its log, ask the user to run local sume login, provide SUME_API_KEY through an approved secret channel, or use a supported auth bridge.

Useful auth commands:

sume auth status
sume logout

API key setup

Environment variables override local config and are preferred for CI:

export SUME_API_KEY="sume_live_..."
export SUME_API_BASE_URL="https://www.sume.so/api/v1"

To store local defaults manually:

sume setup --api-key "$SUME_API_KEY"
sume setup --base-url "https://www.sume.so/api/v1"
sume setup --no-auto-update

Automatic background update checks are enabled by default for installed interactive binaries. Set SUME_NO_UPDATE=1 or run sume setup --no-auto-update to disable them. Manual sume update still works when background checks are disabled.

Commands

`me` and `credits` — Account context

sume me
sume credits
sume auth status

me shows the configured account and workspace. credits shows plan, credit, and active generation concurrency information for the API-key workspace.

`brand` — Analyze and read Brand DNA profiles

sume brand analyze https://example.com
sume brand analyze https://example.com --json
sume brand current
sume brand current --json
sume brand list --limit 5
sume brand list --domain example.com --json
sume brand get example.com --detail full

brand analyze starts or refreshes Brand DNA analysis for a public website URL. Use brand get <domain> --detail full or brand current --detail full to poll until the returned status is completed. brand list and brand current return compact public API summaries by default; full Brand DNA is available behind explicit detail/full calls. Human output summarizes URLs as availability/counts instead of printing full links.

Brand JSON includes images[] entries with role, source, url, reference_url, usable_as_reference, title, alt, and product_name. When usable_as_reference is true, pass reference_url to image generation:

sume images generate \
  --prompt "premium product ad using the brand reference" \
  --reference-image-url "https://media.sume.so/..." \
  --confirm-paid

Public video generation does not currently accept Brand image reference URLs through the CLI/API.

Option	Description
`--limit <n>`	Page size.
`--cursor <cursor>`	Pagination cursor from a previous response.
`--domain <domain>`	Filter list results by domain or website URL.

`avatars` — List usable avatars

sume avatars list --limit 5
sume avatars list --locale ko --limit 5
sume avatars get <avatar_id_or_slug>

Use avatar ids or slugs with ads videos create when creating talking-head or UGC ad video jobs. Human output summarizes media URLs as availability/counts instead of printing full links.

Option	Description
`--limit <n>`	Page size.
`--cursor <cursor>`	Pagination cursor from a previous response.
`--locale <locale>`	Preferred avatar label locale, such as `en` or `ko`.

`jobs` — List jobs and fetch results

sume jobs list --limit 5
sume jobs list --status completed --limit 5
sume jobs get <job_id>
sume jobs result <job_id>
sume jobs result <job_id> --agent --json
sume jobs result <job_id> --download ./outputs/
sume jobs watch <job_id> --timeout 180 --interval 5 --json

Option	Description
`--limit <n>`	Page size.
`--cursor <cursor>`	Pagination cursor from a previous response.
`--type <type>`	Filter jobs by type.
`--status <status>`	Filter jobs by status.
`--agent`	On `jobs result`, return a compact summary without media URLs.
`--redact-urls`	Alias for `--agent`.
`--download [path]`	On `jobs result`, download safe public media URLs from the result.

Use jobs watch --json for agent polling and jobs result <job_id> --agent --json for agent-safe result summaries. These return compact machine-readable objects with media URL counts instead of full output URLs. jobs watch --json returns a compact machine-readable job_watch object with stable state values such as queued, running, succeeded, failed, partial, and timeout; it does not return full output URLs.

`doctor` — Agent-safe local diagnostics

sume doctor --agent --json
sume doctor --agent --artifact-dir ./outputs --json

doctor --agent --json works without authentication and reports no-secret runtime facts for agents: CLI version, auth presence/source, public API base, basic platform info, writable working/artifact directories, and safe capability hints. It never prints API keys, tokens, device codes, or signed URLs.

`assets` — Search Asset Library scenes

sume assets list --limit 5
sume assets list --query "product demo" --limit 5
sume assets search "good hook videos" --source-type generated --limit 5
sume assets search "CTA videos" --source-type generated --limit 5
sume assets search "female camera-facing hook" --source-type generated --limit 5
sume assets search "product demo" --brand ASARAI --tag "application demo" --max-duration 15 --sort relevance
sume assets get <asset_id> --query "good hook videos" --search-mode <mode>
sume assets get <asset_id> --download ./assets/

Search returns indexed Asset Library scene assets scoped to the configured workspace. Search first, then use assets get for one scene when you need details or downloadable media metadata. Preserve search context with --query and --search-mode; add --search-score <score> only when the search result score is non-null. Do not pass 0 as a placeholder score. CLI users should use --query; q is only a deprecated API/tool-schema compatibility alias and is not a CLI flag.

Option	Description
`--limit <n>`	Page size.
`--cursor <cursor>`	Pagination cursor from a previous response.
`--search-mode <auto\|text>`	Search mode. `assets search` defaults to text search.
`--source-type <type>`	Filter by source video type, such as generated or upload.
`--segment-type <type>`	Filter by indexed scene segment type.
`--brand <brand>`	Filter by indexed brand mention.
`--product <product>`	Filter by indexed product mention.
`--tag <tag>`	Filter by reusable asset tag.
`--keyword <keyword>`	Filter by indexed search keyword.
`--cta-present <bool>`	Filter by CTA presence.
`--min-duration <seconds>`	Minimum scene duration.
`--max-duration <seconds>`	Maximum scene duration.
`--created-after <iso>` / `--created-before <iso>`	Filter by creation time.
`--sort <sort>`	`relevance`, `created_at_desc`, `created_at_asc`, or `duration_desc`.
`--query <query>` / `--search-mode <mode>`	On `assets get`, preserve relevance context from `assets search`.
`--search-score <score>`	Optional on `assets get`; include only when the search result score is non-null.
`--download [path]`	On `assets get`, download safe public media URLs from the asset.

Asset responses distinguish clip_url from source_media_url. clip_url is a scene-specific playable clip only when materialized; if it is missing, use source_media_url with the scene timestamps instead of pretending a clip URL exists. Redact full URLs and private identifiers when sharing logs.

`uploads` — Create upload targets

sume uploads presign --purpose asset_library_video --file-name source.mp4 --content-type video/mp4 --size-bytes 12000000 --json
sume uploads presign --purpose face_swap_source_video --file-name source.mp4 --content-type video/mp4 --size-bytes 12000000 --json
sume uploads asset-video --path ./source.mp4 --content-type video/mp4 --json
sume uploads face-swap-source --path ./source.mp4 --content-type video/mp4 --json
sume assets finalize --object-key <object_key> --file-name source.mp4 --content-type video/mp4 --size-bytes 12000000

Use uploads presign before uploading video bytes to Sume storage. The JSON response includes a temporary upload_url; treat it as sensitive. PUT bytes to that URL with upload_headers from the CLI response, or with required_headers plus the declared Content-Type header. Do not send the Sume API Authorization header to the storage URL. For Asset Library videos, upload the bytes to that URL, then run assets finalize with the returned object_key.

Prefer the higher-level helpers for local files when possible. They read one local file, send Content-Type correctly, and avoid printing signed upload URLs:

sume uploads asset-video --path ./source.mp4 --content-type video/mp4 --json
sume uploads face-swap-source --path ./source.mp4 --content-type video/mp4 --json

`assets finalize` — Start Asset Library processing

sume assets finalize --object-key <object_key> --file-name source.mp4 --content-type video/mp4 --size-bytes 12000000

assets finalize registers an uploaded video and starts Asset Library scene processing. Use assets list/search/get to inspect indexed scenes after processing completes.

`images` — Create image generation jobs

sume images generate --prompt "clean product photo of a white ceramic mug" --confirm-paid
sume images generate --prompt "product ad from reference" --reference-image-url "https://media.sume.so/..." --confirm-paid
sume images generate --prompt "clean product photo" --aspect-ratio 1:1 --n 1 --confirm-paid --wait
sume images generate --prompt "clean product photo" --confirm-paid --wait --download ./outputs/
sume images batch plan --manifest-path ./images.manifest.json --report-path ./images.plan.json --json
sume images batch create --manifest-path ./images.manifest.json --state-path ./images.state.json --confirm-paid --json
sume images batch watch --state-path ./images.state.json --json
sume images batch result --state-path ./images.state.json --json

Option	Description
`--prompt <prompt>`	Required image prompt.
`--aspect-ratio <ratio>`	Aspect ratio, for example `1:1`, `4:5`, or `9:16`.
`--n <count>`	Currently `1` only. Run separate jobs for multiple unique images.
`--resolution <resolution>`	Sume-supported image resolution.
`--quality <quality>`	Sume-supported image quality.
`--reference-image-url <url>`	HTTPS image reference URL. Repeat for multiple references.
`--confirm-paid`	Required after explicit approval before creating a paid job.
`--wait`	Poll until the job reaches a terminal state.
`--timeout <seconds>`	Wait timeout. Default: `600`.
`--download [path]`	Wait for the result and download safe public media URLs.

images batch plan is a local manifest validator for agents. It does not create jobs or spend provider credits. The legacy alias images batch --manifest-path is also plan-only. Use it to validate an images[] manifest and write an agent-readable plan/report before asking the user for explicit paid confirmation.

After approval, images batch create --confirm-paid creates one image job per ready manifest item using the same reliable public API path as images generate. The local --state-path file records the manifest hash and job ids, so rerunning create with the same state file skips already-created jobs instead of duplicating paid work. Use batch watch and batch result for aggregate JSON status. Batch results do not print media URLs by default; download local files with per-job jobs result <job_id> --download <dir> --json only when explicitly requested.

Batch create responses include per-item job ids, created/skipped actions, and attempt counts. When the public API returns numeric credit metadata, paid create/watch and result summaries include a reportable credit_summary; use that block for agent reports before falling back to before/after sume credits --json observations.

The current public API still supports one reliable image output per job.

Minimal manifest shape:

{
  "images": [
    {
      "id": "hero",
      "prompt": "Clean product photo on a white background",
      "aspect_ratio": "1:1",
      "reference_image_urls": ["https://media.sume.so/..."]
    }
  ]
}

`videos` — Create video generation jobs

sume videos generate --prompt "4 second product video of a white ceramic mug" --confirm-paid
sume videos generate --prompt "short product video" --duration 4 --resolution 480p --confirm-paid --wait
sume videos generate --prompt "short product video" --generate-audio --confirm-paid --wait

Option	Description
`--prompt <prompt>`	Required video prompt.
`--aspect-ratio <ratio>`	Aspect ratio, for example `9:16`.
`--duration <seconds>`	Duration in seconds.
`--resolution <resolution>`	Resolution, for example `480p` or `720p`.
`--generate-audio`	Ask Sume to generate audio if supported.
`--confirm-paid`	Required after explicit approval before creating a paid job.
`--wait`	Poll until the job reaches a terminal state.
`--timeout <seconds>`	Wait timeout. Default: `1800`.
`--download [path]`	Wait for the result and download safe public media URLs.

`ads` — Create Paid Ads video jobs

sume ads videos plan --script "Short product ad" --ad-format video --brand current --locale ko --duration 8 --resolution 720p --output-path ./ad-video.plan.json --json
sume ads videos create --plan-path ./ad-video.plan.json --confirm-paid --json
sume ads videos batch plan --manifest-path ./ad-videos.manifest.json --report-path ./ad-videos.plan.json --json
sume ads videos batch create --manifest-path ./ad-videos.manifest.json --state-path ./ad-videos.state.json --confirm-paid --json
sume ads videos batch watch --state-path ./ad-videos.state.json --json
sume ads videos batch result --state-path ./ad-videos.state.json --json
sume ads videos create --script "Introduce the product in one sentence" --ad-format talking_heads --avatar-slug <avatar_slug> --confirm-paid
sume ads videos create --script "UGC hook and product demo" --ad-format ugc_ads --avatar-id <avatar_id> --confirm-paid
sume ads videos create --script "Short product ad" --ad-format video --duration 8 --resolution 720p --confirm-paid --wait

ads videos plan is a local no-provider planning step for agents and does not spend credits. Use it for natural requests such as "make a video ad for our brand" or "우리 브랜드에 대해서 영상 광고 만들어보기", then ask for explicit paid authorization before ads videos create --plan-path ... --confirm-paid. ads videos create creates an async Paid Ads video job through the public API. Read status and results through jobs.

Use ads videos batch plan/create/watch/result for multi-variant requests such as "make 3 UGC ads" or "우리 브랜드로 UGC 5초짜리 3개 만들어봐". Batch plan is local and no-provider. Batch create is paid, writes a resumable state file, and skips already-created jobs on rerun.

Option	Description
`--script <script>`	Spoken copy or ad script.
`--plan-path <path>`	Reviewed plan JSON from `ads videos plan`.
`--confirm-paid`	Required after explicit approval before creating a paid job.
`--ad-format <format>`	`talking_heads`, `ugc_ads`, or `video`.
`--avatar-id <id>` / `--avatar-slug <slug>`	Avatar identifier from `sume avatars list`.
`--locale <locale>`	Output locale, such as `en` or `ko`.
`--duration <seconds>`	Duration in seconds.
`--aspect-ratio <ratio>`	Aspect ratio, for example `9:16`.
`--resolution <resolution>`	Resolution, for example `480p` or `720p`.
`--generate-audio`	Ask Sume to generate audio if supported.
`--reference-image-url <url>`	Currently unsupported for Paid Ads create; the CLI refuses before API/provider work.
`--prompt-reference-image-count <n>`	Number of prompt reference images to use when supported.
`--reference-audio-url <url>`	HTTPS audio reference URL. Repeat for multiple references.
`--reference-video-url <url>`	HTTPS video reference URL. Repeat for multiple references.
`--wait`	Poll until the job reaches a terminal state.
`--timeout <seconds>`	Wait timeout. Default: `1800`.

`face-swap` — Create Face Swap jobs

sume uploads face-swap-source --path ./source.mp4 --content-type video/mp4 --json
sume face-swap create --source-video-url "https://media.sume.so/..." --avatar-id <avatar_id> --duration 6 --aspect-ratio 9:16 --confirm-paid
sume face-swap create --source-video-url "https://media.sume.so/..." --avatar-id <avatar_id> --duration 6 --confirm-paid --wait

Face Swap requires a Sume media URL returned by uploads face-swap-source, or by uploads presign with purpose face_swap_source_video followed by a storage PUT that includes Content-Type: video/mp4. Read status and results through jobs.

Use only user-owned or explicitly permissioned source media. Do not use Face Swap for public figures, minors, or non-consensual identity changes. Creating Face Swap jobs can spend credits and requires explicit approval with --confirm-paid.

Option	Description
`--source-video-url <url>`	Sume media URL returned by `uploads face-swap-source` or presign.
`--source-file-name <name>`	Original source video file name.
`--avatar-id <id>`	Avatar id from `sume avatars list`. Repeat for multiple avatars.
`--duration <seconds>`	Trimmed source duration in seconds, 4 to 15 seconds.
`--trim-start <seconds>` / `--trim-end <seconds>`	Optional source trim range.
`--aspect-ratio <ratio>`	Aspect ratio, for example `9:16`.
`--locale <locale>`	Output locale, such as `en` or `ko`.
`--wait`	Poll the returned primary job until terminal.
`--timeout <seconds>`	Wait timeout. Default: `1800`.
`--confirm-paid`	Required after explicit approval and consent/safety review.

`reference-analysis` — Analyze public short-form references

sume reference-analysis create --url "https://www.instagram.com/reel/..." --confirm-paid
sume reference-analysis create --url "https://www.tiktok.com/@user/video/..." --locale en --confirm-paid --wait

Reference Analysis creates a job for a public TikTok or Instagram Reel URL. Read status and results through jobs. It can spend credits and requires explicit approval with --confirm-paid.

sume jobs get <job_id>
sume jobs result <job_id>

`tools` — Inspect local tool schemas

sume tools list --json
sume tools schema brand.current --json
sume tools schema brand.get --json
sume tools schema brand.analyze --json
sume tools schema avatars.list --json
sume tools schema avatars.get --json
sume tools schema images.generate --json
sume tools schema videos.generate --json
sume tools schema ads.videos.plan --json
sume tools schema ads.videos.create --json
sume tools schema face-swap.create --json
sume tools schema face-swap.create_from_local_source --json
sume tools schema assets.search --json
sume tools schema assets.finalize --json
sume tools schema uploads.presign --json
sume tools schema jobs.wait --json
sume tools schema uploads.asset_video --json
sume tools schema uploads.face_swap_source --json
sume tools schema jobs.download --json

Tool schemas are local descriptions of the public API operations the CLI wraps and local MCP workflow helpers such as jobs.wait, uploads.asset_video, and jobs.download. They also include MCP-only helpers such as face-swap.create_from_local_source. They include safety metadata and MCP execution metadata for read-only, mutating, paid/provider, and media-URL-returning calls, and are useful for agents before constructing commands.

`mcp` — Serve Sume tools to MCP clients

sume mcp
sume mcp --toolsets account,brand,avatars,jobs,assets,schemas
sume mcp --toolsets brand --allow-write
sume mcp --toolsets uploads --allow-write
sume mcp --toolsets downloads --allow-write
sume mcp --toolsets generation --allow-paid
sume mcp --toolsets ads,face-swap --allow-paid
sume mcp --toolsets face-swap --allow-write --allow-paid

sume mcp starts a local stdio MCP server from the same sume binary. It uses the existing CLI auth/config (SUME_API_KEY, SUME_API_BASE_URL, or sume login) and exposes read-only tools by default:

account.me
credits.get
brand.list, brand.current, brand.get
avatars.list, avatars.get
jobs.list, jobs.get, jobs.result
jobs.wait
assets.search, assets.get
tools.list, tools.schema

Mutating non-paid tools are available only when explicitly selected and opted in:

sume mcp --toolsets brand --allow-write
sume mcp --toolsets uploads --allow-write
sume mcp --toolsets downloads --allow-write

That exposes the selected read tools plus:

brand.analyze
uploads.asset_video
uploads.face_swap_source
jobs.download

uploads.asset_video accepts a local video path, content_type, and optional file_name. The MCP server reads only that supplied file path, creates the presign, PUTs bytes with the declared Content-Type, finalizes the Asset Library upload, and returns a sanitized asset summary. It does not return the temporary signed upload URL, storage object key, or upload headers. The current MCP implementation buffers the supplied file and rejects files over 512 MiB; use the normal uploads presign / assets finalize CLI flow for larger videos.

uploads.face_swap_source uploads a local Face Swap source video. Its sanitized MCP output does not reveal the intermediate media URL. For an MCP-only Face Swap from a local file, prefer face-swap.create_from_local_source with both --allow-write and --allow-paid; it uploads internally and creates the paid Face Swap job without exposing the intermediate media URL.

jobs.download accepts a job_id and explicit output_dir. It fetches only safe public media.sume.so result URLs, writes at most max_files files, and returns basenames/relative paths under the supplied output directory. It does not return remote URLs or absolute local paths.

Paid/provider tools are available only when explicitly selected and opted in:

sume mcp --toolsets generation --allow-paid
sume mcp --toolsets ads,face-swap --allow-paid

--toolsets generation --allow-paid exposes:

images.generate
videos.generate
reference-analysis.create

--toolsets ads,face-swap --allow-paid exposes:

ads.videos.create
face-swap.create

sume mcp --toolsets face-swap --allow-write --allow-paid also exposes:

face-swap.create_from_local_source

MCP inputs use JSON-native names such as query, domain, avatar_id, avatar_ids, job_id, asset_id, timeout_seconds, script, and source_video_url. The MCP platform layer maps public API aliases such as Asset Library query to the API's q parameter internally. Results are sanitized for agent use: emails, workspace/user ids, API keys, storage object keys, signed/private URLs, and full media URLs are redacted by default.

Example MCP client configuration:

{
  "mcpServers": {
    "sume": {
      "command": "sume",
      "args": ["mcp"],
      "env": {
        "SUME_API_KEY": "sume_live_..."
      }
    }
  }
}

Prefer environment variables or sume login/sume setup; do not pass API keys as command-line arguments.

`skills` — Manage agent skills

sume skills list
sume skills install sume
sume skills install sume-assets
sume skills install sume-brand
sume skills install sume-generation
sume skills install sume-ads
sume skills install sume-reference-analysis
sume skills install sume-tools
sume skills update
sume skills remove sume

Skills are installed from the public Sume skills registry:

https://cli.sume.so/skills/registry

The registry returns a file list and SHA-256 checksums. The CLI downloads each skill file, verifies the checksum, then writes the skill into the current project under .agents/skills/ when .agents/ exists, otherwise .claude/skills/ when .claude/ exists. If neither agent directory exists, create one first:

mkdir -p .agents
sume skills install sume

The selected skills directory also receives .installed.json, which sume skills update uses to re-fetch installed skills.

The sume skill is the top-level setup and routing guide. Focused skill packs are available for workflow-specific guidance:

Skill	Use for
`sume`	Setup, auth, update, tool discovery, safety rules, and workflow routing.
`sume-assets`	Asset Library search, uploads, downloads, and scene clip semantics.
`sume-brand`	Brand DNA read/analyze workflows and brand reference image handling.
`sume-generation`	Image/video generation, async jobs, results, and safe downloads.
`sume-ads`	Paid Ads video, avatars, Face Swap, and source-video boundaries.
`sume-reference-analysis`	Public Reel/TikTok reference analysis, polling, and result summaries.
`sume-tools`	MCP setup, schema discovery, skill refresh, and agent tool routing.

Advanced registry overrides:

SUME_SKILLS_URL="https://cli.sume.so/skills/registry"
SUME_SKILLS_API_URL="https://cli.sume.so/skills"

`init` — Install agent instructions

sume init
sume init --target all
sume init --target claude,cursor,agents-md
sume init --force

init is the convenience path for installing the default Sume guidance. The Claude skill target uses the same registry-backed installer as sume skills install sume; Cursor and AGENTS.md targets render from the same verified registry skill content.

In a blank project, create .agents/ or .claude/ before running the Claude skill target:

mkdir -p .agents
sume init --target claude

Target	Output
`claude`	`.agents/skills/sume/SKILL.md` when `.agents/` exists, otherwise `.claude/skills/sume/SKILL.md`. Requires one of those agent roots.
`cursor`	`.cursor/rules/sume.mdc`.
`agents-md`	A managed `<!-- BEGIN sume:sume -->` block in `AGENTS.md`.
`all`	All supported targets.

Commit the generated instruction files when you want teammates and agents to use the same Sume CLI workflow.

JSON and Automation

Pass --json whenever an agent or script will parse output:

sume me --json
sume credits --json
sume brand current --json
sume brand list --limit 5 --json
sume brand get example.com --detail full --json
sume brand analyze https://example.com --json
sume avatars list --limit 5 --json
sume avatars get <avatar_id_or_slug> --json
sume jobs list --limit 5 --json
sume assets search "product demo hook" --source-type generated --limit 5 --json
sume uploads presign --purpose asset_library_video --file-name source.mp4 --content-type video/mp4 --size-bytes 12000000 --json
sume images generate --prompt "clean product photo" --confirm-paid --wait --agent --json
sume ads videos create --script "short product ad" --ad-format video --confirm-paid --wait --json

The root command also exposes machine-readable CLI metadata:

sume --json

Agent workflow:

Authenticate with SUME_API_KEY or sume login.
Run sume tools list --json.
Inspect the relevant schema with sume tools schema <tool> --json.
Create jobs with --json, capture the job id, then poll with jobs get.
Fetch result summaries with jobs result --agent --json; use --download only when files are needed.

For MCP-capable clients, configure sume mcp when you want read-only account, credits, Brand DNA, avatars, jobs, Asset Library, and schema discovery tools without shell command parsing. Start the server with --toolsets downloads --allow-write only when the user has explicitly authorized writing result files to a local output directory. Start the server with --toolsets generation --allow-paid, --toolsets ads --allow-paid, or --toolsets face-swap --allow-paid only when the user has explicitly authorized those paid/provider workflows through MCP. Use --toolsets brand --allow-write only when the user has explicitly authorized starting or refreshing Brand DNA analysis through MCP, and --toolsets uploads --allow-write only when the user has explicitly authorized reading and uploading a local video file through MCP. jobs.wait uses a 5 second default poll interval and rejects intervals below 1 second.

For paginated responses, preserve next_cursor and pass it back with --cursor when continuing a list/search.

Output and Safety

Default output is compact human-readable terminal text.
--json emits structured JSON and keeps spinners/progress out of stdout.
The CLI never prints configured API keys.
Errors include API status, code, message, and request_id when present.
Download helpers only download safe public media URLs and skip URLs that look signed or private.
Upload presign JSON includes a temporary signed upload_url; it is not redacted because clients must use it for the next PUT. Treat it as sensitive, do not paste it into prompts, issues, or logs, and never send the Sume API Authorization header to that storage URL.
Generation commands can spend credits. Keep credit spend explicit.
Do not paste API keys, signed/private URLs, raw internal generation payloads, full media/result URLs, raw auth status output, account emails, workspace/user/API key ids, or private media into issues, prompts, logs, or PRs.

Update and Uninstall

Check and apply binary updates:

sume version
sume update --check
sume update

You can also re-run the installer to update to the latest release:

curl https://cli.sume.so/install -fsS | bash

Update installed agent skills separately:

sume skills update

Remove the released macOS/Linux install:

rm -rf ~/.sume/bin/sume ~/.local/bin/sume

On Windows, remove %LOCALAPPDATA%\sume\bin\sume.exe and remove that directory from your user Path if the installer added it.

Troubleshooting

`sume: command not found`

Open a new terminal after install. On macOS/Linux, make sure ~/.sume/bin or ~/.local/bin is on PATH.

No API key found

Run:

sume login

or set:

export SUME_API_KEY="sume_live_..."

Browser login on a remote machine

For a human-operated remote shell, use:

sume login --no-browser --timeout 600

Open the printed URL on a machine with a browser, approve access, then let the CLI finish polling.

For Hermes/Telegram/headless agents, use the background process-log pattern above instead of running the polling command in the foreground.

JSON for scripts

Use --json on the command that your script parses. For discovery, start with:

sume --json
sume tools list --json

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 102 Commits
.agents/skills		.agents/skills
.github		.github
agent		agent
src		src
test		test
web		web
.bun-version		.bun-version
.editorconfig		.editorconfig
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
THIRD_PARTY_NOTICES.md		THIRD_PARTY_NOTICES.md
bun.lock		bun.lock
install.ps1		install.ps1
install.sh		install.sh
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.json		tsconfig.json

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

Sume CLI

Install

Setup

Browser login

API key setup

Commands

me and credits — Account context

brand — Analyze and read Brand DNA profiles

avatars — List usable avatars

jobs — List jobs and fetch results

doctor — Agent-safe local diagnostics

assets — Search Asset Library scenes

uploads — Create upload targets

assets finalize — Start Asset Library processing

images — Create image generation jobs

videos — Create video generation jobs

ads — Create Paid Ads video jobs

face-swap — Create Face Swap jobs

reference-analysis — Analyze public short-form references

tools — Inspect local tool schemas

mcp — Serve Sume tools to MCP clients

skills — Manage agent skills

init — Install agent instructions

JSON and Automation

Output and Safety

Update and Uninstall

Troubleshooting

sume: command not found

No API key found

Browser login on a remote machine

JSON for scripts

License

About

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 25

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`me` and `credits` — Account context

`brand` — Analyze and read Brand DNA profiles

`avatars` — List usable avatars

`jobs` — List jobs and fetch results

`doctor` — Agent-safe local diagnostics

`assets` — Search Asset Library scenes

`uploads` — Create upload targets

`assets finalize` — Start Asset Library processing

`images` — Create image generation jobs

`videos` — Create video generation jobs

`ads` — Create Paid Ads video jobs

`face-swap` — Create Face Swap jobs

`reference-analysis` — Analyze public short-form references

`tools` — Inspect local tool schemas

`mcp` — Serve Sume tools to MCP clients

`skills` — Manage agent skills

`init` — Install agent instructions

`sume: command not found`

Packages