Local

Run Voxli tests against your local development environment for fast iteration without CI round-trips. The @voxli/cli package handles agent registration and polling automatically, you just provide a test command.

Using the cli helps with a few things.

Registers an agent in voxli representing your computer (only visible to you).
Allows triggering test runs from the Voxli web UI or via MCP.
Simplifies authentication (no need for API keys).

Setup

Install the voxli cli

npm install -g @voxli/cli

voxli auth

This links your machine to your Voxli account. The CLI stores your credentials locally and injects them as the VOXLI_API_TOKEN environment variable when running your test command.

Write Your Test Command

The CLI passes these environment variables to your command:

VOXLI_API_TOKEN — your API token (injected automatically from voxli auth)
VOXLI_TEST_RESULT_IDS — JSON array of test result IDs to run

This is the same contract as the GitHub integration, so if you already have a test script for CI you can reuse it directly.

"""
Run Voxli test conversations.

Environment variables:
- VOXLI_API_TOKEN: Your API key (required)
- VOXLI_TEST_RESULT_IDS: JSON array of test result IDs (required)
"""

import json
import os
import sys
import time
import requests


def get_agent_response(message: str) -> str:
    """
    Replace this with your actual agent integration.

    Receives a message from the Voxli tester and returns
    your chatbot's response.
    """
    return "The meaning of life is 42."


def poll_next_message(endpoint: str, headers: dict, timeout: int = 30) -> str | None:
    start_time = time.time()
    while True:
        response = requests.post(endpoint, headers=headers)
        response.raise_for_status()
        data = response.json()
        if data["ready"]:
            return None if data.get("end_chat") else data["message"]
        if time.time() - start_time > timeout:
            raise TimeoutError("Timed out waiting for message")
        time.sleep(1)


def run_test(test_result_id: str, api_key: str, base_url: str):
    headers = {"Authorization": f"Bearer {api_key}"}
    conversation_endpoint = f"{base_url}/test-results/{test_result_id}/conversation"
    generate_endpoint = f"{base_url}/test-results/{test_result_id}/next-message"

    # Get first message from Voxli
    tester_message = poll_next_message(generate_endpoint, headers)

    # Conversation loop
    for _ in range(20):  # Max turns safety limit
        agent_response = get_agent_response(tester_message)

        # Record agent response
        response = requests.post(
            conversation_endpoint, headers=headers, json={"type": "message", "content": agent_response}
        )
        response.raise_for_status()

        # Get next message from Voxli
        tester_message = poll_next_message(generate_endpoint, headers)
        if tester_message is None:
            print(f"Test {test_result_id} completed")
            break


def main():
    api_key = os.getenv("VOXLI_API_TOKEN")
    test_result_ids_raw = os.getenv("VOXLI_TEST_RESULT_IDS")
    base_url = os.getenv("VOXLI_API_URL", "https://api.voxli.io")

    if not api_key or not test_result_ids_raw:
        print("Error: VOXLI_API_TOKEN and VOXLI_TEST_RESULT_IDS are required")
        sys.exit(1)

    test_result_ids = json.loads(test_result_ids_raw)

    for test_result_id in test_result_ids:
        run_test(test_result_id, api_key, base_url)


if __name__ == "__main__":
    main()

Start Listening

voxli listen --command "python run_test.py"

The --command flag specifies the shell command the CLI runs when tests are assigned. It receives VOXLI_TEST_RESULT_IDS and VOXLI_API_TOKEN as environment variables.

Trigger a test run from the Voxli UI selecting your local agent — the CLI picks it up and runs your command.

How It Works

The CLI registers your machine as a local agent in Voxli
You trigger a test run from the Voxli UI
The CLI picks up the work and runs your --command with VOXLI_TEST_RESULT_IDS and VOXLI_API_TOKEN
Your script runs the tests and reports results back to Voxli using the API