Skip to main content
The Cekura CLI ships in the same package as the Python SDK. If you haven’t installed or authenticated yet, follow the Overview first.

​
Quickstart

# Install
pip install cekura

# Sign in (opens a browser)
cekura auth login

# List your agents
cekura agents list
Set defaults so you don’t have to repeat --project-id / --organization-id on every command: 
cekura config set default_organization_id 14
cekura config set default_project_id 742
On first sign-in (cekura auth login), the first organization and project the CLI sees on your account are saved as defaults automatically. You only need to override these when you want a different default — typically because you belong to multiple organizations or projects.

​
Common commands

# List agents in a project
cekura agents list --project-id 742

# Get one agent
cekura agents get 123

# List scenarios for an agent
cekura scenarios list --agent-id 123

# Trigger an evaluation run (text mode)
cekura run start --agent-id 123 --scenario-ids 1,2,3

# Inspect runs
cekura runs list --agent-id 123

# View production calls
cekura calls list --project-id 742
Every command supports --help for a full flag listing: 
cekura agents --help
cekura scenarios bulk-update --help

​
JSON output for scripting

Add --format json to any list/get command for clean stdout you can pipe into jq, python -c, or your own tools: 
cekura agents list --project-id 742 --format json | jq '.[].agent_name'
This works on every list and detail command and is the recommended mode for shell scripts and CI pipelines.

​
Top-level command groups

GroupPurpose
authSign in / out, check current identity
configView and set CLI defaults
agentsCreate, update, list voice agents and their tools
scenariosManage test scenarios (evaluators)
metricsDefine evaluation metrics
run / runsTrigger evaluations and inspect individual runs
callsProduction call logs and ad-hoc evaluation
dashboardsAnalytics dashboards and widgets
predefined-metrics, critical-metric-scenarios, metric-reviewsPlatform-managed metrics workflow
test-profiles, personalities, phone-numbersReusable test configuration
cronSchedule recurring evaluations
test-setsCurate evaluation datasets from runs or call logs
projects, organizations, billing, api-keysWorkspace administration

​
Common workflows

  1. Generate an org-scoped API key in the dashboard.
  2. Add it as a CI secret named CEKURA_API_KEY.
  3. In your pipeline: 
    export CEKURA_API_KEY=$CEKURA_API_KEY
cekura run start --agent-id 123 --scenario-ids 1,2,3 --format json | tee run.json
RUN_ID=$(jq -r '.run_id' run.json)
cekura runs get "$RUN_ID" --format json
    Fail the pipeline on a non-passing run by parsing the JSON status field: 
    STATUS=$(jq -r '.status' run.json)
[ "$STATUS" = "passed" ] || exit 1
Prepare scenarios.json:
{
  "scenarios": [
    { "id": 101, "tags": ["regression"] },
    { "id": 102, "tags": ["smoke"] }
  ]
}
Apply:
cekura scenarios bulk-update --from-file scenarios.json
The payload must be a JSON object with a top-level scenarios key, plus any of metric_ids_to_add, metric_ids_to_remove, tool_ids_to_add, etc.
cekura test-sets create-from-run \
  --run-id 9876 \
  --name "regression-2024-04"
Or build one from a production call log:
cekura test-sets create-from-call-log \
  --call-log-id 12345 \
  --name "support-edge-cases"

cekura cron create \
  --name "Nightly regression" \
  --agent-id 123 \
  --schedule "0 2 * * *" \
  --tags "regression"
List and manage existing jobs:
cekura cron list --project-id 742
cekura cron delete 42

​
Troubleshooting

  • OAuth users: your token may have expired. Run cekura auth login again.
  • API key users: verify cekura config get shows the right api_url and that CEKURA_API_KEY is set in the current shell. Generate a fresh key in Settings → API Keys if needed.
Several list endpoints require a scope filter (--project-id, --agent-id, or --organization-id). Pass one explicitly, or set defaults via cekura config set default_project_id <id>.
The platform enforces per-plan rate limits. Throttle your loop, batch where possible, or upgrade your plan. Check usage in Settings → API Usage.
Add --format json to any list/get command. Use jq or python -c to parse.

​
References

SDK guide

Use the same operations from Python with sync or async clients.

API Reference

Full endpoint documentation for every resource the CLI exposes.