Synento docs
Examples

CLI examples: common workflows

Scripts for login, projects, sessions, tokens, export, and bulk deletion with the Synento CLI.

View as Markdown

The CLI has three everyday commands: login, create-project and create-session. For anything else (tokens, exports, deletion) the scripts below call the HTTP API directly with the key the CLI stored.

Setup

# Install globally
npm install -g @synento/cli

# Or use npx (no global install needed)
npx @synento/cli --help

Login and authentication

Interactive login

Run the command. It will prompt for your API key:

synento login
# API key (sk_live_...): sk_live_abc123...
# Authenticated successfully. Credentials stored.

login saves the key without contacting the server, so a mistyped key is only reported by the next command (Error: invalid API key).

Non-interactive login (scripts/CI)

Pass the API key as an argument or via stdin:

# Via argument (recommended for scripts)
synento login sk_live_xxxxx --url https://api.synento.com

# Via stdin (piping from secure env storage)
echo "$SYNENTO_API_KEY" | synento login

The CLI does not read SYNENTO_API_KEY by itself. Pass it as above. It does read SYNENTO_API_URL, which overrides the stored API URL for every command.

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

{ "apiKey": "sk_live_xxxxx", "apiUrl": "https://api.synento.com", "lastLogin": "2026-10-09T15:02:27.069Z" }

Creating projects

The project is created in the organisation your API key belongs to.

Interactive mode

Prompts for the project name (the environment defaults to development):

synento create-project
# Project name: Acme Video Platform

Non-interactive mode

Provide all arguments inline:

synento create-project "Staging Environment" --env staging
#
# Project created:
#   ID:      b8bf8cee4bab3e8db501fcca360a0032
#   Name:    Staging Environment

--env is development (the default, stored as dev), staging, or production (stored as prod). The Free plan includes 3 projects; past that the command prints the plan's limit and exits non-zero.

An API key belongs to one project, so to create sessions in the new project, create an API key for it in the dashboard and synento login with that key.

Creating sessions

Sessions require a project ID (use -p or --project): the ID of the project your API key belongs to, shown in the dashboard:

synento create-session "Weekly Standup" -p 5e286c87114834912fd972164fc171b2
#
# Session created:
#   ID:        de77f69940426dc4be538a228b960845
#   Name:      Weekly Standup

Always pass a name. Run without one, the command prompts for it, but leaving the prompt empty currently exits without creating a session.

Automation scripts

Daily session creator

Create recurring sessions with the CLI in a cron job:

#!/bin/bash
# create-daily-standup.sh

PROJECT_ID="5e286c87114834912fd972164fc171b2"  # your project's ID
SESSION_NAME="Daily Standup — $(date +%Y-%m-%d)"

RESULT=$(synento create-session "$SESSION_NAME" -p "$PROJECT_ID" --url https://api.synento.com)

echo "Created session: $RESULT"

Connection token (via HTTP API)

The CLI has no token command. Mint a connection token for a session with the HTTP API:

API_KEY=$(node -p "require('$HOME/.config/synento/credentials.json').apiKey")

curl -s -X POST "https://api.synento.com/v1/sessions/SESSION_ID/connection" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "alice"}'
# → {"data":{"access_token":"eyJ…","expires_in":3600,"session":"SESSION_ID"},"error":null}

The browser SDK sends this token as a WebSocket subprotocol; see the Web Quickstart.

Session export script (via HTTP API)

The CLI doesn't have an export command, but you can call the API with the stored credentials. An export is a background job: start it, poll it, then download the MP4.

#!/bin/bash
set -euo pipefail

SESSION_ID="$1"

# Read the key and API URL the CLI stored at login
CRED_FILE="$HOME/.config/synento/credentials.json"
API_KEY=$(node -p "require('$CRED_FILE').apiKey")
API_URL=$(node -p "require('$CRED_FILE').apiUrl")
AUTH="Authorization: Bearer $API_KEY"

# 1. Start the export. The response is a job id, not the video.
JOB_ID=$(curl -sf "$API_URL/v1/sessions/$SESSION_ID/export" -H "$AUTH" |
  node -p "JSON.parse(require('fs').readFileSync(0, 'utf8')).data.job_id")

# 2. Poll until the job finishes
while true; do
  STATUS=$(curl -sf "$API_URL/v1/exports/$JOB_ID" -H "$AUTH" |
    node -p "JSON.parse(require('fs').readFileSync(0, 'utf8')).data.status")
  echo "Export $JOB_ID: $STATUS"
  [ "$STATUS" = "completed" ] && break
  [ "$STATUS" = "failed" ] && exit 1
  sleep 2
done

# 3. Download the MP4
curl -sf -o recording.mp4 "$API_URL/v1/exports/$JOB_ID/download" -H "$AUTH"
echo "Exported to recording.mp4 ($(du -h recording.mp4 | cut -f1))"

Each export's participant-minutes count toward your plan's export allowance (300 a period on both plans; past it, pay-as-you-go bills $0.004 per exported participant-minute); requesting the same export again returns the existing job instead.

Bulk session deletion (HTTP API)

The CLI doesn't support deletion. Use the HTTP API directly. Deleting a session erases its recording, exports and replay links, and cannot be undone, so this script only lists what it would delete until you set CONFIRM=yes:

#!/bin/bash
set -euo pipefail

DAYS="${DAYS:-7}"
CRED_FILE="$HOME/.config/synento/credentials.json"
API_KEY=$(node -p "require('$CRED_FILE').apiKey")
API_URL=$(node -p "require('$CRED_FILE').apiUrl")

# List the key's sessions and pick the ones older than $DAYS days
OLD_IDS=$(curl -sf "$API_URL/v1/sessions" -H "Authorization: Bearer $API_KEY" |
  DAYS="$DAYS" node -e "
const { data: sessions } = JSON.parse(require('fs').readFileSync(0, 'utf8'));
const cutoff = Date.now() - Number(process.env.DAYS) * 24 * 60 * 60 * 1000;
for (const s of sessions) {
  if (new Date(s.created_at).getTime() < cutoff) console.log(s.id);
}
")

for ID in $OLD_IDS; do
  if [ "${CONFIRM:-}" = "yes" ]; then
    curl -sf -X DELETE "$API_URL/v1/sessions/$ID" -H "Authorization: Bearer $API_KEY" > /dev/null
    echo "Deleted $ID"
  else
    echo "Would delete $ID (set CONFIRM=yes to delete)"
  fi
done

GET /v1/sessions returns up to 500 sessions per call; add ?offset=500 (and so on) to page through more.

Troubleshooting CLI commands

"Not authenticated" or connection errors

  • Error: Not authenticated. Run 'synento login' first. means no credentials file exists. Run synento login.
  • Check that the credentials file exists: cat ~/.config/synento/credentials.json
  • Verify the URL is reachable: curl -s https://api.synento.com/health (prints ok)
  • Use the --url flag to override for a single command

"invalid API key" or 401 errors

  • Ensure the API key starts with sk_ (login refuses anything else)
  • Check that the key has not been revoked in the dashboard
  • Try re-running synento login to refresh stored credentials

"project not found" or "forbidden"

  • The -p project ID must be the project your API key belongs to

On this page