livqenoDocs

SDKsCLI

CLI

Manage projects and keys, and inspect rooms, chat and streams from your terminal or CI.

@livqeno/cli is for you, the developer, working in a terminal or in CI. It's not part of your app, and your users never run it.

Use it to:

  • Set up: create projects and API keys without opening the dashboard.
  • Debug: see who's in a room right now, why a user's connection failed, or whether chat is healthy.
  • Automate: script the same things in CI, with --json output and stable exit codes.

Think of it as the dashboard, in your terminal. It can do what you can do in the dashboard, and nothing more.

Install

Terminal
npm install -g @livqeno/cli

Or run it without installing. This is best for CI:

Terminal
npx @livqeno/cli projects list

Point it at Livqeno

Do this once, before anything else. Out of the box the CLI talks to http://localhost:4100, a local development API. Point it at the hosted API:

Terminal
livqeno config set apiUrl https://api.livqeno.com

LIVQENO_API_URL does the same for one command or one CI job, without writing the config file. It wins over the saved value.

Authenticate

The CLI needs to know who you are. There are two ways, depending on where it runs.

On your own computer

Terminal
livqeno login

This opens your browser and uses your dashboard login. Nothing to paste.

The login page is on the dashboard. The CLI works out its address from the API URL: https://api.livqeno.com opens https://app.livqeno.com, and a local http://localhost:4100 opens http://localhost:3001. For any other setup, set LIVQENO_DASHBOARD_URL to the dashboard's address.

In CI, a container, or over SSH

There's no browser there, so set an environment variable instead. Nothing is saved to disk.

Terminal
export LIVQENO_TOKEN="$YOUR_SESSION_TOKEN"
export LIVQENO_API_URL="https://api.livqeno.com"  # required: the default is localhost
 
livqeno projects list --json

How to get a token: it's the session token from your dashboard login.

  1. Run livqeno login once on a computer with a browser.
  2. Open ~/.swalvo/credentials.json and copy the token field.
  3. Save it as a secret in your CI provider.

Session tokens expire. If a job starts failing with exit code 3, get a new token.

A full GitHub Actions step:

- name: List Livqeno projects
  env:
    LIVQENO_TOKEN: ${{ secrets.LIVQENO_TOKEN }}
  run: npx @livqeno/cli projects list --json

Good to know

  • LIVQENO_TOKEN takes priority over a saved login. You can use a different identity for one command:

    Terminal
    LIVQENO_TOKEN="$DEPLOY_TOKEN" livqeno keys list --project 16281d1e-5b0c-4f3e-9a51-7d2c8e4b9a10

  • No browser, but you can write to the home folder? Run livqeno login --token "$LIVQENO_TOKEN". It checks the token and saves it, so later commands don't need the variable.

  • livqeno login --no-open prints the login link instead of opening a browser for you. Copy and paste it into a browser yourself — handy if you're logging in from one device but want to approve it on another.

  • livqeno whoami shows who you're logged in as, and where the login came from:

    $ livqeno whoami
Logged in as: dev@example.com
Credentials:  $LIVQENO_TOKEN
API:          https://api.livqeno.com
Projects:     3
Environment:  development

Projects

A project holds one app's rooms, chats, and keys. See Create a project.

Terminal
livqeno projects create my-video-app        # prints the new project's ID
livqeno projects list                       # every project, with its ID
livqeno projects inspect <project-id>
livqeno projects use <project-id>           # sets the current project for other commands
livqeno projects delete <project-id> --yes  # --yes required outside a TTY

Project IDs are plain UUIDs, like 16281d1e-5b0c-4f3e-9a51-7d2c8e4b9a10. Copy one from livqeno projects list or from the output of projects create.

Commands that work on a project (keys, rooms, streams, …) need one selected. Without one they fail with "No Livqeno project selected". Select it with livqeno projects use <project-id>, link the folder with livqeno init, or pass --project <project-id> to a single command.

livqeno init

Links the current folder to a project. Then you don't need --project on every command:

Terminal
livqeno init

API keys

This is how you create the API key your backend will use. The key is printed once: copy it straight into your backend's secrets. See API credentials.

Terminal
livqeno keys create --name backend --environment production
livqeno keys list
livqeno keys revoke <keyId>

--environment accepts dev / development, stg / staging, prod / production. A typo is rejected. Leave it out to get a development key. See Environments.

Rooms

Useful when a user says "I can't see Bob in the call": check who is actually in the room, and what they're publishing.

Terminal
livqeno rooms list             # live SFU participant counts, honest about unknowns
livqeno rooms inspect <roomId> # participants + published tracks
livqeno rooms create <name>

Chat

Useful for checking chat health (how busy it is, how fast messages are delivered) and who's connected.

