Setup API Key

Sonilo Setup

Guide the user through connecting to Sonilo. There are several ways in — pick based on what the user is actually doing, not just whichever is listed first:

Choosing:

• On a machine with a browser and any MCP host → Path A. It is the shortest path and leaves no secret in a config file.
• Claude Code or Muse Code, and nothing local wanted → Path B.
• No browser (CI, a container, a remote box), or the user says they already have a key → Path C.
• Not working through an agent at all (writing code, scripting a shell) → Path D at the end; the MCP configuration in A–C does not apply.

Step 0: Check what already works (all paths)

Do this before changing anything — the answer is often "nothing to do".

There are two transports, and either one is enough. Probe both before concluding that nothing is set up.

1. MCP: is a sonilo MCP server connected (any Sonilo tool, e.g. text_to_music or get_account_services, available to call)? If so, call the free, read-only get_account_services().
2. CLI: if there are no Sonilo tools, run sonilo account — the same free, read-only call as above. Exit code 0 means the CLI is installed, signed in, and reaching the API, and the skills can drive it directly. Do not probe with sonilo whoami: it exits 0 even when signed out, so it cannot separate the two states, and on an account with no display name it prints an empty account: line that reads like a broken credential. It is worth running only to show which account is active, never to decide.
3. Either one succeeds: Sonilo is configured and working. Say so and stop. Ask only whether they want to rotate credentials.
4. Fails with 401: authentication is stale, not missing. If they signed in with sonilo login, the key may have expired (90 days) or been revoked — sonilo login again fixes it. Otherwise the key is wrong: continue at Path C.
5. Neither responds: nothing is connected — pick a path below and run it. MCP is the better default (it needs no shell, and it is the only transport that survives a dubbing job's two-hour poll), but a CLI that is installed and signed in is a complete setup on its own; do not make someone configure MCP they will not use.

Never print, quote, or echo a key or the contents of the credential file. If you must refer to one, redact it.

Path A: sonilo login (no API key, any MCP host)

One sign-in, then both the CLI and the local MCP server are authenticated — the CLI writes a credential to ~/.config/sonilo/credentials.json and sonilo-mcp (0.16.0 and later) reads it.

npm install -g sonilo-cli     # or: pip install sonilo-cli
sonilo login

The CLI prints a one-time code and opens the browser to platform.sonilo.com. The user signs in to their Sonilo Platform account (separate from a consumer sonilo.com account), confirms the code matches what the terminal printed, and approves. On a machine without a browser, add --no-browser and have them approve the printed URL from another device.

Then add the MCP server with no secret in the config:

claude mcp add sonilo -- uvx sonilo-mcp     # Claude Code
codex mcp add sonilo -- uvx sonilo-mcp      # Codex

For Claude Desktop, the whole config is:

{
  "mcpServers": {
    "sonilo": { "command": "uvx", "args": ["sonilo-mcp"], "env": {} }
  }
}

Both need the uv package manager (provides uvx): install it with brew install uv (macOS), pipx install uv / pip install uv, or winget install --id=astral-sh.uv (Windows) — other methods at https://docs.astral.sh/uv/getting-started/installation/.

Worth telling the user up front:

• Approving mints an ordinary API key on their account, named cli: <hostname>, that expires after 90 days and is visible and revocable at https://platform.sonilo.com/dashboard/api-keys.
• sonilo whoami shows which account and source is active; sonilo logout revokes the key server-side and then forgets it locally.
• An exported SONILO_API_KEY takes precedence over the sign-in. If tools authenticate as an unexpected account, check for that variable first — sonilo whoami says so explicitly when it is set.
• Sign-in is for humans. Provisioned/POC accounts are issued a key by Sonilo and cannot use sonilo login; those users belong on Path C.

Validate with get_account_services(), exactly as in Step 0.

Path B: Remote OAuth plugin (Claude Code or Muse Code, no API key)

claude
/plugin marketplace add sonilo-ai/sonilo-claude-plugin
/plugin install sonilo@sonilo

The first Sonilo tool call opens the browser to sign in to a Sonilo Platform account (platform.sonilo.com — separate from a consumer sonilo.com account) and approve access. Claude Code stores the resulting token per-user in the OS keychain; nothing to copy, paste, or configure. Review or disconnect anytime from /mcp.

This connects to a single hosted endpoint (https://api.sonilo.com/mcp, OAuth 2.1 + PKCE) that carries the same tool set as the local server (Paths A and C): music/SFX from text or video, video-to-video music/SFX, video-to-sound, video-to-video-sound, dubbing, audio ducking, and account/usage. Paths A and C are still the better fit for other MCP hosts, or for users who prefer holding and managing their own key.

Muse Code: the Sonilo skills plugin carries the same hosted server, so installing it is the whole setup:

MUSE_EXPERIMENTAL_PLUGINS=1 muse plugins marketplace add sonilo-skills https://github.com/sonilo-ai/skills
MUSE_EXPERIMENTAL_PLUGINS=1 muse plugins install skills@sonilo-skills
MUSE_EXPERIMENTAL_PLUGINS=1 muse plugins approve skills

approve activates the MCP server (Muse keeps a third-party plugin's server off until then). The first Sonilo tool call asks for the same Sonilo Platform sign-in. If a call reports that the server needs an OAuth sign-in, add "mcp_servers": {"sonilo": {"transport": "streamable_http", "url": "https://api.sonilo.com/mcp"}} to ~/.config/muse/settings.json and run muse mcp login sonilo — Muse Code 1.4.0 only logs in to servers listed there.