setup-api-key
Guides users through connecting to Sonilo — signing in with `sonilo login` (OAuth, no key), the remote OAuth Claude Code plugin, or an API key for CI and headless use. Use when the user needs to configure Sonilo, wants to sign in or connect their Sonilo account, when Sonilo tools are missing, or when a call fails because no key or credential is available. First checks what already works, and only runs full setup when needed.
sonilo-ai · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add sonilo-ai/skills --skill setup-api-key技能说明
name: setup-api-key
description: Guides users through connecting to Sonilo — signing in with sonilo login (OAuth, no key), the remote OAuth Claude Code plugin, or an API key for CI and headless use. Use when the user needs to configure Sonilo, wants to sign in or connect their Sonilo account, when Sonilo tools are missing, or when a call fails because no key or credential is available. First checks what already works, and only runs full setup when needed.
license: MIT
compatibility: Requires internet access to platform.sonilo.com and api.sonilo.com. Exact requirement depends on the chosen path — a CLI install plus a browser for sonilo login, claude mcp add//plugin install for MCP, or just pip/npm for the SDKs.
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:
| Path | Needs an API key? | Best for |
|---|---|---|
A. sonilo login (CLI sign-in, credential shared with the local MCP server) | No — OAuth in the browser | Anyone on a machine with a browser. One sign-in covers the CLI and uvx sonilo-mcp, so the MCP config carries no secret. |
B. Remote OAuth MCP plugin (sonilo-claude-plugin) | No — OAuth sign-in | Claude Code users who want nothing running locally. Full tool coverage. |
C. API key (SONILO_API_KEY) | Yes | CI, containers, headless boxes, and anyone who prefers holding a key. Works with every client. |
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 specifically, 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.
- MCP: is a
soniloMCP server connected (any Sonilo tool, e.g.text_to_musicorget_account_services, available to call)? If so, call the free, read-onlyget_account_services(). - 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 withsonilo 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 emptyaccount:line that reads like a broken credential. It is worth running only to show which account is active, never to decide. - Either one succeeds: Sonilo is configured and working. Say so and stop. Ask only whether they want to rotate credentials.
- 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 loginagain fixes it. Otherwise the key is wrong: continue at Path C. - 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 whoamishows which account and source is active;sonilo logoutrevokes the key server-side and then forgets it locally.- An exported
SONILO_API_KEYtakes precedence over the sign-in. If tools authenticate as an unexpected account, check for that variable first —sonilo whoamisays 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 only, 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 — s
阅读完整来源 ↗