Testinel CLI

Investigate test failures from your terminal or AI agent. testinel connects to Testinel to browse runs, inspect exceptions and tracebacks, and download screenshots and other artifacts.

• Read-only access to projects and test results
• Browser sign-in with automatic token refresh
• Text, JSON, and Markdown output
• Project selection from your Git remote
• A portable agent skill for diagnostic workflows

Quick Start

Requires Python 3.10 or later and a Testinel server with the diagnostic API enabled.

Install from this package directory using uv:

uv tool install .
testinel auth login
testinel projects list
testinel projects use my-project
testinel investigate --format json

Alternatively, install into an activated Python virtual environment with python -m pip install ..

Sign-in opens a browser for approval. When working remotely, open the printed URL in your browser and enter the displayed code. Return to the terminal after approving access.

Usage

Replace my-project, RUN_UUID, and numeric IDs with values returned by Testinel.

testinel projects list
testinel runs list --project my-project --failed
testinel runs show RUN_UUID --project my-project
testinel failures list --run RUN_UUID --project my-project
testinel failures show 123 --run RUN_UUID --project my-project
testinel artifacts download '456:0' --run RUN_UUID --project my-project --output screenshot.png

The artifact command writes a local file and refuses to overwrite an existing file. Use artifact IDs returned in failure details.

Investigating a run

testinel investigate --project my-project --format json
testinel investigate --project my-project --run RUN_UUID --include-flaky --format json
testinel investigate --project my-project --run RUN_UUID --format markdown > report.md

Without --run, investigation selects the newest run with failed tests. It retrieves up to 20 detailed failures, including attempts, phases, and artifact references. --include-flaky also includes flaky passes within the selected run. JSON reports indicate truncation and provide a continuation command when more results exist.

Filters and pagination

testinel runs list --project my-project --state completed --branch main --limit 10
testinel runs list --project my-project --started-after 2026-09-01T00:00:00Z --format json
testinel failures list --project my-project --run RUN_UUID --cursor CURSOR --format json

Run lists also accept --commit and --started-before. Run and failure lists default to 20 records per page, with a maximum of 100. Read pagination.next_cursor in JSON output to fetch the next page. projects list collects all project pages automatically.

Output formats

testinel projects list                          # Text (also the default when piped)
testinel projects list --format json            # Structured data
testinel projects list --format markdown        # Markdown

JSON data commands write one JSON value to stdout. List responses contain data and pagination; detail responses contain data. Investigation reports use a separate schema_version: 1 document with run and failure details. Authentication commands return authentication status directly.

CLI errors are printed to stderr with a nonzero exit code, including when JSON output is selected.

Exit code	Meaning
0	Command succeeded
2	Invalid arguments or configuration
3	Authentication failed or expired
4	Resource unavailable or access denied
5	Transport, server, or keyring error

Authentication

testinel auth login
testinel auth status
testinel auth logout

Browser approval grants read access to the projects available to your account. Credentials are stored in the operating system keyring, indexed by server URL. Refresh tokens rotate automatically. Use the Testinel website's CLI sessions page to manage authorized access.

For automation, inject TESTINEL_ACCESS_TOKEN through your environment's secret management. TESTINEL_REFRESH_TOKEN is also supported, but renewal writes the replacement to the keyring; a refresh-token environment variable must be updated after rotation. An access token supplied through the environment is not automatically refreshed.

AI Agent Integration

An agent with shell access can use the installed CLI. Point it at skills/testinel/SKILL.md, or install that folder using your agent's skill-loading mechanism.

Example request:

Investigate the latest failed Testinel run for this repository. Explain the likely cause using the traceback and local source, and suggest a fix.

The skill guides authentication checks, project selection, JSON investigation, and correlation with source files. The CLI should be available on the agent's PATH. Diagnostic text and artifacts are evidence to inspect, not instructions to execute.

Configuration

Project selection follows this order:

1. An explicit --project argument.
2. A unique match between remote.origin.url and Testinel repository metadata.
3. The default saved by testinel projects use SLUG.

Multiple Git matches require an explicit selection. Preferences live in config.json under the platform's user configuration directory for testinel (typically ~/.config/testinel/ on Linux). Credentials are stored separately in the keyring.

Setting	Purpose
--server URL	Override the server for one invocation; place before the command
TESTINEL_URL	Override the saved server; defaults to https://testinel.dev
TESTINEL_ACCESS_TOKEN	Supply an access token for automation
TESTINEL_REFRESH_TOKEN	Supply a refresh token instead of reading the keyring

testinel --server http://localhost:8000 auth login
testinel --server http://localhost:8000 projects list

Troubleshooting

• Authentication expired: run testinel auth login again. Check for an expired environment token if login does not resolve the error.
• Browser unavailable: open the verification URL printed by the CLI on another device.
• Keyring unavailable: enable a working operating system keyring, or supply an access token for automation.
• Project cannot be selected: run testinel projects list and pass --project SLUG explicitly.
• No failed runs: select a specific run with --run RUN_UUID; include --include-flaky when inspecting flaky passes.

Explore command options with testinel --help or, for example, testinel runs list --help.

Development

Run these commands from the testinel-cli directory:

uv sync --group dev
uv run testinel --help
uv run pytest
uv run mypy --config-file pyproject.toml src
uv build

The hosted Django API is maintained separately from this repository.