CLI

Generate music, sound effects, and dubbing straight from your terminal. The sonilo command ships as an npm package and as a PyPI package — install whichever fits your setup.

Install

Both packages install the same sonilo executable. Pick one; installing both puts two binaries with the same name on your PATH.

Node

npm install -g sonilo-cli

# or run it without installing:
npx sonilo-cli account

Python

pip install sonilo-cli

Authenticate

The CLI reads your key from the environment. Every command also accepts --api-key if you need to override it for a single call.

export SONILO_API_KEY=sk-...

# or, per command:
sonilo account --api-key sk-...

Commands

Account and usage

# Plan limits, available services, and free-trial quota
sonilo account

# Usage summary (defaults to the last 30 days)
sonilo usage --days 7

Music

# Music from a text prompt
sonilo text-to-music --prompt "warm lo-fi piano, rain in the background" --duration 30

# Music matched to a video, written as WAV
sonilo video-to-music --video clip.mp4 --prompt "tense, driving synths" --output score.wav --format wav

# Music that changes style at timed points
sonilo video-to-music --video clip.mp4 \
  --segments '[{"start":0,"label":"intro","prompt":"soft solo piano"},{"start":20,"label":"chorus","prompt":"full orchestra"}]' \
  --output score.wav

Sound effects

# A sound effect from a text prompt
sonilo text-to-sfx --prompt "glass bottle shattering on concrete" --duration 3

# A sound effect matched to a video
sonilo video-to-sfx --video clip.mp4 --output foley.wav

# Different sound effects for different parts of the video
sonilo video-to-sfx --video clip.mp4 \
  --segments '[{"start":0,"end":4,"prompt":"footsteps on gravel"},{"start":4,"end":10,"prompt":"car door slam then engine starts"}]' \
  --output foley.wav

Music and sound effects together

# A music bed and sound effects for one clip, mixed into a single track
sonilo video-to-sound --video clip.mp4 \
  --music-prompt "tense strings" \
  --sfx-prompt "footsteps, distant thunder" \
  --output mix.wav

# Sound effects timed to specific moments, mixed with a music bed
sonilo video-to-sound --video clip.mp4 \
  --music-prompt "tense strings" \
  --segments '[{"start":0,"end":4,"prompt":"footsteps on gravel"},{"start":4,"end":10,"prompt":"car door slam then engine starts"}]' \
  --output mix.wav

# Same, but muxed back into the video
sonilo video-to-video-sound --video clip.mp4 --sfx-prompt "footsteps" --output scored.mp4

Dubbing

# Dub a video into other languages — one file is written per language
sonilo dubbing --video clip.mp4 --languages es,fr --output dubbed.mp4

Async tasks

# Fetch the current state of an async task
sonilo tasks get <task-id>

# Poll until it finishes
sonilo tasks wait <task-id>

Segments

Commands that accept --segments take a JSON array in any of three forms:

--segments '[{"start":0,"label":"intro","prompt":"airy pads"}]'   # inline JSON
--segments @segments.json                                          # from a file
--segments @-                                                      # from stdin

The shape of each item depends on the command:

music   { start, prompt, label? }   text-to-music, video-to-music
sfx     { start, end, prompt }      video-to-sfx, video-to-sound, video-to-video-sound

The CLI checks that each segment has the right shape before sending it; the API enforces the timing rules, so a 422 error comes from there — see the music or sound effect segments parameter for specifics.

Full option list

Every command documents its own flags — output paths, formats, durations, target languages, ducking and speech options.

sonilo --help
sonilo video-to-music --help

Source

View the Node CLI on GitHub View the Python CLI on GitHub