Overview

Sume CLI is the local command-line interface for Sume. It is built for humans, automation scripts, and agents that need a structured way to call Sume without using internal services.

The CLI is intentionally thin:

• It calls Sume Public API v1.
• It uses the API-key workspace resolved by Sume.
• It supports human output and stable --json output.
• It can start a local MCP stdio server from the same binary.
• It can install Sume agent skill packs into local projects.
• It does not connect to Sume databases, Railway services, provider APIs, or internal routes.

Default API base:

What the CLI is for

Use the CLI when you want to:

• check account, workspace, and credit state;
• list jobs and fetch job results;
• search Asset Library scenes;
• create image, video, Paid Ads, Face Swap, or Reference Analysis jobs;
• upload videos into Asset Library or Face Swap flows;
• expose Sume tools to MCP clients;
• install Sume skill guidance into coding-agent projects.

Quick install

Then authenticate and verify:

Remote, SSH, Hermes, Modal, and other headless terminals should use the device flow instead:

See Authentication for the full remote-agent pattern.

Common read-only workflow

Read-only commands are safe starting points for agents. They still may return media metadata or public media URLs, so redact full URLs and private identifiers when copying results into chat or logs.

Common generation workflow

Generation commands can spend credits or create provider work. Agents should confirm user intent before running them.

CLI docs

Page	Use it for
Install and update	Installer, version checks, binary updates, and release behavior.
Authentication	Browser login, remote/headless login, API keys, and logout.
Configuration	Config files, environment variables, update settings, and API base overrides.
Command reference	Top-level commands and safe command examples.
Jobs and assets	Async job polling, result download, Asset Library search, uploads, and finalize.
Generation workflows	Image, video, Paid Ads, Face Swap, and Reference Analysis workflows.
MCP server	sume mcp, toolsets, write/paid gates, and MCP-only helpers.
Agent skills	sume init, sume skills, skill packs, and agent guidance.
Troubleshooting	Missing keys, remote login, downloads, updates, jobs, and MCP startup.
Security	Secrets, signed URLs, paid calls, and automation safety rules.

Public API relationship

CLI commands map to the Public API. Use the CLI for shell and agent workflows. Use the Public API directly for server integrations that need their own HTTP client, retry policy, or deployment environment.

For exact API shapes, see:

• API reference
• API cookbook
• /api/openapi.json

Agent mode

Use --json whenever another program will parse output:

Agents should summarize output and redact:

• API keys;
• login URLs and temporary user codes;
• signed upload URLs;
• storage object keys;
• full private or signed media URLs;
• user, workspace, and API key ids unless strictly needed for debugging.

Release note

These docs describe the current SumeLabs/sume-cli release line around v0.1.11 and the merged source on main. If a command appears in source but your installed binary does not recognize it, run sume update --check and see Install and update.