vsscli Essentials

vsscli is the command-line client for the platform’s management API. Every topic page in these docs shows its own commands; this page covers the machinery they all share — connecting, profiles, output, and the interactive modes.

vsscli login                        # password + 2FA (or --apikey)
vsscli ns use 0197f9d2-…            # set the working namespace
vsscli config push tenant.yaml --apply
vsscli cdrs calls --since 24h

Profiles

A profile bundles a server URL, a saved login, and a working namespace under a name, so switching between environments (production, lab, a second cluster) is one command instead of four flags:

vsscli profile create prod --server https://api.switch.example
vsscli profile use prod             # make it the default
vsscli profile list
vsscli profile show [name]
vsscli profile set server https://api2.switch.example
vsscli profile set default-namespace 0197f9d2-…
vsscli profile set output-format json    # per-profile default output
vsscli profile set pager on              # per-profile pager default
vsscli profile rename prod prod-east
vsscli profile delete lab

The output-format and pager preferences apply whenever you don’t pass the corresponding flag — precedence is explicit --output/--pager › profile preference › built-in default.

Every command runs against the current profile unless --profile <name> picks another one for that invocation. Profiles live in ~/.config/vsscli/config.yaml (override with $VSSCLI_CONFIG_DIR, or $XDG_CONFIG_HOME).

Session tokens are not stored in that file: they go to your OS keyring when one is available, falling back to a 0600-permission file under ~/.local/share/vsscli (override with $VSSCLI_DATA_DIR / $XDG_DATA_HOME).

Logging in

vsscli login runs the interactive password + two-factor flow by default — including first-time authenticator enrollment with a terminal QR code — and saves the session token into the current profile:

vsscli login                        # prompts: user, password, TOTP
vsscli login --user alice --namespace 0197f9d2-…   # pre-fill, prompt the rest
vsscli login --apikey               # API-key login (prompts for the key)

Service accounts and scripts use API-key login; the key can also come from the $VSSCLI_API_KEY environment variable. A script doesn’t have to “log in” at all: passing --api-key (or having $VSSCLI_API_KEY set) on any command exchanges the key for a token for that one invocation, leaving the stored credential untouched. Credential precedence, highest first: --token (used verbatim) → --api-key/$VSSCLI_API_KEY (exchanged on the fly) → the profile’s stored session. Session management lives under auth:

vsscli auth status                  # who am I, which server, token validity
vsscli auth token print             # emit the raw JWT (for curl)
vsscli auth logout                  # discard the stored token

Tokens expire after one hour; when a command starts failing with 401, log in again (scripts using an API key can simply re-run vsscli login --apikey "$KEY").

The server URL is resolved in order: --server flag → $VSSCLI_SERVER → the profile’s saved server.

The working namespace — and aliases

Most commands operate on one namespace. Set it once per profile:

vsscli ns use 0197f9d2-3f4a-7c21-…

…or override per invocation with --namespace. Because UUIDs are miserable to type, a profile can carry namespace aliases:

vsscli ns alias add acme 0197f9d2-3f4a-7c21-…
vsscli ns alias list
vsscli ns use acme                  # aliases work wherever a namespace does
vsscli config get running --namespace acme
vsscli ns alias delete acme

Aliases are local to the profile — they are your shorthand, not server state. The shell prompt (below) shows the alias instead of the UUID when one matches.

Global flags

Available on every command:

Flag	Effect
--profile <name>	Use a saved profile other than the current one
--server <url>	Override the API base URL
--namespace <id|alias>	Override the working namespace
--token <jwt>	Use a session token directly (skips the stored credential)
--api-key <key>	Authenticate this one invocation with an API key (exchanged for a token on the fly; nothing is stored)
-o, --output <fmt>	Output format: table (default), json, yaml, plaintext, quiet
--quiet	Minimal, machine-friendly output (usually bare identifiers)
--pager	Pipe long output through $PAGER (default less)
--no-color	Disable colorized output
--yes	Answer destructive-action confirmations non-interactively
--verbose	Request diagnostics; with --help, also print the API endpoint
--debug	Include HTTP method/path/status in error output

Output management

Every command renders through the same four formats. table is the human default; json and yaml emit the full structured result for tooling; plaintext is a minimal text rendering; quiet prints just the identifiers — one per line, built for xargs and shell loops:

vsscli rt vm list -o json | jq '.[].box'
vsscli cdrs legs --since 24h --quiet | wc -l
for box in $(vsscli rt vm orphans list --quiet); do …; done

A profile can carry a default format (profile set output-format …), so a service account whose consumers always want JSON never needs the flag. Long listings combine well with --pager; the CDR and routing-log commands honour it for their multi-page output.

Commands that mint secrets (device passwords, API keys) refuse to print them to an interactive terminal by accident — they require an explicit capture mode: --show (print), --copy (clipboard), --out FILE (0600 file), --json, or --env NAME. See device credentials for the pattern in action.

Finding your way around

The command tree is organized by topic, most groups with a short alias:

