--- name: raconte description: Run AI voice interviews from the terminal, a script, or an AI agent with the Raconte CLI (@raconte/cli). Use it when you want to create an interview from a prompt, invite participants by email or SMS (or generate a shareable link), send and track invitations, bulk-invite a list of people, or read interview transcripts and per-message insights, without opening the web app. Also the right tool to automate interview workflows in CI/scripts or to let an agent operate Raconte over the API with one command. homepage: https://raconte.ai --- # Raconte CLI `@raconte/cli` drives [Raconte](https://raconte.ai), AI-run voice interviews, from a terminal or an AI agent. You craft a prompt, send a link, the AI runs a natural voice conversation, and you get transcripts and insights. The CLI wraps the public Raconte REST API. Every command authenticates with an organization API key and prints JSON, so it is safe to script and easy for an agent to parse. ## Install Global (provides the `raconte` command everywhere): ```bash npm install -g @raconte/cli ``` Or run without installing: ```bash npx @raconte/cli interviews list ``` Requires Node.js 20 or newer. ## Authenticate Create an organization API key in **Settings, API** on raconte.ai, then expose it as an environment variable: ```bash export RACONTE_API_KEY="your-key" ``` Every command reads `RACONTE_API_KEY`. You can also pass `--api-key ` per call. ## Output and exit codes - All output is JSON on stdout. Pipe it to `jq` or parse it directly. - Errors are JSON on stderr: `{ "status": , "error": }` for API errors, `{ "error": }` for transport or usage errors. - Exit codes: `0` success, `2` usage error (bad argument, missing key, invalid JSON), `3` auth failure (401/403), `1` any other failure. - Commands never prompt. They are deterministic and non-interactive. ## Commands Run `raconte --help`, `raconte interviews --help`, or `raconte --help` for the authoritative, up-to-date list. ### Interviews | Command | Description | | --- | --- | | `raconte interviews list [--archived]` | List interviews (active, or archived only). | | `raconte interviews get ` | Get one interview. | | `raconte interviews create --prompt --locale

 --voice-id  [...]` | Create an interview. |
| `raconte interviews update  [...]` | Update an interview. |
| `raconte interviews archive ` | Archive an interview. |
| `raconte interviews restore ` | Restore an archived interview. |
| `raconte interviews logs ` | Get the activity logs. |
| `raconte interviews regenerate-intro ` | Regenerate the AI intro message. |
| `raconte interviews regenerate-first-message ` | Regenerate the AI first message. |

`create` accepts `--prompt` (10 characters minimum), `--locale` (e.g. `en`, `fr`) and `--voice-id` as the core fields, plus optional `--title`, `--intro`, `--first-message`, `--email`, `--phone`, and `--invitees ''` to send to several people at once. Find a `--voice-id` with `raconte voices list`.

`update` accepts `--title`, `--prompt`, `--intro`, `--first-message`, `--locale`, `--voice-id`, `--max-minutes` (maximum minutes per call, silence is not counted), `--max-responses` (maximum guest messages before the interview stops), and `--disable-org-system-prompt`.

### Invitations

| Command | Description |
| --- | --- |
| `raconte invitations list ` | List the invitations of an interview. |
| `raconte invitations get ` | Get one invitation. |
| `raconte invitations create  [--name --email --phone]` | Create an invitation. With no fields, returns a blank shareable invitation (a link); name/email/phone only pre-fill it and are not sent. |
| `raconte invitations create-bulk  --invitees ''` | Bulk-create invitations and send each one right away. |
| `raconte invitations update  --name ` | Update the invitee display name. Email and phone are not editable here (use `send`). |
| `raconte invitations send  [--email --phone]` | Send by email or SMS (sets the contact and dispatches). |
| `raconte invitations cancel ` | Cancel a ready invitation. |
| `raconte invitations reactivate ` | Reactivate a cancelled invitation. |
| `raconte invitations archive ` | Archive an invitation. |
| `raconte invitations restore ` | Restore an archived invitation. |
| `raconte invitations logs ` | Get the activity logs. |
| `raconte invitations audio-url  ` | Get a temporary audio URL for a transcript message. |

**Getting a shareable link without sending anything:** `raconte invitations create ` with no other field creates a READY invitation and returns it. The link to share is `https://raconte.ai/invitation/`, where `` is the `slug` field of the response. Anyone with that link can take the interview; no email or SMS is sent. To deliver by email or SMS instead, use `invitations send` (or pass `--email`/`--phone` to `create` to pre-fill, then `send`).

To change a recipient's email or phone you always send: there is no way to alter contact details silently. `update` only changes the display name.

### Voices

| Command | Description |
| --- | --- |
| `raconte voices list [--language ]` | List the voices you can pass as `--voice-id`. Public, no API key required. |
| `raconte voices test-audio-url ` | Get a short-lived preview audio URL for a voice. Public, no API key required. |

Mutating commands also accept `--data ''` for the full request body. Explicit flags override keys from `--data`.

## Examples

Pick a voice, then create an interview and capture its id:

```bash
VOICE=$(raconte voices list --language en | jq -r '.[0].id')
ID=$(raconte interviews create \
  --title "Onboarding feedback" \
  --prompt "Ask the user about their first week, follow up on friction points." \
  --locale en \
  --voice-id "$VOICE" | jq -r '.id')
```

Get a shareable link without sending anything:

```bash
raconte invitations create "$ID" | jq -r '"https://raconte.ai/invitation/" + .slug'
```

Invite several people in one call (each is emailed or texted right away):

```bash
raconte invitations create-bulk "$ID" \
  --invitees '[{"name":"Ada","email":"ada@example.com"},{"name":"Bo","phone":"+33600000000"}]'
```

Read an interview's invitations and their statuses:

```bash
raconte invitations list "$ID" | jq '.[] | {id, status, recipientEmail}'
```

## Programmatic use

For TypeScript or Node apps, use the SDK instead of shelling out: [`@raconte/node-sdk`](https://raconte.ai/en/docs/sdk) exposes the same surface as typed functions with Zod schemas.

## Reference

- Product docs: https://raconte.ai/en/docs
- REST API reference: https://raconte.ai/en/docs/api
- MCP server (for MCP-native agents): https://raconte.ai/en/docs/mcp