diff --git a/README.md b/README.md index 82cac2f..7d5958a 100644 --- a/README.md +++ b/README.md @@ -32,7 +32,7 @@ Components are versioned independently: the server, the CLI, and the edge worker ## What it does -- **File keys** in 10 formats (`.docx` / `.xlsx` / `.pptx` / `.pdf` / `.svg` / `.html` / `.md` / `.eml` / `.ics` / `.vcf`) plus a honey-directory `.zip` and Apple Wallet `.pkpass` passes (install / uninstall / fetch callbacks each fire the key) +- **File keys** in 11 formats (`.docx` / `.xlsx` / `.pptx` / `.pdf` / `.rtf` / `.svg` / `.html` / `.md` / `.eml` / `.ics` / `.vcf`) plus credential and connection-profile bait, a honey-directory `.zip`, and Apple Wallet `.pkpass` passes (install / uninstall / fetch callbacks each fire the key) - **Host-event installers** — shell, sudo, login, boot, wake, network — for macOS, Linux, and Windows, with parsed `X-Mantis-*` context including SSH client IP - **Web canaries** — CSS-background and JS clone-detector — plus NFC NDEF tag URLs and printable QR/NFC sticker labels - **Smart-home triggers** via Home Assistant, Scrypted, and an optional LAN watcher @@ -85,6 +85,7 @@ The prose documentation lives at [docs.mantis.privacykey.org](https://docs.manti - [Getting started](https://docs.mantis.privacykey.org/getting-started) — five steps from `brew install` to first key - [Use cases](https://docs.mantis.privacykey.org/use-cases) — defensive, detective, operational and adversarial patterns +- [CLI reference](https://docs.mantis.privacykey.org/cli/) and [command map](./cli/COMMAND_MAP.md) — setup, key management, monitoring, and scripting - [HTTP API](https://docs.mantis.privacykey.org/api) — endpoints, response kinds, webhook payload shape - [File keys](https://docs.mantis.privacykey.org/file-keys), [host-event keys](https://docs.mantis.privacykey.org/host-events), [deployment](https://docs.mantis.privacykey.org/deployment), [updating](https://docs.mantis.privacykey.org/updating) - [`CHANGELOG.md`](./CHANGELOG.md) — what changed in each release, with the upgrade steps (migrations, settings, artifacts to regenerate) diff --git a/cli/README.md b/cli/README.md index 00677bc..e49061f 100644 --- a/cli/README.md +++ b/cli/README.md @@ -7,14 +7,18 @@ For a visual overview of every command and how they relate, see ## Install (from this repo) +From the repository root, use the Node version in [`.nvmrc`](../.nvmrc) +and the pnpm version pinned in [`package.json`](../package.json). + ```bash -cd cli -npm install -npm run build -npm link # exposes `mantis` on $PATH +pnpm install --frozen-lockfile +pnpm --filter @mantis/cli run build +node cli/dist/index.js --help ``` -For one-off use without linking: `node cli/dist/index.js `. +For the published binary, run `brew install privacykey/tap/mantis`. This +README follows the source tree, so terminal examples can differ from the +version installed by Homebrew. ## Quickstart @@ -39,6 +43,24 @@ Credentials are stored in: - OS keychain (`mantis-cli-cf` service, account = base URL) — Cloudflare Access service-auth credentials (if configured) - `~/.cloudflared/` — short-lived JWTs cached by the `cloudflared` binary itself (managed externally; we don't touch them) +## Reading the terminal output + +Run `mantis --help` for commands grouped by task, or +`mantis --help` for its options. Running `mantis` with no arguments +shows next steps based on whether you have a server profile, an edge key, or +both. + +- `mantis status` puts tripped keys first and reports unavailable monitor + states. Run `mantis status ` for the hits behind a trip, or + `mantis status --watch` for a live view. +- `mantis hits ` shows recent hits. Use `--verbose` for full headers or + `--follow` to see new hits as they arrive. +- `mantis doctor` lists passed, skipped, and failed checks with next steps + where available. Use it after setting up a profile or changing hosts. + +Use [machine-readable output](#scripting) when another program consumes the +result. + ## Commands | Command | Purpose | diff --git a/cli/share/man/man1/mantis.1 b/cli/share/man/man1/mantis.1 index a10d5e4..0e0f8db 100644 --- a/cli/share/man/man1/mantis.1 +++ b/cli/share/man/man1/mantis.1 @@ -213,7 +213,7 @@ Poll across all keys (or one) and print new hits as they arrive. .B mantis status [id] [\-w] [\-\-tripped\-only] [\-i N] Show monitor state. Without .IR id : -summary across all monitored keys. With +summary across all monitored keys, with tripped keys first. With .IR id : detail (window: hits + expiry; latch: hits since reset). .BR \-w / \-\-watch @@ -291,7 +291,8 @@ and vectors with a server-side dedupe window are chattier on edge. .TP .B mantis doctor [\-\-public\-url URL] Health-check CLI config, server health, auth, Cloudflare state, and split -public/private hosts. +public/private hosts. The report distinguishes failed and skipped checks +and shows recovery steps where available. .TP .B mantis detect [\-\-scope user|system|all] [\-\-deep] [\-\-verbose] @@ -462,6 +463,9 @@ mantis detect \-\-scope all \-\-deep .RE .SH SEE ALSO +CLI reference at +.UR https://docs.mantis.privacykey.org/cli/ +.UE . Project README at .UR https://github.com/privacykey/mantis .UE diff --git a/cli/share/tldr/mantis.md b/cli/share/tldr/mantis.md index 943be0a..f97561b 100644 --- a/cli/share/tldr/mantis.md +++ b/cli/share/tldr/mantis.md @@ -16,7 +16,7 @@ `mantis hits last --follow` -- Create a key with a decoy PDF that fires when the file is opened: +- Create a key and a decoy PDF that can fire in a compatible reader: `mantis new "{{memo}}" --pdf {{path/to/decoy.pdf}}` diff --git a/docs/GETTING-STARTED.md b/docs/GETTING-STARTED.md index 2d21f6c..34f7d26 100644 --- a/docs/GETTING-STARTED.md +++ b/docs/GETTING-STARTED.md @@ -1,8 +1,5 @@ # Getting started -Moved out of the top-level README so it stays short. Everything here was in the -README before; nothing has been added. - **Stateful server or stateless edge?** Run the full **server** (`docker compose`, Postgres-backed) when you want the web dashboard, notification queue, file/host-event keys, and history. Run the **edge** @@ -41,8 +38,10 @@ Open and paste that same key to sign in to the web dashboard. Then log in the CLI and mint a key: ```bash -mantis --key mantis_live_... login --url http://localhost:3000 -mantis new "first mantis" -w http://localhost:3000/inbox/demo +mantis login --url http://localhost:3000 # paste the admin key when prompted +key_id="$(mantis new "first mantis" --id-only)" +curl -fsS -o /dev/null "$(mantis show "$key_id" --url-only)" +mantis hits "$key_id" ``` This is fine for evaluation but **don't rely on a laptop deploy for canaries