How to run the Sume CLI in CI and on headless servers

To run the Sume CLI in CI or on a headless server, install a pinned release binary, pass an API key from your CI secret store as SUME_API_KEY or through sume auth setup --api-key, point SUME_CONFIG_DIR at a job-local directory, run sume doctor --agent --json as a preflight, and read every result with --json.

These steps come from the CLI docs on configuration, authentication, install and update, and security, read on 2026-09-26. The CLI still works, but the docs say it is not part of the primary path today: it is for local shells and scripts, not the default integration. Interactive install and login are in the CLI tutorial.

How do I pin the Sume CLI version in CI?

The hosted installer resolves the latest sumelabs/cli GitHub Release, so a pipeline that runs it can pick up a new version between builds. For a pinned install, use the direct-download fallback on Install and update and replace latest in its download URL with a specific release tag. Each GitHub Release attaches checksums.txt.

• Release assets: sume-darwin-arm64, sume-darwin-x64, sume-linux-arm64, sume-linux-x64, and sume-windows-x64.exe.
• Verify the install with sume version. sume update --check reports whether a newer release exists without modifying local files, so it can flag drift without upgrading anything.

How does the CLI authenticate without a browser?

Use an API key. The install docs keep manual API-key setup for CI and controlled server environments. Store a key from the API Keys dashboard in your CI secret store and expose it to the job as SUME_API_KEY, or run sume auth setup --api-key "$SUME_API_KEY" as a setup step.

sume login waits for the request to be approved on the device approval page, so it does not suit an unattended job. sume login --no-browser only prints the approval URL instead of opening a browser, which helps on a remote box you are logged into; the CLI tutorial covers that interactive flow.

How do I keep a CI job's config isolated?

By default the CLI keeps local configuration in ~/.sume-com/config.json. Set SUME_CONFIG_DIR to a directory the job owns, so parallel jobs and shared runners do not use one config file. Never print or commit SUME_API_KEY, the config file, or raw provider payloads.

# SUME_API_KEY is injected by the CI secret store
export SUME_CONFIG_DIR="$(mktemp -d)"
export SUME_API_BASE_URL="https://api.sume.com/v1"

sume version
sume doctor --agent --json
sume account get --json

What should a CI job check before it spends credits?

Start with the read-only checks the troubleshooting page lists: sume version, sume auth status, sume doctor --agent --json, and sume account get --json. doctor inspects local readiness without calling the API, and account get reads the account context for the configured key.

Write commands require confirmation flags, so a pipeline has to pass them itself: --confirm-submit for non-paid writes such as job cancellation, --confirm-paid for Avatar and Avatar Video runs that can reserve or spend credits. The docs' advice for agents fits pipelines too: submit one bounded job first when testing, and recover existing jobs instead of retrying paid commands.

How do I read CLI output in a pipeline?

Add --json for stable machine-readable output, and --agent when logs may contain sensitive URLs or account metadata: it redacts URL-like and account or workspace fields where supported.

• sume tools list --json and sume tools schema <name> --json discover exact schemas at runtime, so a job can validate a payload before a paid step.
• If a CI step restarts or a local wait times out, recover the job by id with sume jobs status and sume jobs result instead of resubmitting paid generation. sume jobs download <job_id> --output-dir ./out writes completed media artifacts into a local directory.
• Results can include first-party media URLs, which are public but still user data. When a job reports results, summarize media counts and file types and redact query strings instead of dumping raw payloads.

What can't the CLI do in a pipeline?

There is no sume image, sume video, or sume music subcommand. The CLI docs send those jobs to Image 1.0, Video 1.0, and Music 1.0 over HTTP, but Image 1.0 and Video 1.0 are retiring soon and Music 1.0 is retiring gradually. New integrations use POST /v1/images or POST /v1/videos with sume/auto, as the migration guide shows, or POST /v1/music-router/generate for music, and can still recover those jobs with sume jobs.

Schedules have no CLI command either: start a schedule run from CI with an HTTP call to POST /v1/actions/{action_id}/runs. For the full command list, see the Sume CLI commands reference.