# CLI `@scriptivox-api/cli` is the official command-line client for the Scriptivox transcription API. It transcribes recorded audio and video from a shell or a script — 119 languages, speaker diarization, word-level timestamps, and SRT / WebVTT / plain-text export. It is a peer of the [MCP server](/docs/mcp): same API, different transport. Use the CLI when a human or a shell script is driving; use MCP when a model is. **npm:** [`@scriptivox-api/cli`](https://www.npmjs.com/package/@scriptivox-api/cli) · **Command:** `scriptivox-api` --- ## Install ```bash npm install -g @scriptivox-api/cli # or run it without installing npx @scriptivox-api/cli --help ``` Node 18 or newer. **Zero runtime dependencies** — nothing is pulled in at install time beyond the package itself. ## Authenticate Create a key at [/keys](/keys) and add credit at [/billing](/billing). ```bash export SCRIPTIVOX_API_KEY=sk_live_... ``` Or pass `--api-key` per command. See [Authentication](/docs/authentication) for the header details the CLI handles for you. > **The API is billed separately from the web app:** > A subscription on [scriptivox.com](https://www.scriptivox.com) grants no API credit. API usage draws down a prepaid balance at $0.20 per hour of audio. That is why the package is `@scriptivox-api/cli` and the command is `scriptivox-api` rather than `scriptivox` — the name is a reminder of which product you are spending. ## Commands Every command maps one-to-one onto an operation in the [OpenAPI specification](/openapi.json). ```bash # Transcribe a public URL and wait for the result scriptivox-api transcribe https://example.com/meeting.mp3 --language en --diarize --wait # Upload a local file, transcribe it, wait scriptivox-api transcribe ./interview.m4a --diarize --speakers 2 --wait # Export captions — stdout is clean, progress goes to stderr scriptivox-api get 4f3c... --format srt --max-words 3 > interview.srt scriptivox-api get 4f3c... --format vtt --speakers-in-captions true > interview.vtt # Inspect and manage jobs scriptivox-api status 4f3c... scriptivox-api list --status completed --limit 20 --json scriptivox-api cancel 4f3c... scriptivox-api delete 4f3c... # Check the balance scriptivox-api balance ``` `scriptivox-api --help` lists every flag. ## Scripting Structured output goes to **stdout**, progress and diagnostics to **stderr**, so a redirect produces a clean file even while the command is reporting status. `--json` puts JSON on stdout and silences progress entirely. Exit codes are part of the contract: | Code | Meaning | | --- | --- | | `0` | Success | | `1` | Usage error — bad arguments, missing API key, unreadable file | | `2` | API error — the machine-readable error code is printed on stderr | ```bash if ! scriptivox-api transcribe ./call.mp3 --wait --json > result.json; then echo "transcription failed with exit $?" >&2 fi ``` The exit-code contract is guarded by an offline test suite that never touches the network, so a refactor cannot quietly change a code that scripts depend on. ## Things worth knowing - **`transcribe` returns before the work is done.** Without `--wait` you get a job ID; input problems — unreachable URL, unsupported media, audio too long — surface *later* on `status`, as `status: failed` with an `error.code`. Check the poll path, not just the submit call. - **Pass `--language` when you know it.** Auto-detection works most of the time but mis-routes short clips, code-switched audio, and files that open with music. It is also faster, because the model skips its detection pass. - **`--speakers` needs `--diarize`.** It is a prior, not a hard cap: asking for 5 may yield 6. - **Failed and cancelled jobs are free.** The reserved balance is released. - **`--idempotency-key` makes retries safe.** The same key with the same body replays the cached response for 24 hours instead of starting a second, separately-billed job. ## Scope The CLI talks to `https://api.scriptivox.com/v1` and nothing else. There is no session login, no cookie handling, and no access to the web app or the developer dashboard — an `sk_live_…` key is the only credential it understands. MIT licensed. Bug reports and feature requests: [support@scriptivox.com](mailto:support@scriptivox.com).