> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cekura.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Manage agents, scenarios, runs, and call data from your terminal

export const CopyPageButton = () => {
  if (typeof window !== 'undefined') {
    setTimeout(function () {
      if (document.getElementById('ck-tools')) return;
      var anchor = document.getElementById('content-area') || document.querySelector('.mdx-content');
      if (!anchor) return;
      if (!document.getElementById('ck-style')) {
        var s = document.createElement('style');
        s.id = 'ck-style';
        s.textContent = '#ck-tools{position:absolute;top:6px;right:0;z-index:100;font-family:inherit;}' + '.ck-row{display:inline-flex;align-items:stretch;border:1px solid rgba(0,0,0,0.15);border-radius:8px;overflow:hidden;background:#fff;}' + ':root.dark .ck-row{background:rgba(255,255,255,0.06);border-color:rgba(255,255,255,0.12);}' + '.ck-btn{padding:5px 12px;border:none;background:none;cursor:pointer;font-size:13px;font-weight:500;font-family:inherit;color:#374151;}' + ':root.dark .ck-btn{color:#d1d5db;}' + '.ck-btn:hover{background:rgba(0,0,0,0.04);}' + ':root.dark .ck-btn:hover{background:rgba(255,255,255,0.06);}' + '.ck-chevron{padding:5px 8px;border:none;background:none;cursor:pointer;font-size:14px;font-family:inherit;color:#374151;}' + ':root.dark .ck-chevron{color:#d1d5db;}' + '.ck-chevron:hover{background:rgba(0,0,0,0.04);}' + ':root.dark .ck-chevron:hover{background:rgba(255,255,255,0.06);}' + '.ck-divider{width:1px;background:rgba(0,0,0,0.12);flex-shrink:0;}' + ':root.dark .ck-divider{background:rgba(255,255,255,0.12);}' + '.ck-dd{position:absolute;top:calc(100% + 4px);right:0;min-width:180px;background:#fff;border:1px solid rgba(0,0,0,0.12);border-radius:8px;box-shadow:0 4px 12px rgba(0,0,0,0.1);padding:4px;display:none;z-index:200;}' + ':root.dark .ck-dd{background:#1f2937;border-color:rgba(255,255,255,0.1);box-shadow:0 4px 16px rgba(0,0,0,0.35);}' + '.ck-item{display:block;width:100%;padding:7px 12px;border:none;background:none;border-radius:6px;cursor:pointer;font-size:13px;font-family:inherit;text-align:left;color:#374151;}' + ':root.dark .ck-item{color:#d1d5db;}' + '.ck-item:hover{background:rgba(0,0,0,0.05);}' + ':root.dark .ck-item:hover{background:rgba(255,255,255,0.07);}';
        document.head.appendChild(s);
      }
      var wrap = document.createElement('div');
      wrap.id = 'ck-tools';
      var row = document.createElement('div');
      row.className = 'ck-row';
      var mainBtn = document.createElement('button');
      mainBtn.className = 'ck-btn';
      mainBtn.textContent = 'Copy page';
      var divider = document.createElement('span');
      divider.className = 'ck-divider';
      var chevron = document.createElement('button');
      chevron.className = 'ck-chevron';
      chevron.textContent = '▾';
      var dd = document.createElement('div');
      dd.className = 'ck-dd';
      function closeDD() {
        dd.style.display = 'none';
      }
      function openDD() {
        dd.style.display = 'block';
      }
      chevron.onclick = function (e) {
        e.stopPropagation();
        if (dd.style.display === 'block') {
          closeDD();
        } else {
          openDD();
        }
      };
      document.addEventListener('click', function (e) {
        if (!e.target.closest('#ck-tools')) {
          closeDD();
        }
      });
      document.addEventListener('keydown', function (e) {
        if (e.key === 'Escape') {
          closeDD();
        }
      });
      function makeItem(label, fn) {
        var b = document.createElement('button');
        b.className = 'ck-item';
        b.textContent = label;
        b.onclick = function () {
          fn();
          closeDD();
        };
        return b;
      }
      function getMarkdown() {
        var walk = function (node) {
          if (!node) return '';
          if (node.nodeType === 3) return node.textContent || '';
          if (node.nodeType !== 1) return '';
          var tag = node.tagName.toLowerCase();
          var skip = ['script', 'style', 'svg', 'noscript', 'button', 'iframe'];
          if (skip.indexOf(tag) !== -1) return '';
          if (node.id === 'ck-tools') return '';
          var ch = Array.from(node.childNodes).map(walk).join('');
          if (tag === 'h1') return '\n# ' + ch.trim() + '\n\n';
          if (tag === 'h2') return '\n## ' + ch.trim() + '\n\n';
          if (tag === 'h3') return '\n### ' + ch.trim() + '\n\n';
          if (tag === 'p') return '\n' + ch.trim() + '\n\n';
          if (tag === 'pre') return '\n```\n' + node.textContent.trim() + '\n```\n\n';
          if (tag === 'li') return '- ' + ch.trim() + '\n';
          if (tag === 'code') return '`' + ch.trim() + '`';
          return ch;
        };
        var content = document.querySelector('.mdx-content') || document.getElementById('content-area') || document.body;
        return walk(content).replace(/\n\n\n+/g, '\n\n').trim();
      }
      function copyMd() {
        var md = getMarkdown();
        navigator.clipboard.writeText(md).then(function () {
          mainBtn.textContent = 'Copied!';
          setTimeout(function () {
            mainBtn.textContent = 'Copy page';
          }, 2000);
        });
      }
      function viewMd() {
        var md = getMarkdown();
        var safe = md.split('&').join('&amp;').split('<').join('&lt;').split('>').join('&gt;');
        var html = '<!DOCTYPE html><html><head><meta charset="utf-8"><style>body{font-family:monospace;max-width:860px;margin:40px auto;padding:0 24px;line-height:1.7;white-space:pre-wrap;word-wrap:break-word}</style></head><body>' + safe + '</body></html>';
        window.open(URL.createObjectURL(new Blob([html], {
          type: 'text/html'
        })), '_blank');
      }
      function openClaude() {
        var prompt = 'Can you read this Cekura docs page ' + window.location.href + ' so I can ask you questions?';
        window.open('https://claude.ai/new?q=' + encodeURIComponent(prompt), '_blank');
      }
      mainBtn.onclick = copyMd;
      dd.appendChild(makeItem('Copy page', copyMd));
      dd.appendChild(makeItem('View as Markdown', viewMd));
      dd.appendChild(makeItem('Open in Claude', openClaude));
      row.appendChild(mainBtn);
      row.appendChild(divider);
      row.appendChild(chevron);
      wrap.appendChild(row);
      wrap.appendChild(dd);
      anchor.style.position = 'relative';
      anchor.insertBefore(wrap, anchor.firstChild);
    }, 50);
  }
  return null;
};

