sume

name	sume
description	Use the Sume CLI, MCP server, and focused Sume skills safely. Use this overview skill for setup, auth, update, tool discovery, safety routing, and choosing between Sume Asset Library, Brand, generation, Ads, Reference Analysis, jobs, uploads, downloads, and schema tools.

Sume Skill Router

Sume CLI is a thin wrapper over the Sume public API. It does not access Sume databases, non-public Sume services, provider APIs, or internal routes directly.

Use this skill as the entry point. For specific workflows, install and use focused skills:

sume skills install sume-assets --json
sume skills install sume-brand --json
sume skills install sume-generation --json
sume skills install sume-ads --json
sume skills install sume-reference-analysis --json
sume skills install sume-tools --json

Core Rules

1. Use --json whenever an agent will parse CLI output.
2. Authenticate with SUME_API_KEY, sume login, or sume setup. In Hermes, Telegram, Modal, SSH, CI-like, or other remote/headless terminals, never run sume login --device --timeout 600 or sume login --no-browser --timeout 600 as a long foreground command. Use the background device-login workflow below.
3. Inspect structured tool contracts before creating requests: sume tools list --json and sume tools schema <tool> --json.
4. Prefer MCP for agent tool calls when available. Default sume mcp is read-only and sanitized.
5. Ask for explicit confirmation before any action that can spend credits, upload local files, write local downloads, or start mutating analysis.
6. Do not print API keys, signed/private URLs, full media/result URLs, storage object keys, auth headers, user emails, workspace/user ids, API key ids, or large raw responses.
7. Do not call Sume DBs, Railway services, private app routes, provider APIs, or internal endpoints.
8. Product-native Supercomputer tools remain Sume-controlled. Do not simulate private Supercomputer tools with internal routes.

Read references/safety.md when a task involves paid, write, upload, download, or sensitive media behavior.

Setup

sume --version
sume me --json

If sume me --json reports missing_api_key and the terminal is remote/headless, do not start a long foreground login waiter. In Hermes/Telegram especially, foreground polling can hide the URL/code until the command exits and can leak auth material into logs.

Use a short-lived process log and keep the login waiter in the background:

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"

Send the printed URL/code only to the requesting user as an actionable auth message, then wait for the user to say they approved it. After approval, finish the flow and verify auth:

wait "$login_pid"
sume auth status --json
sume me --json
rm -f "$login_log" "$login_log.status"

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

Do not ask the user to paste API keys into chat unless they explicitly choose manual key setup. Treat login URLs/codes as temporary sensitive auth material: show them only in the active auth flow, not in final reports, issue comments, PR bodies, persistent logs, or shared transcripts.

Use plain sume login only when the browser is available on the same machine as the CLI process.

Environment variables are also supported:

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

Remote sandboxes may persist ~/.sume/config.json in snapshots or reused home directories. For throwaway runs, use an ephemeral SUME_CONFIG_DIR or run sume logout after testing.

Tool Discovery

sume --json
sume tools list --json
sume tools schema assets.search --json
sume tools schema brand.current --json
sume tools schema images.generate --json
sume mcp --help

The schema registry is the source of truth for command inputs, safety flags, and MCP executability. Do not copy full schema tables into prompts.

Workflow Routing

Use sume-assets for:

• Asset Library search and retrieval.
• Scene clip versus source-video handling.
• Uploading local videos into Asset Library.
• Downloading safe public job or asset media.

Use sume-brand for:

• Reading Brand DNA.
• Starting or refreshing public website Brand analysis.
• Using brand image references with image generation.

Use sume-tools for:

• MCP setup and toolset selection.
• Schema discovery.
• Skill install/update behavior.
• Supercomputer or Hermes local agent wiring.

Use sume-generation for:

• Image and video generation.
• Async job polling and result handling.
• Paid generation safety and downloads.

Use sume-ads for:

• Paid Ads videos.
• Avatar discovery.
• Face Swap source-video and avatar workflows.

Use sume-reference-analysis for:

• Public TikTok or Instagram Reel analysis.
• Reference Analysis job creation, polling, and result summaries.

MCP Gates

Default sume mcp exposes read-only tools: account, credits, Brand read, avatars, jobs, Asset Library read, and schema discovery.

Use explicit gates for stronger actions:

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

Never make write or paid toolsets available by default.

Async Job Pattern

Most creation workflows return a job id. Use:

sume jobs get <job_id> --json
sume jobs result <job_id> --json

Use downloads only when the user wants files on disk:

sume jobs result <job_id> --download ./outputs/ --json

Do not curl media URLs yourself. Let CLI or MCP download helpers enforce safe URL rules.

Skill Maintenance

sume skills list --json
sume skills install sume --json
sume skills update --json
sume update --check --json

Hermes local experiments should refresh Sume skills from the same registry/source instead of maintaining a copied stale SKILL.md.

For future QA of these skills, see references/eval-scenarios.md.