Group	Alias	Covers
namespace	ns	Namespace lifecycle, tree, aliases, use
config	—	Configuration versions: show, push, diff, apply, tags, edit
realtime	rt	Runtime state: voicemail (rt vm), line features (rt line)
resource	res	Managed-mode resource definitions
peer	—	SIP device credentials
cdrs	cdr	Call detail records + bulk export
route-logs	rl	Routing forensics
lcr	—	Least-cost-routing rate tables
user, grants, me	—	Users, role grants, self-service
profile, auth, login	—	Profiles and sessions
api	—	Raw API escape hatch: vsscli api get /v1/ns/…
shell	repl	The interactive shell (below)

Help is everywhere: vsscli <cmd> --help at any level, and adding --verbose to --help also prints which API endpoint the command calls — handy when graduating from CLI experiments to integration code. Shell tab-completion is available for bash, zsh, and fish via vsscli completion <shell> (see vsscli completion --help for the install one-liner).

The interactive shell

vsscli shell starts a REPL: every CLI command works without the vsscli prefix, with line editing and history, and the prompt tracks your context:

$ vsscli shell
vsscli[prod ns=acme]> rt vm list
vsscli[prod ns=acme]> cd ns lab-tenant      # sugar for: ns use lab-tenant
vsscli[prod ns=lab-tenant]> cdrs calls --since 1h
vsscli[prod ns=lab-tenant]> exit

Shell built-ins:

Command	Does
pwd	Show the active profile, server, and namespace
set output <fmt> / set pager on|off	Change output settings for this session
history	Show the session’s command history
cd ns <id|alias>	Switch namespace (alias for ns use)
exit / quit	Leave the shell
!<command>	Shell escape — disabled unless started with --allow-shell
configure terminal	Enter the configuration editor (below)

configure terminal — the IOS-style config editor

From inside the shell, configure terminal (or conf t) opens a modal, Cisco-IOS-style editor over the namespace’s latest config version. Edits accumulate in a local draft — nothing touches the server until you commit:

vsscli[prod ns=acme]> conf t
Edits are local until you `commit`. `commit apply` also promotes to running; `end`/`exit` leaves. Type ? for help.
(config)# line-profiles standard
(config-line-profiles-standard)# max-ring-time 30
(config-line-profiles-standard)# calling-features dnd cfa cfb cfna voicemail
(config-line-profiles-standard)# exit
(config)# lines 1001
(config-lines-1001)# voicemail 1001
(config-lines-1001)# no ring-group
(config-lines-1001)# end
vsscli[prod ns=acme]>

The grammar, mode by mode:

• Enter a mode by naming a config section — bare for singletons (configuration), with a name for collections (lines 1001, trunks carrier-a), with an index or add for list-shaped sections. The prompt shows where you are: (config-lines-1001)#.
• Set a field with set <field> <value> — or just <field> <value>; a bare leading token that isn’t a sub-mode is a set. Multi-valued fields take all their values on one line.
• no <field> unsets a field (IOS-style negation).
• show prints the current mode’s subtree from your draft; show diff shows the full draft-vs-base diff.
• edit <field> opens a subtree in your external editor ($VSSCLI_EDITOR / $EDITOR) — the escape hatch for the deeply nested structures (translation match/modify blocks) the modal grammar deliberately doesn’t drill into.
• ? at any point lists what’s available in the current mode, and Tab completes field and mode names (schema-aware).
• Navigate with exit (up one mode), top (back to the root mode), end (leave the editor).
• do <command> runs any normal CLI command without leaving the editor (do rt vm list).

Finishing up:

• validate dry-runs your draft against server-side validation and reports field-level errors — free to run at any point.
• commit sends the draft as a minimal patch against the version you started from, creating a new config version; a concurrent change by someone else is detected rather than overwritten. The session then continues on the new version. commit apply also promotes it to running in the same step.
• save <path> writes the draft YAML to a local file instead (author offline, config push later).

The editor is a front-end over the same versioned config pipeline as config push / config apply — everything about versions, validation, and rollback in config versioning applies unchanged.

Scripting notes

• --yes skips interactive confirmation on destructive commands (purges, deletes) — combine with explicit ranges and scopes, never defaults.
• --quiet output is stable, line-oriented identifiers; --output json is the full contract. Prefer those over parsing tables.
• vsscli auth token print bridges to raw curl; vsscli api get|post|put|delete <path> makes one-off API calls with the profile’s auth already attached.

Troubleshooting

Symptom	Cause	Do
“no active namespace”	No working namespace set	vsscli ns use <nsid> or pass --namespace
401 after an hour of work	Session token expired	vsscli login again (--apikey for service accounts)
“no server configured”	No profile server, flag, or env	vsscli profile set server <url>, or --server / $VSSCLI_SERVER
Password prompt but no QR/TOTP support in terminal	First login enrolls 2FA interactively	Use a terminal that renders the QR, or enter the printed secret into your authenticator manually
configure terminal not found at the top level	It is shell-only by design	vsscli shell, then conf t
Secret command prints nothing	Capture mode required	Add --show, --copy, --out FILE, --json, or --env NAME