Synento docs
Guides

CLI guide

Manage projects and sessions from the terminal with the Synento CLI.

View as Markdown

The CLI covers login, creating a project, and creating a session.

Installation

The CLI is published on npm as @synento/cli and installs a synento command. Run it without installing:

npx @synento/cli --help

Or install it globally:

npm install -g @synento/cli
synento --help

It needs Node.js 18 or later.

Commands

synento login [apiKey] [--url <baseUrl>]

Store an API key for the other commands to use. Credentials are saved to ~/.config/synento/credentials.json. The key is not checked against the server here, only that it starts with sk_, so a mistyped key shows up on your next command.

Interactive:

synento login
# Prompts: API key (sk_live_...):

Non-interactive:

synento login sk_live_xxxxx

# Or via stdin (for scripting):
echo "sk_live_xxxxx" | synento login

Commands talk to the hosted API, https://api.synento.com, unless you pass --url or set SYNENTO_API_URL. The URL in effect when you log in is stored with the key.

synento create-project [name] [--env <environment>] [--url <baseUrl>]

Create a new project under your organisation. --env is development (the default), staging or production.

synento create-project "My App" --env production

synento create-session [name] -p|--project <projectId> [--url <baseUrl>]

Create a new session in a project. --project is required and must be the project your API key belongs to.

synento create-session "Team Standup" -p <projectId>

Output (printed to stdout):

Session created:
  ID:        5375d47394f938bf6560d230e0ae4d40
  Name:      Team Standup
  Project ID: undefined

The Project ID line currently prints undefined; the session is created in the project you passed. Always pass the session name as an argument: if you leave it out, the CLI prompts for one, and leaving that prompt empty can make it wait for further input instead of using the default name, Untitled session.

synento transcript <sessionId> [--format <format>] [--lang <lang>] [--request]

Print a session's transcript, or with --request transcribe a session that has ended (pass --language to set auto, multi or a BCP-47 tag). --format is text (the default, grouped by speaker), vtt, srt or json. See Transcripts.

synento transcript sess_abc123 --request
synento transcript sess_abc123 --format vtt > call.vtt

Credential storage

Credentials are stored in ~/.config/synento/credentials.json:

{
  "apiKey": "sk_live_xxxxx",
  "apiUrl": "https://api.synento.com",
  "lastLogin": "2026-01-01T12:00:00.000Z"
}

The file holds your full API key in plain text and is created with your default file permissions, which on most systems lets other users on the machine read it. Restrict it after logging in (chmod 600 ~/.config/synento/credentials.json) and never commit it.

Scripting examples

Create a session in a script

#!/bin/bash
echo "$SYNENTO_API_KEY" | synento login
PROJECT="<projectId>"
SESSION=$(synento create-session "Test Run" -p "$PROJECT" | awk '/ID:/ && !/Project/ {print $2}')
echo "Created session: $SESSION"

The CLI prints human-readable text, not JSON. For anything more than this, use the REST API or @synento/node, which return JSON.

Log in from a CI secret

# GitHub Actions: env: SYNENTO_API_KEY: ${{ secrets.SYNENTO_API_KEY }}
echo "$SYNENTO_API_KEY" | synento login --url https://api.synento.com

The CLI does not read SYNENTO_API_KEY by itself; pipe it into login as shown.

Limitations

The CLI currently covers logging in, creating projects and sessions, and transcripts. It does not list sessions, mint connection tokens or export recordings; use the REST API, @synento/node or the dashboard for those.

On this page