Metadata-Version: 2.4
Name: veyzl-cli
Version: 0.1.0
Summary: Command-line client for Veyzl hosted AI audits
Author-email: Veyzl <suyash@veyzl.ai>
License-Expression: MIT
Project-URL: Homepage, https://veyzl.ai
Project-URL: Documentation, https://veyzl.ai/developers
Keywords: veyzl,ai,audit,governance,compliance,cli
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: certifi
Dynamic: license-file

# veyzl-cli

Command-line client for Veyzl hosted audits: sign in, list projects and runs, start an audit and
gate on its result, and download signed evidence packs.

```bash
pipx install veyzl-cli        # or: pip install veyzl-cli
veyzl login
veyzl projects
veyzl audit <project-id> --wait
git push && veyzl watch <project-id>   # follow the audit the push started
```

## Commands

| Command | What it does |
| --- | --- |
| `veyzl login` | Opens veyzl.ai in your browser; approve there and the CLI is signed in as you. |
| `veyzl logout` | Deletes the stored sign-in from this computer. |
| `veyzl whoami` | Shows the signed-in account and plan. |
| `veyzl projects` | Lists the projects you can open, with their latest result and pass rate. |
| `veyzl runs <project>` | Lists hosted audit runs, newest first (`--limit N`). |
| `veyzl audit <project>` | Starts a hosted audit (`--branch`). With `--wait`, shows progress and exits `0` only if the audit passes, `1` otherwise. |
| `veyzl watch <project>` | Follows the audit GitHub started for a push or PR and exits like `audit --wait`. Matches `--commit SHA`, `--pr N` or `--branch B`; with none of them inside a git repo it follows `HEAD`, otherwise the newest run. Waits for the run to appear (`--timeout`, default 1800s). |
| `veyzl export <project>` | Writes the project's signed evidence pack (`-o FILE`, `--force` to overwrite). Startup plan feature. |

`whoami`, `projects`, `runs`, `audit` and `watch` take `--json` for the raw API response.

In a terminal, `audit --wait` and `watch` draw a live bar with the elapsed time. While the run
reports progress the bar fills by percent and shows the current step (e.g. `42% running tests 21/50`);
otherwise it moves a run stage at a time (queued, running, finished). When output isn't a terminal
(CI logs, pipes, AI coding agents) it prints one plain line per stage instead.

## Sign-in

`veyzl login` listens on a random port on `127.0.0.1` and opens `https://veyzl.ai/cli-login`.
When you approve there (any sign-in method works: email, Google or GitHub), the page posts your
session back to that listener, guarded by a one-time state value. The CLI stores it in
`~/.config/veyzl/credentials.json` (or `$XDG_CONFIG_HOME/veyzl/`), readable only by you, and renews
its short-lived tokens on its own. `veyzl logout` deletes that file.

Sign-in needs a browser on the same machine as the CLI; it doesn't work over plain SSH. For those
places, use a CI token.

## CI and cloud agents: `VEYZL_TOKEN`

CI pipelines and cloud coding agents have no browser, so they use a **CI token** instead. The
anyone on the project creates one in the project's **Settings → CI tokens** (Startup plan). It is
shown once, works only on that project, acts as the person who created it (and stops if they leave
the project), and expires after 90 days.
When `VEYZL_TOKEN` is set, the CLI uses it instead of the stored sign-in.

```yaml
# GitHub Actions: wait for the audit of this commit before deploying
- run: pipx install veyzl-cli
- run: veyzl watch <project-id> --commit "$GITHUB_SHA"
  env:
    VEYZL_TOKEN: ${{ secrets.VEYZL_TOKEN }}
```

A CI token can run `runs`, `audit`, `watch`, `export` and `whoami` for its project. `projects`
needs a signed-in account. Revoke a token in the same settings card; it stops working at once.

## Environment

| Variable | Default |
| --- | --- |
| `VEYZL_TOKEN` | unset; a project CI token to use instead of `veyzl login` |
| `VEYZL_API_URL` | `https://api.veyzl.ai` |
| `VEYZL_WEB_URL` | `https://veyzl.ai` (where `login` sends the browser) |

## Requirements

Python 3.9 or newer, and a Veyzl account. The only dependency is `certifi`, for HTTPS certificate checks.

## Development

From the CLI's source folder:

```bash
pip install -e .
python3 -m unittest discover tests
```

Releasing a new version: see `RELEASING.md` in the source folder.

## License

MIT. This covers the CLI only; using the Veyzl service is subject to its own terms.
