Metadata-Version: 2.5
Name: testinel-cli
Version: 0.1.1
Summary: CLI for investigating Testinel test runs
Project-URL: Homepage, https://testinel.dev
Project-URL: Repository, https://github.com/Testinel/testinel-cli
Project-URL: Issues, https://github.com/Testinel/testinel-cli/issues
Author-email: Volodymyr Obrizan <obrizan@testinel.dev>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Requires-Dist: filelock<4,>=3
Requires-Dist: httpx<1,>=0.27
Requires-Dist: keyring<26,>=25
Requires-Dist: platformdirs<5,>=4
Description-Content-Type: text/markdown

# 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](https://github.com/Testinel/testinel-cli/blob/main/skills/testinel/SKILL.md) for diagnostic workflows

Want to turn Selenium and Playwright test runs into searchable diagnostics? [Start with Testinel](https://testinel.dev/), send your runs using [pytest-testinel](https://github.com/Testinel/pytest-testinel), and use this CLI to investigate failures from your terminal or AI agent.

## Quick Start

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

Before using the CLI, you need:

- A Testinel account.
- A Testinel project configured to receive test results.
- At least one test run uploaded to that project.

The default `investigate` command selects the newest run with failed tests. You can use `--run RUN_UUID` to investigate a specific run.

Install from PyPI using pip:

```bash
python -m pip install testinel-cli
testinel auth login
testinel projects list
testinel projects use my-project
testinel investigate --format json
```

Alternatively, add it to a uv-managed project:

```bash
uv add testinel-cli
uv run testinel auth login
uv run testinel projects list
```

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.

## Authentication

```bash
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.


## Usage

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

```bash
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

```bash
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

```bash
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

```bash
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 |

## AI Agent Integration

An agent with shell access can use the installed CLI. Point it at [skills/testinel/SKILL.md](https://github.com/Testinel/testinel-cli/blob/main/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 |

```bash
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:

```bash
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.
