Authentication

Sume CLI needs a Sume API key before it can call the Public API. Use browser login for local terminals, device login for remote/headless terminals, and environment variables for CI.

Check auth state

Start every agent workflow with:

If no key is configured, the CLI returns a missing-key error with a hint for local, remote/headless, and environment-variable setup.

Browser login

For a normal local terminal:

The CLI starts a device authorization request, opens a browser approval page when possible, waits for approval, then stores a scoped API key in the local Sume config file.

Do not copy the printed login URL or code into shared logs. Treat them as temporary sensitive auth material.

Remote and headless login

Use this in SSH sessions, remote containers, Modal sandboxes, Hermes terminals, Telegram-mediated terminals, or any environment where a browser cannot open locally:

Aliases:

The CLI prints a URL/code and polls until the user approves in a local browser. After approval, verify:

Agent-safe remote login pattern

In an agent-controlled remote terminal, avoid blocking the terminal for ten minutes with a foreground login command. Start the waiter in the background, show the URL/code only to the requesting user, then wait after the user approves:

Do not paste API keys into agent chat unless the user explicitly chooses that credential path. Prefer the device login flow or a secret manager.

API keys and CI

Environment variables override local config:

Use SUME_API_KEY for CI, scheduled jobs, and non-interactive scripts. Avoid checking keys into repository files.

Manual local setup is also available:

Logout

Remove the locally stored API key:

If a sandbox image or Modal snapshot has captured a config file, run sume logout before snapshotting or use an isolated SUME_CONFIG_DIR for throwaway auth.

What is stored

The CLI stores local config under ~/.sume/config.json by default. The API key is encrypted with a machine-derived key when saved by sume login or sume setup, and the file is written with owner-only permissions on platforms that support them.

Set a separate config directory for disposable environments:

Common failures

Symptom	Fix
No Sume API key found	Run sume login, run sume login --no-browser --timeout 600, or set SUME_API_KEY.
Browser did not open	Re-run with --no-browser, --device, or --device-auth.
Login timed out	Re-run with a fresh URL/code. Device codes expire.
Wrong account/workspace	Run sume logout, then authenticate again.
CI hangs at login	Do not use interactive login in CI; set SUME_API_KEY.