---
title: "CLI | Raconte"
description: "Manage interviews and invitations from the terminal or an AI agent with @raconte/cli."
url: "https://raconte.ai/en/docs/cli"
---

# CLI

Manage interviews and invitations from the terminal or an AI agent with @raconte/cli.

`@raconte/cli` drives Raconte from a terminal or an AI agent. It wraps the same surface as the [REST API](/en/docs/api) and the [MCP server](/en/docs/mcp): create and manage **interviews** and **invitations**, authenticated with an organization API key. Every command prints JSON, so it scripts cleanly and an agent can parse it.

Want to hand the CLI to an AI agent? Point it at the ready-made skill: [raconte.ai/skill.md](/skill.md).

## Install

```bash
npm install -g @raconte/cli
```

Or run without installing:

```bash
npx @raconte/cli interviews list
```

Requires Node.js 20 or newer.

## Authentication

Create an organization API key from [Settings → API](/settings/api), then expose it:

```bash
export RACONTE_API_KEY="YOUR_API_KEY"
```

Every command reads `RACONTE_API_KEY`. You can also pass `--api-key <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, `3` auth failure (401/403), `1` any other failure.
*   Commands never prompt: they are deterministic and non-interactive.

## Rate limit

The API allows 300 requests per minute per API key, shared across every endpoint. Past it a command fails with `{ "status": 429, ... }` on stderr. Wait a minute before retrying, and prefer `invitations create-bulk` over a loop of `invitations create`.

## Commands

Run `raconte --help` or `raconte <group> <command> --help` for the authoritative list.

### Interviews

Command

Description

`interviews list [--archived]`

List interviews.

`interviews get <id>`

Get one interview.

`interviews create --prompt --locale --voice-id [...]`

Create an interview.

`interviews update <id> [...]`

Update an interview.

`interviews archive <id>`

Archive an interview.

`interviews restore <id>`

Restore an archived interview.

`interviews logs <id>`

Read activity logs.

`interviews regenerate-intro <id>`

Regenerate the AI intro message.

`interviews regenerate-first-message <id>`

Regenerate the AI first message.

### Invitations

Command

Description

`invitations list <interviewId>`

List the invitations of an interview.

`invitations get <invitationId>`

Get one invitation.

`invitations create <interviewId> [--name --email]`

Create an invitation. With no fields, returns a blank shareable invitation; name/email only pre-fill it and are not sent.

`invitations create-bulk <interviewId> --invitees '<json>'`

Bulk-create invitations and send each one right away.

`invitations update <invitationId> --name <name>`

Update the invitee display name. The email is not editable here (use `send`).

`invitations send <invitationId> --email <email>`

Send by email (sets the contact and dispatches).

`invitations cancel <invitationId>`

Cancel a ready invitation.

`invitations reactivate <invitationId> [--send-email]`

Reactivate a cancelled invitation, or reopen a completed one (it becomes reopened) so the invitee can resume it from their link. `--send-email` emails the invitee a resume link when reopening.

`invitations complete <invitationId>`

Mark a reopened invitation as completed: finalizes it, regenerates insights and clears the incomplete flag.

`invitations archive <invitationId>`

Archive an invitation.

`invitations restore <invitationId>`

Restore an archived invitation.

`invitations logs <invitationId>`

Read activity logs.

`invitations audio-url <invitationId> <messageId>`

Get a temporary audio URL for a transcript message.

**Just need a shareable link?** Run `invitations create <interviewId>` with no other field. It creates a READY invitation; the link to share is `https://raconte.ai/i/<slug>` (the `slug` is in the response). Anyone with the link can take the interview, and nothing is emailed. Changing a recipient’s email always sends (via `send`); `update` only changes the display name, so the contact is never altered silently.

### Share (reusable public link)

One reusable public link per interview, off by default. Unlike an invitation (one person, one transcript), each visitor who opens the link and submits the short pre-interview form gets their own invitation and transcript. The link is `https://raconte.ai/share/<slug>`.

Command

Description

`share get <interviewId>`

Get the reusable public link config (slug, url, form policy, limits, usage count). A disabled one is created on first access.

`share update <interviewId> [...]`

Enable the link, choose what the form asks, and set limits.

`update` accepts `--enabled` (`--no-enabled` to turn off), the per-field form policy `--ask-name` / `--ask-email` (each `off | optional | required`), and the limits `--max-interviews`, `--max-per-ip-per-day`, `--opens-at <iso>`, `--closes-at <iso>`, `--dedupe-by-contact` (`--no-dedupe-by-contact`), `--access-code`, and `--allowed-email-domains "acme.com,acme.fr"` (enforced only when `--ask-email` is required). Clear a nullable limit with `--data '{"maxInterviews": null}'`; pass an empty string to clear `--access-code` or `--allowed-email-domains`.

### Voices

Command

Description

`voices list [--language <code>]`

List the voices you pass as `--voice-id`. Public, no API key required.

`voices test-audio-url <voiceId>`

Get a short-lived preview audio URL for a voice. Public, no API key required.

Mutating commands also accept `--data '<json object>'` for the full request body. Explicit flags override its keys.

## Example

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

# Get a shareable link without sending anything
raconte invitations create "$ID" | jq -r '"https://raconte.ai/i/" + .slug'

# Or invite people directly (each is emailed right away)
raconte invitations create-bulk "$ID" \
  --invitees '[{"name":"Ada","email":"ada@example.com"},{"name":"Bo","email":"bo@example.com"}]'
```

## Programmatic use

Building a TypeScript or Node integration? Use the [SDK](/en/docs/sdk) (`@raconte/node-sdk`) instead of shelling out: the same surface as typed functions with Zod schemas.
