pp-adminbyrequest

What this skill does

<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/devices/adminbyrequest/SKILL.md,
     regenerated post-merge by tools/generate-skills/. Hand-edits here are
     silently overwritten on the next regen. Edit the library/ source instead.
     See the repository agent guide, section "Generated artifacts: registry.json, cli-skills/". -->

# Admin By Request — Printing Press CLI

## Prerequisites: Install the CLI

This skill drives the `adminbyrequest-pp-cli` binary. **You must verify the CLI is installed before invoking any command from this skill.** If it is missing, install it first:

1. Install via the Printing Press installer. It defaults binaries to `$HOME/.local/bin` on macOS/Linux and `%LOCALAPPDATA%\Programs\PrintingPress\bin` on Windows:
   ```bash
   npx -y @mvanhorn/printing-press-library install adminbyrequest --cli-only
   ```
2. Verify: `adminbyrequest-pp-cli --version`
3. Ensure the reported install directory is on `$PATH` for the agent/runtime that will invoke this skill.

If the `npx` install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.3 or newer):

```bash
go install github.com/mvanhorn/printing-press-library/library/devices/adminbyrequest/cmd/adminbyrequest-pp-cli@latest
```

If `--version` reports "command not found" after install, the runtime cannot see the binary directory on `$PATH`. Do not proceed with skill commands until verification succeeds.

## When to Use This CLI

Use this CLI when you are administering an Admin By Request tenant from a terminal or AI agent: triaging pending requests in bulk, pulling audit data into a SIEM you have not yet wired up, generating offline PINs without opening the portal, or answering cross-resource questions (repeat requestors, agent-version drift) that the portal does not directly support.

## Unique Capabilities

These capabilities aren't available in any other tool for this API.

### Local state that compounds
- **`requests repeat-offenders`** — Surface the top users by elevation-request count over a configurable window, so admins can spot patterns the portal does not visualize.

  _When tracing repeated elevation attempts across a fleet, this is the single query that names the people; without it, an agent has to walk every request and aggregate manually._

  ```bash
  adminbyrequest-pp-cli requests repeat-offenders --window 30d --json
  ```
- **`correlate`** — Given an audit log entry ID, join it to nearby events on the same computer to reconstruct a full elevation timeline.

  _Incident response often asks what else happened on this machine when this admin session opened; this is the single command that answers it._

  ```bash
  adminbyrequest-pp-cli correlate 50461167 --window 5m --json
  ```

### Fleet hygiene
- **`inventory drift`** — List endpoints whose AbR client version is older than a target version, useful for upgrade campaigns.

  _Before any compliance audit, the agent should know which endpoints are running an old client; this is the one-liner._

  ```bash
  adminbyrequest-pp-cli inventory drift --client-version 8.7.2 --json
  ```
- **`inventory risk-score`** — Score each endpoint by elevation frequency, local-admin count, and AbR client version recency.

  _Lets an admin focus remediation effort on the endpoints most likely to be abused._

  ```bash
  adminbyrequest-pp-cli inventory risk-score --top 10 --json
  ```

### Reachability mitigation
- **`quota forecast`** — Track local API call count against the 100k-per-day quota and predict whether the current pace will exceed it before midnight.

  _Reachability mitigation: an agent that calls the API in a loop needs to know before it bricks the tenant for the day._

  ```bash
  adminbyrequest-pp-cli quota forecast --json
  ```

### Compliance and review
- **`requests denied-reasons`** — Tokenize the free-text deniedReason field across all denied requests and emit a top-N word distribution.

  _For compliance review and tone-of-policy checks, surfacing the actual words used is faster than reading each row._

  ```bash
  adminbyrequest-pp-cli requests denied-reasons --top 20 --json
  ```
- **`report compliance`** — Render audit entries for a user or computer over a window in a format suitable for auditors (CSV or markdown).

  _Auditor evidence requests always want a single artifact; this generates it in one command._

  ```bash
  adminbyrequest-pp-cli report compliance --since 2026-01-01 --user CHRISCOOMBES --format md
  ```

## Command Reference

**auditlog** — Admin session and elevation audit log entries

- `adminbyrequest-pp-cli auditlog delta` — Delta query for audit log changes (use timeNow/deltaTime ticks for resumable sync)
- `adminbyrequest-pp-cli auditlog list` — List audit log entries (admin sessions, app elevations, denied requests). Pagination is by id cursor.

**events** — Security and operational events emitted by AbR clients

- `adminbyrequest-pp-cli events` — List events. Use code filter to narrow to specific event types.

**inventory** — Endpoint inventory: hardware, software, OS, AbR agent version

- `adminbyrequest-pp-cli inventory list` — List inventoried endpoints. Use wantsoftware/wanthardware to expand.
- `adminbyrequest-pp-cli inventory pin` — Generate an offline elevation PIN code for a device. Pass --challenge for challenge-response mode.

**requests** — Pending, approved, and denied elevation requests

- `adminbyrequest-pp-cli requests approve` — Approve a pending elevation request.
- `adminbyrequest-pp-cli requests deny` — Deny a pending elevation request.
- `adminbyrequest-pp-cli requests list` — List elevation requests filtered by status.


**Hand-written commands**

- `adminbyrequest-pp-cli correlate <auditlog-id>` — Join an audit log entry to nearby events on the same computer (window in minutes)
- `adminbyrequest-pp-cli report` — Render compliance reports from synced data
- `adminbyrequest-pp-cli quota` — Track local API call count vs AbR's 100k/day quota


### Finding the right command

When you know what you want to do but not which command does it, ask the CLI directly:

```bash
adminbyrequest-pp-cli which "<capability in your own words>"
```

`which` resolves a natural-language capability query to the best matching command from this CLI's curated feature index. Exit code `0` means at least one match; exit code `2` means no confident match — fall back to `--help` or use a narrower query.

## Recipes


### Triage pending requests as JSON

```bash
adminbyrequest-pp-cli requests list --status pending --agent --select id,user.account,reason
```

Surface the pending elevation queue in agent-friendly JSON narrowed to the fields needed to decide. Approve or deny individual ids with `requests approve <id> --reason ...` or `requests deny <id> --reason ...`.

### Compliance evidence for one user

```bash
adminbyrequest-pp-cli report compliance --since 2026-01-01 --user CHRISCOOMBES --format md > evidence.md
```

Render every audit log entry for a user since a date into a markdown report.

### Find every device on an old client

```bash
adminbyrequest-pp-cli inventory drift --client-version 8.7.2 --json --select name,abrClientVersion
```

Inventory drift filters the synced inventory snapshot for endpoints below the target client version.

### Check today's API quota consumption

```bash
adminbyrequest-pp-cli quota show --agent
```

Local counter of API calls made today; the CLI tracks them in `~/.cache/adminbyrequest-pp-cli/http/` so this command itself never costs an API call.

### Audit-to-event timeline narrowed via --select

```bash
adminbyrequest-pp-cli correlate 50461167 --window 5m --agent --select audit.application.name,audit.user.account,events.eventText,events.eventTime
```

Joins audit entry to nearby events on the same computer; --select narrows the deeply nested response so the agent does not parse the full payload.

## Auth Setup

Set ADMINBYREQUEST_API_KEY in your environment. The CLI sends it via the apikey header.