Metadata-Version: 2.4
Name: pantoqacli
Version: 0.0.3
Summary: Panto QA Bridge
Author-email: Ritwick Dey <ritwick@getpanto.ai>
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp>=3.14.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: build>=1.3.0; extra == "dev"
Requires-Dist: pre_commit>=4.5.1; extra == "dev"
Requires-Dist: mypy>=1.19.1; extra == "dev"
Dynamic: license-file

# PantoQA CLI

PantoQA CLI is a Python package for running QA flows against Android or iOS apps using natural-language prompts. It connects to the PantoQA service over WebSocket and can drive a locally connected device via the PantoQA bridge or manage remote device sessions.


## Ask your agent to set it up

To configure your coding agent with the PantoQA skill, ask it to use the skill file here:

https://www.getpanto.ai/SKILL.md

This is the setup file the agent can reference for PantoQA workflows, commands, and local bridge usage.

## Project overview

This repository packages the `pantoqacli` command and includes a skill definition used by the PantoQA agent tooling:

- `pantoqacli` — command-line entry point for authentication, QA execution, bridge inspection, and remote device management
- `skills/pantoqa-agent/SKILL.md` — exported skill metadata for agent integrations

## Installation

Install from the project root with `pip`:

```bash
python -m pip install -e .
```

Or install the package from PyPI if available:

```bash
python -m pip install pantoqacli
```

For local developer setup with optional tooling:

```bash
python -m pip install -e .[dev]
```

## CLI entry point

After installation, the package exposes:

```bash
pantoqacli --help
```

You can also check the installed version:

```bash
pantoqacli --version
```

## Authentication

Most commands require a token. The CLI resolves it in this order:

1. `--token` argument
2. `PANTOQA_TOKEN` environment variable
3. `~/pantoqa-agent/.token`

Log in to create the token file:

```bash
pantoqacli login
```

Verify the configured key:

```bash
pantoqacli test-auth
```

The alias below is also supported:

```bash
pantoqacli auth
```

## Local bridge setup

For local device testing, the bridge must be running and a device must be attached.

Start the bridge:

```bash
pantoqa_bridge
```

Check bridge health:

```bash
pantoqacli bridge status
```

List connected devices:

```bash
pantoqacli bridge devices
```

The `serial_no` returned by `bridge devices` is what you pass to `--device-serial-no` in a QA run.

## Running QA prompts

Run a single prompt:

```bash
pantoqacli run \
  --prompt "Open Settings app"
```

Run multiple prompts sequentially in one session:

```bash
pantoqacli run \
  --prompt "Open Settings" \
  --prompt "Enable Wi-Fi"
```

Common optional flags:

```bash
pantoqacli run \
  --base-url https://qa-app.getpanto.ai \
  --token "$PANTOQA_TOKEN" \
  --prompt "Open Settings" \
  --prompt "Enable Wi-Fi" \
  --platform android \
  --driver-type BRIDGE_V2 \
  --session-exe-type EXECUTE \
  --bridge-base-url http://127.0.0.1:6565 \
  --device-serial-no emulator-5554 \
  --xml-mode adb \
  --verbose
```

## Bridge and remote device utilities

Inspect the bridge without running a prompt:

```bash
pantoqacli bridge status
pantoqacli bridge devices
```

Remote device lifecycle commands:

```bash
pantoqacli remote device start --base-url https://qa-app.getpanto.ai --token "$PANTOQA_TOKEN"
pantoqacli remote device status --session-id <session-id>
pantoqacli remote device preview --session-id <session-id>
pantoqacli remote device stop --timeout 10
```

## Exporting the skill definition

This project includes a skill file that can be exported for agent usage:

```bash
pantoqacli export-skill
```

## Notes

- `run` executes prompts over a WebSocket to the QA server.
- `bridge` commands talk to the local bridge service that performs device actions.
- Remote device commands are separate from local bridge execution and manage background remote sessions.
- If a bridge is not reachable or no device is available, do not attempt to run automated prompts against it.

## License

This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.
