dograh-ctl

A CLI to run a self-hosted Dograh voice-agent platform from the terminal: agents, calls, transcripts, numbers, models, campaigns, tools, keys, and an MCP server that exposes all of it to an agent. No dashboard clicking.

Why this exists

Dograh ships a REST API, generated SDKs, a dashboard, and an MCP server for building agents. It does not ship a command line for running them. Everything you do to operate a voice agent in production (which number routes where, what the last call cost, flip a model, place a test call, read the transcript) means clicking through the UI. dograh-ctl is the missing operations surface: scriptable (--json everywhere), diffable, and automatable, and dograh-ctl serve hands the same verbs to an agent over MCP.

Install

From PyPI:

uv tool install dograh-ctl        # or: pip install dograh-ctl
uvx dograh-ctl --help             # try it without installing

Or straight from GitHub:

uv tool install git+https://github.com/erickcxc/dograh-ctl

From a clone: pip install -e . (or uv sync). Python 3.10+.

Point it at your instance and key (create a key in Dograh, under Developers):

export DOGRAH_BASE_URL=https://your-dograh-host
export DOGRAH_API_KEY=dgr_xxx
dograh-ctl ping

Auth is the X-API-Key header. The key is read from the environment and stays in .env (gitignored), never in the repo, never in this tool's output.

Quick start

dograh-ctl agents list                                   # what agents exist
dograh-ctl agents get 7                                  # graph summary + model override (masked)
dograh-ctl runs chat 7 -m "hello"                        # talk to an agent, no telephony
dograh-ctl models set --realtime google_realtime/gemini-3.1-flash-live-preview
dograh-ctl agents publish 7                              # edits are drafts until published
dograh-ctl runs trigger 7 --to +13135550100 --yes        # place a real call
dograh-ctl runs transcript 501                           # read it back
dograh-ctl runs latency --json | jq .p95                 # everything is scriptable

Commands

Every command accepts --json (raw API payload, for scripts). Every failure is one line on stderr with an exit code: 2 for local configuration problems, 1 for anything the instance refused or could not be reached for. No tracebacks.

Buying a number is a carrier action: twilio phone-numbers:buy:local --country-code US --area-code 313, then dograh-ctl numbers add +1313... --agent 7.

Safety rails

• Verbs that place calls or cost money (runs trigger, campaigns start, numbers remove, keys revoke) ask for confirmation; pass --yes in scripts.
• models set and agents set-model read the current configuration, change one block, and write the whole thing back, so masked secrets are merged by the server, never overwritten with a placeholder.
• Nothing prints a secret. keys create shows the prefix; --reveal prints the full key once.
• Edits to an agent are drafts. agents publish is the step that changes production behaviour.

For AI agents (Claude Code and any MCP client)

This is the reason dograh-ctl exists: a coding agent should be able to create a voice agent, publish it, give it a number, test it, call it, and read the transcript, without a human clicking through a dashboard.

• One-step install for Claude Code (MCP server + skill + setup command):

  claude plugin marketplace add erickcxc/dograh-ctl
  claude plugin install dograh-ctl
  

  The plugin registers dograh-ops (uvx dograh-ctl serve, credentials passed through from your shell as ${DOGRAH_BASE_URL} / ${DOGRAH_API_KEY}, never stored) and installs the dograh-ctl skill, which teaches the lifecycle: create -> set_prompt -> set_model -> validate -> publish -> number -> chat test -> call -> transcript. /dograh-ctl-setup checks the environment and the connection.
• Any MCP client: dograh-ctl mcp-config prints the claude mcp add line and the JSON block.
• Shell-driving agents: every command takes --json; exit codes are stable (2 config, 1 remote); AGENTS.md has the conventions.
• Safety for autonomous use: tools that place calls (runs_trigger, campaigns_start) are annotated destructive so clients confirm; writes are idempotent read-modify-write; payloads are scrubbed of keys; keys create/revoke and numbers remove are CLI-only on purpose.

Build with Dograh's MCP, operate with dograh-ctl serve

Dograh mounts its own MCP server at {DOGRAH_BASE_URL}/api/v1/mcp (Streamable HTTP, same API key). Its tools are for authoring: create and save workflows, list node types, search the docs, pull the voice-prompting guide.

dograh-ctl serve is the operations plane over stdio: list agents, place a call, read a transcript, latency stats, route numbers, flip models, watch a campaign. Point Claude Code (or any MCP client) at both and an agent can build a voice agent, call it, and read what happened.

{ "mcpServers": { "dograh-ops": { "command": "dograh-ctl", "args": ["serve"] } } }

Verification

Shapes are taken from the Dograh source at dograh-hq/dograh@b32187d8 (2026-08-20) and pinned in tests/fixtures. Ten endpoints are Dograh's stable SDK contract; the rest are dashboard-internal and may drift between Dograh releases, which is why every command is mocked-HTTP tested and the fixtures cite their schema.

Live-verified rows move as commands are exercised against a real instance; nothing is listed as live-verified unless it was.

Design

• Thin httpx client with the X-API-Key header; DOGRAH_BASE_URL and DOGRAH_API_KEY from the environment.
• typer and rich; one output module so tables and --json never drift; one error path so no command shows a traceback.
• Talks only to your own self-hosted Dograh. This is a control layer on top of Dograh; it never vendors or republishes Dograh's code.
• Tests: uv run pytest (respx-mocked HTTP, fixtures mirror the upstream schemas). CI runs lint + tests on Python 3.10 and 3.12.

The command surface

The whole operations surface of a self-hosted Dograh instance, in one tool: 9 command groups, 32 commands, every one of them tested, and the same verbs exposed to agents through serve. Day 8 shipped the skeleton (ping, agents, runs, numbers); Day 9 completed the map and tagged v0.2.0.

Built live

Designed and built live on the AI by Erick stream (one-hour build challenge, Days 8 and 9), as the engine-first pivot into voice.

Daily builds: https://www.youtube.com/channel/UCWCXKXvNtNbKPkeK_t5CZlg

I build agentic systems like this for businesses. Reach me through the channel.

License

MIT