What this does

Status 202 is an API-powered progress tracker. This package is the companion CLI for it, and does two independent things:

1. Report progress to one tracker — runs locally (behind NAT, on a laptop, on an internal server, anywhere), polls Status 202 for pending update requests, runs your command, and reports the result back. No inbound connection required.
2. Manage trackers on your account — create, list, get, update, and delete trackers themselves, via status202 trackers ... subcommands.

Install

npm install -g status202

Or run it without installing globally:

npx status202 --token YOUR_TOKEN --command "./progress.sh"

1. Reporting progress

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 (via the "Request update" button, or automatically on app open for callable trackers). Use --push to skip that check and report immediately every cycle instead — handy for cron, or for live/push-mode trackers.

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 the agent tracking the value locally, so it also works with --push. It picks back up and resumes reporting automatically, with no restart needed, as soon as the tracker is reset or the app's "Resume agent" button is used. --once runs are unaffected either way.

Flags

| Flag | Description | | --- | --- | | --token <token> | Required (or set via STATUS202_TOKEN env var, or token in status202.json). The tracker's URL token — found on the tracker's detail page in the app. | | --api-key <key> | Bearer API key for the tracker, if it's an apiKey-mode tracker (also STATUS202_API_KEY / apiKey in config). | | --command <cmd> | Shell command to run when an update is requested. Runs via /bin/sh -c. | | --watch-file <path> | Report whenever this file changes, instead of polling on a timer. If --command is also given, the command runs on each change and its stdout is what gets parsed/reported; otherwise the file's own contents are read and parsed directly. | | --field <percent\|value> | Which JSON key to send a bare numeric result as. Default: percent. | | --poll-interval <seconds> | Seconds between polls. Default: 10. Ignored with --watch-file. | | --once | Run/report a single time, then exit (e.g. for cron). | | --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. Default: ./status202.json. | | -h, --help | Show help. |

Config file

Instead of flags, drop a status202.json next to where you run the command:

{
  "token": "YOUR_TOKEN",
  "apiKey": "sk_...",
  "command": "./progress.sh",
  "pollInterval": 15
}

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

Examples

# Poll every 15s; run progress.sh only when the app requests an update
status202 --token abc123 --command "./progress.sh" --poll-interval 15

# Report a file's contents whenever it changes, instead of polling
status202 --token abc123 --watch-file ./progress.txt

# One-shot report from cron, no polling
status202 --token abc123 --push --once --command "./progress.sh"

# apiKey-mode tracker
status202 --token abc123 --api-key sk_live_... --command "./progress.sh"

2. Managing trackers (trackers subcommand)

These act on your account, not a single tracker — creating, listing, updating, and deleting trackers themselves. They use your account API key instead of a per-tracker token, and call the /trackers endpoints of the API directly (see API Docs in the app for the raw HTTP reference).

Generate your account key from Settings → API access in the app. It's shown once — store it somewhere safe.

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

Account flag

| Flag | Description | | --- | --- | | --account-key <key> | Required. Your account API key (or STATUS202_ACCOUNT_KEY env var, or accountKey in status202.json). | | --json | Print raw JSON instead of a formatted summary. |

trackers create / trackers update fields

Every one of these is optional on update (only the fields you pass are changed); --name is required on create.

| Flag | Maps to | Notes | | --- | --- | --- | | --name <name> | name | Tracker display name. | | --description <text> | description | Optional description. | | --group-id <id> | groupId | Places the tracker in an existing group. | | --value-mode <mode> | valueMode | percent (0–100 directly) or range (reports a value within min/max). Default: percent. Can't be changed after creation. | | --auth-mode <mode> | authMode | open (secret is the URL token) or apiKey (requires an Authorization: Bearer header). Default: open. Can't be changed after creation — recreate the tracker instead. | | --update-mode <mode> | updateMode | push (you send updates whenever), webhook (Status 202 fetches a callback URL you host), or agent (this CLI polls and reports). Default: push. | | --min <n> | min | Range minimum (range mode only). | | --max <n> | max | Range maximum (range mode only). | | --callback-url <url> | callbackUrl | Your webhook URL (webhook update mode only). | | --time-tracking | timeTracking | Enables elapsed-time tracking on the tracker. |

trackers create prints the new tracker's id and endpoint, plus a one-time API key if you used --auth-mode apiKey — save it immediately, it isn't shown again.

Examples

# Create an agent-mode tracker, save the printed token for step 1 above
status202 trackers create --name "Nightly backup" --update-mode agent --time-tracking

# Create a range tracker with its own API key
status202 trackers create --name "Disk usage" --value-mode range --min 0 --max 500 --auth-mode apiKey

# List every tracker on your account
status202 trackers list --json

# Move a tracker into a group and rename it
status202 trackers update TRACKER_ID --name "DB backup" --group-id GROUP_ID

# Delete a tracker
status202 trackers delete TRACKER_ID

3. Managing groups (groups subcommand)

Same account API key as tracker management above. A group is either a plain collection (just for organizing trackers) or a project (also gets combined progress, and can notify you once every tracker in it is complete).

status202 groups list --with-rollup
status202 groups create --name "Q1 Launch" --kind project
status202 groups get GROUP_ID --with-trackers
status202 groups update GROUP_ID --name "Q1 Launch (final)"
status202 groups delete GROUP_ID --reassign-to OTHER_GROUP_ID

Group flags

| Flag | Maps to | Notes | | --- | --- | --- | | --name <name> | name | Group name. Required on create. | | --description <text> | description | Optional description. | | --kind <kind> | kind | collection (default) or project. | | --with-rollup | — | Include {total, done, avgPercent} on groups list/groups get. Costs two extra reads per group, so it's opt-in. | | --with-trackers | — | Include the full member tracker list on groups get. | | --reassign-to <id> | — | On groups delete, move member trackers into this group instead of ungrouping them. |

Examples

# List every group with combined progress
status202 groups list --with-rollup

# Create a project group, then place trackers in it
status202 groups create --name "Q1 Launch" --kind project
status202 trackers create --name "Design" --group-id GROUP_ID
status202 trackers create --name "Build" --group-id GROUP_ID

# List only the trackers in one group
status202 trackers list --group-id GROUP_ID

# Delete a group, keeping its trackers by moving them elsewhere
status202 groups delete GROUP_ID --reassign-to OTHER_GROUP_ID

General

| Flag | Applies to | Description | | --- | --- | --- | | --base-url <url> | all | API base URL. Default: https://api.status202.dev/v1. | | --config <path> | all | Path to a status202.json config file. | | -h, --help | all | Show usage for progress reporting, tracker management, and group management. |

Run status202 --help any time for the full in-terminal reference.