CLI and Agent Skill

Add CC0 sound effects to a project from the terminal, Claude Code, Codex or Cursor. One command searches the catalog and downloads the sound file.

Add a sound in one command

The lotsofsounds CLI searches the catalog and downloads a sound into your project. All sounds are CC0, so you can ship them with no credit.

npx lotsofsounds search whoosh
npx lotsofsounds add fs-105016

add saves the file in public/sounds/ if the project has a public/ folder, else in sounds/. Use --dir and --name to change the folder and the file name.

Free to try, Pro to download

Search with no login returns free sample sounds. To search the full catalog and download sounds, log in with a Pro or Enterprise plan.

Log in

npx lotsofsounds login

The CLI shows a code and opens the browser. Sign in or sign up, check that the page shows the same code, and approve. The CLI saves an API key in ~/.config/lotsofsounds/config.json. Only your user can read this file.

If your account is on the Free plan, the approval page has an Upgrade to Pro button. After checkout, the page returns to the same login.

To use a key that you already have, set the LOTSOFSOUNDS_API_KEY environment variable. It takes priority over the saved key.

Commands

Command	What it does
`search <keywords>`	Find sounds. Options: `--limit`, `--category sfx\|music\|lofi\|ambient`, `--max-duration`, `--min-duration`, `--tags`
`add <id\|keywords>`	Download a sound. With keywords, it adds the best match. Options: `--dir`, `--name`
`info <id>`	Show the details of a sound
`login`	Sign in or sign up in the browser and save a key
`whoami`	Show the account and the requests used today
`logout`	Remove the saved key
`skill install`	Install the agent skill (see below)

Add --json to a command to get one JSON object. Search uses keywords, not sentences: whoosh, rain, ui click.

Use it with coding agents

Install the Lots of Sounds skill, and your agent knows when and how to add sounds:

npx lotsofsounds skill install

The command writes SKILL.md to ~/.claude/skills/lotsofsounds/ (Claude Code) and ~/.agents/skills/lotsofsounds/ (Codex and other Agent Skills clients). Use --project to install the skill into the current project, so your whole team gets it.

Then ask in plain words:

"Add a click sound to the buttons."
"The game needs jump, coin and game-over sounds."
"Play a short chime when the upload is complete."

You can read the skill at lotsofsounds.com/skill.md.

How an agent logs in

An agent cannot wait for a browser in one command, so the login has two steps:

npx -y lotsofsounds login --no-wait --json   # returns a url and a user_code
npx -y lotsofsounds login --wait --json      # waits for the approval

The agent gives you the link. You approve in the browser. The agent never sees your password, and you never paste a key into the chat.

Errors

Each error has a code and a next_step that the agent can repeat to you.

`code`	Meaning	What to do
`missing_api_key`	No login	Run `npx lotsofsounds login`
`invalid_api_key`	The key was revoked	Run `npx lotsofsounds login`
`plan_required`	The account is on the Free plan	Upgrade at /pricing
`rate_limited`	The daily limit is used	Wait for midnight UTC, or upgrade

Other ways to connect

MCP server for Claude, ChatGPT, Cursor and other MCP clients.
REST API for your own code.