<CopyPageButton />

<Note>
  The Cekura CLI ships in the same package as the Python SDK. If you haven't installed or authenticated yet, follow the [Overview](/cli-sdk/overview) first.
</Note>

## Quickstart

```bash theme={null}
# 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:

```bash theme={null}
cekura config set default_organization_id 14
cekura config set default_project_id 742
```

<Tip>
  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.
</Tip>

## Common commands

```bash theme={null}
# 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:

```bash theme={null}
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:

```bash theme={null}
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

| Group                                                               | Purpose                                           |
| ------------------------------------------------------------------- | ------------------------------------------------- |
| `auth`                                                              | Sign in / out, check current identity             |
| `config`                                                            | View and set CLI defaults                         |
| `agents`                                                            | Create, update, list voice agents and their tools |
| `scenarios`                                                         | Manage test scenarios (evaluators)                |
| `metrics`                                                           | Define evaluation metrics                         |
| `run` / `runs`                                                      | Trigger evaluations and inspect individual runs   |
| `calls`                                                             | Production call logs and ad-hoc evaluation        |
| `dashboards`                                                        | Analytics dashboards and widgets                  |
| `predefined-metrics`, `critical-metric-scenarios`, `metric-reviews` | Platform-managed metrics workflow                 |
| `test-profiles`, `personalities`, `phone-numbers`                   | Reusable test configuration                       |
| `cron`                                                              | Schedule recurring evaluations                    |
| `test-sets`                                                         | Curate evaluation datasets from runs or call logs |
| `projects`, `organizations`, `billing`, `api-keys`                  | Workspace administration                          |

## Common workflows

<AccordionGroup>
  <Accordion title="Run evaluations from CI">
    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:

       ```bash theme={null}
       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:

       ```bash theme={null}
       STATUS=$(jq -r '.status' run.json)
       [ "$STATUS" = "passed" ] || exit 1
       ```
  </Accordion>

  <Accordion title="Bulk-update scenarios from a JSON file">
    Prepare `scenarios.json`:

    ```json theme={null}
    {
      "scenarios": [
        { "id": 101, "tags": ["regression"] },
        { "id": 102, "tags": ["smoke"] }
      ]
    }
    ```

    Apply:

    ```bash theme={null}
    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.
  </Accordion>

  <Accordion title="Promote a passing run into a test set">
    ```bash theme={null}
    cekura test-sets create-from-run \
      --run-id 9876 \
      --name "regression-2024-04"
    ```

    Or build one from a production call log:

    ```bash theme={null}
    cekura test-sets create-from-call-log \
      --call-log-id 12345 \
      --name "support-edge-cases"
    ```
  </Accordion>

  <Accordion title="Schedule recurring evaluations">
    ```bash theme={null}
    cekura cron create \
      --name "Nightly regression" \
      --agent-id 123 \
      --schedule "0 2 * * *" \
      --tags "regression"
    ```

    List and manage existing jobs:

    ```bash theme={null}
    cekura cron list --project-id 742
    cekura cron delete 42
    ```
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="`Authentication failed. Check your CEKURA_API_KEY.`">
    * **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.
  </Accordion>

  <Accordion title="`Please provide one of the required query parameter`">
    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>`.
  </Accordion>

  <Accordion title="Rate limited (429)">
    The platform enforces per-plan rate limits. Throttle your loop, batch where possible, or upgrade your plan. Check usage in **Settings → API Usage**.
  </Accordion>

  <Accordion title="Want machine-readable output">
    Add `--format json` to any list/get command. Use `jq` or `python -c` to parse.
  </Accordion>
</AccordionGroup>

## References

<CardGroup cols={2}>
  <Card title="SDK guide" icon="python" href="/cli-sdk/sdk">
    Use the same operations from Python with sync or async clients.
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference">
    Full endpoint documentation for every resource the CLI exposes.
  </Card>
</CardGroup>