Metadata-Version: 2.4
Name: status202
Version: 1.0.2
Summary: CLI agent for Status 202 -- runs a local command and reports progress back to your Status 202 trackers.
License-Expression: MIT
Project-URL: Homepage, https://status202.dev
Keywords: status202,progress,tracker,cli
Requires-Python: >=3.8
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://status202.dev/brand/logo.png" width="96" height="96" alt="status202 logo">
</p>

<h1 align="center">status202 (Python)</h1>

<p align="center">CLI agent for <a href="https://status202.dev">Status 202</a> — report progress to a tracker, and create/update/delete trackers, straight from the command line. Zero dependencies, stdlib only.</p>

This is a Python port of the [npm `status202` package](https://www.npmjs.com/package/status202) for machines where you'd rather use `pip` than install Node — same flags, same behavior.

## Install

```bash
pip install status202
```

## 1. Reporting progress

```bash
status202 --token YOUR_TOKEN --command "./progress.sh"
```

Your command's stdout is parsed as either:

- JSON — `{"percent": 42}` or `{"value": 7}`
- a bare number — sent using whatever `--field` is set to (`percent` by default)

By default the agent polls Status 202 every `--poll-interval` seconds and only runs your command when an update was actually requested from the app. Use `--push` to skip that check and report immediately every cycle instead.

The agent pauses reporting (but keeps polling) once the tracker reaches 100%, or its agent is manually stopped from the app's tracker page (interval-mode trackers only) — this is driven by the server, not tracked locally. It resumes automatically, with no restart needed, once the tracker is reset or "Resume agent" is used in the app.

### Flags

| Flag | Description |
| --- | --- |
| `--token <token>` | **Required** (or `STATUS202_TOKEN` env var, or `token` in `status202.json`). |
| `--api-key <key>` | Bearer API key for the tracker, if it's an `apiKey`-mode tracker. |
| `--command <cmd>` | Shell command to run when an update is requested. Runs via `/bin/sh -c`. |
| `--watch-file <path>` | Report whenever this file's mtime changes (polled every 0.5s), instead of polling on a timer. If `--command` is also given, the command runs on each change; otherwise the file's own contents are read directly. |
| `--field <percent\|value>` | Which JSON key to send a bare numeric result as. Default: `percent`. |
| `--poll-interval <seconds>` | Seconds between polls. Default: `10`. |
| `--once` | Run/report a single time, then exit. |
| `--push` | Skip the pending-update check; report immediately every cycle. |
| `--base-url <url>` | API base URL. Default: `https://api.status202.dev/v1`. |
| `--config <path>` | Path to a `status202.json` config file. |
| `-h`, `--help` | Show help. |

Precedence for every setting: **CLI flag > environment variable > config file > default.**

## 2. Managing trackers (`trackers` subcommand)

```bash
status202 trackers list
status202 trackers create --name "Backup job" --update-mode agent
status202 trackers get TRACKER_ID
status202 trackers update TRACKER_ID --name "Nightly backup"
status202 trackers delete TRACKER_ID
```

Generate your account key from **Settings → API access** in the app, then pass it via `--account-key`, `STATUS202_ACCOUNT_KEY`, or `accountKey` in `status202.json`.

See the npm package's README for the full field reference (`--name`, `--value-mode`, `--auth-mode`, `--update-mode`, `--min`/`--max`, `--callback-url`, `--time-tracking`) — the flags are identical between the two.
