Skip to main content
Use PyAI’s voice APIs directly from a terminal. Turn a script into a voiceover, get a transcript from a recording, or carry a Dub job through to its downloaded audio. Engineers and coding agents use the same commands and API contract.
The CLI is included in @pyai/sdk 0.5.0. It supports browser sign-in, saved profiles, and environment keys for coding agents and CI.

​
Install

Use Node.js 22 or newer for the recommended setup:
The compiled executable supports Node.js 18 or newer. Use pyai schema --json to inspect the installed command surface. See the full handbook for source builds and local packages.

​
Go from text to audio

With PYAI_API_KEY provided by your secret manager:
Need an isolated sandbox first? pyai auth sandbox -p sandbox creates an organization and saves its key privately. Reuse that profile for later work; each sandbox creation creates a separate organization. Review its returned scopes before selecting a product.
Use a voice ID returned by voices with --voice. Speech defaults to WAV; changing the extension does not change the audio format. Use --format for MP3, WAV, Opus, AAC, FLAC, PCM, or G.711 output. Transcription accepts a local path or an HTTP(S) URL as its positional input; a URL selects an asynchronous job, so add --wait when you need the finished transcript. Files written through --out are not overwritten unless you pass --force. Shell redirects such as > meeting.txt follow your shell’s overwrite behavior.

​
Sign in through the browser

On a deployment with browser authentication enabled:
The CLI displays a code and opens the console. Sign in with your existing email or Google login, match the code, select a project, and approve access. An owner or admin can approve a 30-day credential with the displayed scopes. The key is saved privately in your profile and never appears in the browser URL or login receipt. Revoke it through the console’s API Keys screen. For SSH or a container, use pyai login --no-browser -p remote. Open the printed link on another device and approve the matching code. The CLI polls outbound; no callback port or port forwarding is needed. Login requests expire after ten minutes; --login-timeout can shorten the local wait. Unattended CI and coding agents can use PYAI_API_KEY directly. To save an existing key without putting it in command arguments:
An exported PYAI_API_KEY overrides a stored profile’s key, including when -p is supplied. PYAI_BASE_URL and --base-url select a deployment. pyai logout -p work removes local credentials; it does not revoke the key server-side.

​
Dub through to a file

Check currently enabled source and target languages first:
When the language pair is listed and your key has dub:render:
This submits once, polls with a deadline, and downloads completed audio. The explicit job commands remain useful for separate CI stages or resuming work:
A wait timeout does not cancel the remote job. Inspect the job path returned in the error and resume waiting instead of blindly resubmitting.

​
Review API configuration as JSON

--data accepts inline JSON, @file.json, or @- for stdin. Dedicated mutations expect an object. --dry-run validates local input and shows the planned request without sending it. It does not prove remote authorization or server schema validity. Explicit delete and cancel commands do not prompt for terminal confirmation. The CLI also covers transcription jobs, cloned voices, voice design, Cast, Recap, Trace, tools, Hear vocabulary, and AMD configuration and call records. Discover exact flags with pyai GROUP --help or pyai help all.

​
Shortcuts that stay predictable

Use separate short options with a space before each value. pyai recipes shows an offline cookbook; pyai recipes speak narrows it to a task. Recipe names are auth, speak, transcribe, dub, agent, inspect, and ci. Displaying recipes makes no API calls.

​
Give a coding agent the right context

init creates a new directory containing PYAI.md and starter assets. The parent directory must exist. The default template is agent; creation is offline and does not install dependencies, save credentials, or call an API. Follow the generated README to run the starter. schema describes the installed CLI offline. Filter it to a command or group to give an agent only the syntax it needs. schema --openapi retrieves the configured deployment’s API contract. Use pyai request METHOD /PATH for routes without a dedicated command. API paths stay on the configured origin. Give your agent this instruction:
Read PYAI.md and inspect pyai schema --json. Fetch the live OpenAPI before constructing API bodies. Use PYAI_API_KEY without printing it. Discover voices, preview mutations with —dry-run, and use bounded waits. Return a runnable verification command and handle stable error codes.

​
Script output and failure handling

--json writes one command result to stdout and structured errors to stderr. Audio commands save bytes to a file and return a receipt with path, bytes, and content_type. --out - streams raw bytes and is incompatible with JSON. transcribe --text-only emits plain transcript text; URL jobs require --wait for text-only output. Large results may require reading the returned result_url. Branch on the error’s code, not its message. HTTP status, request_id, and job path are included when available. Browser login also emits public JSON events on stderr while waiting, so treat its stderr as newline-delimited JSON. --timeout defaults to 30 seconds per HTTP request, --wait-timeout to 120 seconds per wait, and --poll-interval to 2 seconds. Only reads are automatically retried; mutations are not retried. Idempotency support is determined by each API route. List commands return one page; continue with the returned next_cursor as --cursor. pyai doctor checks credentials, catalogs, and a Speak-to-Hear round trip; pyai smoke makes a smaller synthesis check. Both consume applicable API usage. Use --dry-run to inspect their request plans without calling the API.

​
Further reading

The CLI works with files, REST resources, and asynchronous jobs. Use the SDK for live microphone input, Hear streams, Omni conversations, and AMD streams.