Terminal
livqeno chat overview                # activity, throughput, latency
livqeno chat overview --range 24h    # 15m | 1h | 24h | 7d
livqeno chat conversations           # or: livqeno chat list
livqeno chat connections             # WebSocket sessions
livqeno chat connections --state CONNECTED --limit 100
livqeno chat presence <conversationId>

Chat commands are read-only. The CLI can't create conversations or send messages, because it doesn't hold an API key.

Live streams

Terminal
livqeno streams list
livqeno streams list --status LIVE
livqeno streams inspect <streamId>          # details + live viewer count + hosts
livqeno streams create "Friday Q&A" --host user-123
livqeno streams update <streamId> --title "New title"
livqeno streams end <streamId>              # LIVE → ENDED, terminal

There are no commands to add/remove hosts or make host/viewer tokens. Those create real credentials, which need an API key. Do them from your backend with @livqeno/server or livqeno.

RTC: live media state

See live rooms, participants, and server capacity:

Terminal
livqeno rtc rooms list
livqeno rtc rooms get <roomId>
livqeno rtc rooms close <roomId>
livqeno rtc participants list <roomId>
livqeno rtc diagnostics <roomId>
 
# Livqeno operators only — a customer account gets 403:
livqeno rtc servers list
livqeno rtc servers list --region us-east    # just the servers in that region
livqeno rtc servers get <server>
livqeno rtc servers drain <server>      # stop new rooms; live ones keep running
livqeno rtc servers drain <server> --undo   # undo that: let it take new rooms again
  • livqeno rtc diagnostics works for everyone. It tells you if there's capacity, without naming servers.
  • livqeno rtc servers ... is for Livqeno's own team. You'll get 403.

livqeno rooms vs livqeno rtc rooms:

CommandShows
livqeno roomsThe room records saved in your project
livqeno rtc roomsWhat's live on the media servers right now

Project setup

Terminal
livqeno init                # link this directory to a project
livqeno dev                 # check this directory is ready for Livqeno development
livqeno sdk install         # add and configure a Livqeno SDK in this project
livqeno sdk install --dry-run   # just show what it would run, don't install anything
livqeno logs                # stream developer-facing logs for the current project
livqeno version             # the CLI's own version
livqeno logout              # discard the stored session

Connections, errors, diagnostics

This is where you go when a call failed and you want to know why. A connection is one user's session in a call; an error is a problem a client SDK reported. Both are sent by your users' apps automatically (see Telemetry).

A typical debugging session:

  1. livqeno errors list to find recent failures.
  2. livqeno errors inspect <errorId> to see the likely cause and a suggested fix.
  3. livqeno connections inspect <connectionId> to check that user's network quality (packet loss, jitter, round-trip time).
Terminal
livqeno connections list
livqeno connections inspect <connectionId>   # includes the Quality section — see below
livqeno errors list
livqeno errors list --category TOKEN_ERROR   # only this kind of error (or ICE_ERROR, TURN_ERROR, ...)
livqeno errors list --connection <connectionId>   # only errors from that one connection
livqeno errors inspect <errorId>             # category, likely cause, suggested action
livqeno diagnostics

connections inspect shows RTT, jitter, packet loss, bitrate, and codec once the client's SDK has reported them. A brand-new connection may show nothing yet. See Diagnostics.

Status and config

Terminal
livqeno status                                          # is everything up
livqeno config list
livqeno config get apiUrl
livqeno config set apiUrl https://api.livqeno.com

Environment variables the CLI reads:

VariableWhat it does
LIVQENO_API_URLThe API to talk to. Overrides apiUrl from livqeno config. Default http://localhost:4100.
LIVQENO_TOKENA dashboard session token. Overrides a saved livqeno login.
LIVQENO_DASHBOARD_URLWhere livqeno login opens the login page. Only needed when it can't be worked out from the API URL.

JSON output for scripts

Every read command accepts --json:

Terminal
livqeno status --json | jq -r '.dependencies.database'
livqeno projects list --json | jq -r '.[0].id'

Debug mode

Terminal
livqeno --debug status

Shows the full requests and responses (never secrets). Use it when a command doesn't do what you expect.

Exit codes

These stay the same across releases, so scripts can rely on them:

CodeMeaning
0Success
1General failure
2Invalid usage — bad flags or arguments
3Authentication failure
4Authorization failure
5Not found
6Network failure

Security

  • The CLI never has your project API key or a chat token's secret.
  • It only sees what you can already see in the dashboard.
  • A saved login is stored in ~/.swalvo/credentials.json with mode 600 (folder 700).
  • A token from LIVQENO_TOKEN is never saved to disk.
  • No command ever prints a token, including --json and --debug output.

Next steps

  • SDKs: the packages your backend and app use. The CLI doesn't replace them.
  • Diagnostics: what the connection quality numbers mean.
  • Errors: what each error code means.
Edit this page on GitHub