CLI guide
Manage projects and sessions from the terminal with the Synento CLI.
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 --helpOr install it globally:
npm install -g @synento/cli
synento --helpIt 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 loginCommands 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 productionsynento 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: undefinedThe 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.vttCredential 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.comThe 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.