What the CLI does
Most customers never need this page: the Control panel covers everyday setup. The topaz command-line tool does the same work from a terminal, a script or an AI agent: people and extensions, desk phones and softphones, phone numbers, call routing, voicemail, ring groups, call history and webhooks to your other systems. It uses the same API as the Control panel (https://app.topaz.tel/v2), so everything it does shows up there and stays editable there. First sign up; you need to be an administrator of the account.
Install
Python 3.10 or newer; nothing else.
curl -fsSL https://topaz.tel/install.sh | shThe script downloads the CLI from this site, checks its SHA-256 and installs it with uv, pipx or a private Python environment, putting topaz in ~/.local/bin. To install by hand, download the CLI 0.3.2 wheel and SHA256SUMS into one folder, then:
sha256sum -c SHA256SUMS
uv tool install ./topaz_tel-0.3.2-py3-none-any.whl # or: pipx install ./topaz_tel-0.3.2-py3-none-any.whlLog in
Run topaz login. The CLI shows a link and a short code and opens your browser at the Control panel’s sign-in for the CLI. Sign in as an account administrator (or confirm, if you are already signed in), check that the code matches and click Approve. The CLI then receives your account’s API key directly from Topaz and keeps it in your computer’s keychain (macOS Keychain, or GNOME Keyring or KWallet on Linux); where there is no keychain it goes in a file only you can read. It exchanges the key for a one-hour session as needed. topaz whoami shows the account in use and topaz doctor checks the whole chain.
topaz login
topaz whoami| Situation | Command |
|---|---|
| An AI agent | topaz login --start, show the person the link, then topaz login --wait --timeout 100; exit code 4 means still waiting, so run it again |
| Username and password instead of a browser | topaz login --password (an administrator’s sign-in: other users can change only their own profile) |
| CI or a container | set TOPAZ_API_KEY from your secrets manager, or pipe the key to topaz login --api-key-stdin |
| Several accounts | topaz login --profile acme, then --profile acme on any command |
What the key can do
It is your account’s own API key: it can do everything an account administrator can do in the Control panel, for as long as it exists. Keep it like a password. topaz logout removes it from this computer only; topaz auth rotate-key --yes issues a new key and stores it here, and every other copy stops working at once. That is how to revoke access.
Give an AI agent the skill
The CLI carries a skill for AI agents, topaz-tel. It teaches the safe way to work (look first, explain the plan, ask before anything that costs money or deletes data, confirm with a test call) and step-by-step recipes: a new employee, a main number with an auto-attendant and office hours, ring and hunt groups, forwarding, shared voicemail, a conference bridge, blocked callers, call recording, call events to a CRM and offboarding.
topaz skill install # Claude Code
topaz skill install --agent codex # Codex (or --agent all, or --dir DIR)It always matches the installed CLI version. You can also read the skill here.
Commands
topaz COMMAND --help describes every option and topaz schema lists every command as JSON.
| Command | What it manages |
|---|---|
users | people: create --first-name --last-name --email --extension auto --invite, invite, forward --to NUMBER, delete --yes |
devices | phones: create --name --owner USER --type sip_device|softphone|cellphone, credentials ID, status |
numbers | list (and where each one rings), assign NUMBER --user|--callflow, release NUMBER --yes. During early access, new numbers are added on request (email support@mail.topaz.tel): buy is refused for customer accounts |
ring-groups | create --name --member ID (repeat --member; --strategy single rings one after another), list, delete --yes |
calls | list --since 24h (call history), active (calls in progress) |
voicemail | boxes, plus messages BOX and message BOX MSG --download FILE |
callflows, menus, rules | call routing, auto-attendants, office hours and holidays |
media | greetings: create --name --file greeting.wav |
webhooks | call events to your systems: available, create --name --uri --event |
account, balance | account settings; your calling credit (read only) |
api METHOD PATH | any other API call, relative to your account (topaz api GET limits) |
Every resource has list, get ID, create, update ID and delete ID --yes. create and update take a JSON document (--data FILE) or single fields (--set key=text, --set key:=json); update merges your changes into the current document. users create, devices create and ring-groups create set things up exactly as the Control panel’s SmartPBX does, so the result looks and behaves the same there.
Examples
A new employee with an extension, voicemail, a desk phone and their mobile ringing too:
topaz users create --first-name Jane --last-name Doe --email jane@example.com --extension auto --invite
topaz devices create --name "Jane desk phone" --owner USER_ID
topaz devices create --name "Jane mobile" --owner USER_ID --type cellphone --number +16045551234A sales line that rings two people, on its own number:
topaz ring-groups create --name Sales --member USER_1 --member USER_2
topaz numbers assign +16045550123 --callflow CALLFLOW_IDYesterday’s calls, and call events sent to a CRM:
topaz calls list --since 24h
topaz webhooks create --name CRM --uri https://crm.example.com/topaz --event channel_destroydevices create prints the phone’s SIP username and password; the SIP domain is your account realm and the outbound proxy is sip.topaz.tel. See Phones & devices.
Output, errors and exit codes
At a terminal the CLI prints tables; in scripts and agents it prints JSON (force either with --json or --table), never your session token. Errors go to stderr with the reason and, for invalid data, each rejected field. Exit codes: 0 ok, 1 error, 2 bad usage, 3 not logged in, 4 login still waiting for approval.
Safety
Reading is free. Deleting anything, and releasing a phone number, needs --yes; the skill tells agents to get your explicit OK first. A phone number costs $10 a month from your credit. Credit, cards and top-ups are managed only in the Control panel under My Account › Billing; the CLI only reads your balance and never handles card details. 911 and emergency calling are not supported. A change that timed out may still have happened, so the CLI never repeats one by itself: read it back first. Webhook and call-recording addresses must be public HTTPS URLs.
How browser login works
topaz login follows the standard device-login pattern (OAuth device authorization, RFC 8628). The approval page lives on the Control panel’s own address and approves only administrators of the account. The key is read with the approving administrator’s own session, held in memory for at most ten minutes, handed to the waiting CLI once and then forgotten. The page shows which computer asked: approve only a login you started yourself.
Accounts and billing
A person creates the account at https://signup.topaz.tel/, paying on Stripe's hosted checkout, and adds credit or changes the card in the Control panel under My Account › Billing (https://app.topaz.tel/#/billing), in Stripe's own card form. An agent may share those links but must never enter, request or handle card details.
Machine-readable files
LLM index · Full CLI guide · Agent skill · CLI schema · Kazoo API callback catalog · Install script · Release manifest. The schema is what topaz schema prints. The callback catalog lists the Kazoo API modules Topaz is built from, with source hashes; it is reference material, not a promise that every endpoint is available to your account.