Pentify Terminal

Command reference

Every Pentify Terminal command, the API calls it makes, the scopes it needs, the errors it can return, and what it costs in workspace tokens.

All commands accept the global flags --api-token, --workspace, and --json. Resolution order for the bearer token is documented under Security & token storage. Errors map to the same canonical codes the HTTP API returns — see Errors.

`pentify login`

Pair the Terminal with a Pentify workspace via the browser.

Synopsis	`pentify login [--workspace <name>]`
API calls	Opens browser to `app.pentify.io/auth/terminal-pair`; polls `GET /auth/terminal/poll`.
Required scopes	None for `/poll` (public). The minted PAT carries `scans:read`, `scans:write`, `targets:read`, `targets:write`, `reports:read`, `usage:read`.
Retry-safe?	Yes. The poll loop is idempotent server-side as long as the same `device_id` is used per `pentify login` invocation.
Token cost	0 — the poll endpoint is not metered.

Error	Action
`not_paired_yet` (404)	Keep polling — the user hasn’t authorized yet.
`pairing_consumed` (410)	Re-run `pentify login`.
`validation_error` (400)	Bug in the client — file an issue.
`rate_limited` (429)	Back off per `Retry-After`.

`pentify logout`

Clear the local OS keychain entry. Does not revoke the server-side PAT.

Synopsis	`pentify logout`
API calls	None. Purely local.
Required scopes	n/a
Errors	OS-level keychain access denied (not an API error).
Retry-safe?	Yes. Idempotent — a second run on a logged-out terminal is a no-op.
Token cost	0

Revoke the server-side key

Server-side revocation lives in app.pentify.io/settings/api-keys. pentify logout only removes the local credential.

`pentify profile`

Show the signed-in user, current workspace, and the API key in use.

Synopsis	`pentify profile`
API calls	`GET /v1/profile`
Required scopes	`usage:read`
Retry-safe?	Yes. Idempotent GET.
Token cost	1 token

Error	Action
`invalid_api_key` (401)	Run `pentify login` to re-pair.
`insufficient_scope` (403)	Mint a wider key from Settings → API keys.
`internal_error` (5xx)	Retry once with backoff.

`pentify workspaces list`

List all Pentify workspaces accessible to the current key’s owner. The active pairing is returned first.

Synopsis	`pentify workspaces list`
API calls	`GET /v1/workspaces`
Required scopes	`usage:read`
Retry-safe?	Yes. Idempotent GET.
Token cost	1 token

Error	Action
`invalid_api_key` (401)	Run `pentify login`.
`insufficient_scope` (403)	Re-pair to mint a full-scope key.
`clerk_unavailable` (503)	Retry with exponential backoff.

`pentify scans create`

Queue a new scan against a verified target.

Synopsis	`pentify scans create <target> --type {quick\|standard\|compliance}[--idempotency-key <uuid>]`
API calls	`POST /v1/scans` with an `Idempotency-Key` header. The Terminal auto-generates a UUIDv4 if `--idempotency-key` is omitted, and persists it across retries within one logical invocation.
Required scopes	`scans:write`. The hostname must already be a verified `Target` in the workspace; if the Terminal needs to register one, `targets:write` is required for the sub-flow.
Retry-safe?	Only with the same `Idempotency-Key` (24h server-side dedupe TTL). Without the header, retries double-bill.
Token cost	`quick` 1,000 / `standard` 5,000 / `compliance` 25,000. Held at create, committed on completion, refunded on fail or cancel.

Error	Action
`validation_error` (400)	Bad `scan_type` — only quick/standard/compliance.
`target_not_verified` (409)	Run `pentify targets verify <hostname>` first.
`insufficient_tokens` (402)	Surface `details.top_up_url` to the user, stop.
`idempotency_key_conflict` (409)	Different body for the same key — generate a fresh UUID and retry.
`rate_limited` (429)	Back off per `Retry-After`.
`internal_error` (5xx)	Do not retry POST without the same `Idempotency-Key`.

`pentify scans list`

List recent scans for the current workspace, newest first.

Synopsis	`pentify scans list [--status {running\|queued\|completed\|failed\|canceled}] [--limit N] [--cursor <opaque>]`
API calls	`GET /v1/scans?status=&limit=&cursor=`
Required scopes	`scans:read`
Errors	Canonical 401 / 403 / 429 / 5xx — see Errors page.
Retry-safe?	Yes. Idempotent GET.
Token cost	1 token per call. Cursor pagination — the Terminal must not auto-paginate without explicit user opt-in.

`pentify scans get`

Fetch the current status of a single scan.

Synopsis	`pentify scans get <scan-id>`
API calls	`GET /v1/scans/{id}`
Required scopes	`scans:read`
Retry-safe?	Yes.
Token cost	1

Error	Action
`not_found` (404)	Scan id is wrong, or the scan belongs to another workspace.

`pentify findings list`

List findings (severity, title, evidence URLs, remediation) for a completed scan.

Synopsis	`pentify findings list <scan-id> [--severity {critical\|high\|medium\|low\|info}]`
API calls	`GET /v1/scans/{id}/findings`
Required scopes	`scans:read`
Retry-safe?	Yes.
Token cost	1

Error	Action
`not_found` (404)	Wrong id or wrong workspace.
Scan still running	The API returns the partial set; if `status != completed`, the Terminal surfaces “scan still running, findings may be incomplete”.

Evidence URL TTL

evidence_urls[] are R2 signed URLs with ~30 minute TTL. Download immediately — never cache the URL itself.

`pentify reports open`

Open the PDF report in the user’s default viewer.

Synopsis	`pentify reports open <scan-id>`
API calls	`GET /v1/scans/{id}/report.pdf` → 302 redirect to a signed R2 URL. Terminal follows the redirect, pipes the bytes into a temp file, and invokes the platform-specific opener (`open`, `xdg-open`, `start`).
Required scopes	`reports:read` (aliases `scans:read`).
Retry-safe?	Yes. The redirect target rotates each call — the Terminal always re-fetches before opening.
Token cost	1

Error	Action
`not_found` (404)	Wrong scan id.
Report not ready (409)	Scan hasn’t completed yet — wait and retry.

Token cost summary

At-a-glance budget reference. Mirrors Tokens & pricing.

Command	Cost (tokens)
`pentify login`	0
`pentify logout`	0
`pentify profile`	1
`pentify workspaces list`	1
`pentify scans create --type quick`	1,000
`pentify scans create --type standard`	5,000
`pentify scans create --type compliance`	25,000
`pentify scans list`	1 per page
`pentify scans get`	1
`pentify findings list`	1
`pentify reports open`	1