Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 2 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ The Mintlify documentation source for [`privacykey/mantis`](https://github.com/p

Production is a Cloudflare Worker serving the static export as assets
([`wrangler.jsonc`](wrangler.jsonc)). `just deploy` builds and publishes it.
**Hostname:** `docs.mantis.privacykey.org` *(DNS not configured yet)*
**Hostname** [docs.mantis.privacykey.org](https://docs.mantis.privacykey.org/)

[![Project status](https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2Fprivacykey%2F.github%2Fmain%2Fbadges%2Fdocs-mantis.json)](https://github.com/privacykey/.github/blob/main/STATUS.md#docs-mantis)

Expand All @@ -17,9 +17,7 @@ Production is a Cloudflare Worker serving the static export as assets

## Read the docs

The published site is not live yet — no docs domain resolves for this project at the moment, so there is nothing to link here. Until it is published, read the pages in this repository directly: they are ordinary Markdown with Mintlify frontmatter, and GitHub renders them.

Start at [`index.mdx`](./index.mdx), or jump to [Getting started](./getting-started.md).
Read the [published documentation](https://docs.mantis.privacykey.org/) or start with the [Getting started source](./getting-started.md).

## Run it locally

Expand Down
5 changes: 4 additions & 1 deletion api.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ The CLI is the recommended interface, but everything it does is exposed over a p

```bash
export MANTIS=http://localhost:3000
export KEY=mantis_live_... # `mantis login` output, or read from the bootstrap log
export KEY=mantis_live_... # use your API key or read the bootstrap admin key from the server log

# Mint a key
curl -sX POST $MANTIS/api/keys \
Expand All @@ -25,6 +25,9 @@ curl -i $MANTIS/c/<public_id>
curl -s $MANTIS/api/keys/<id>/hits -H "Authorization: Bearer $KEY" | jq
```

On server builds from `main`, a temporary authentication dependency failure
returns HTTP `503` with `Retry-After: 1`. Wait and retry with the same credentials.

## Endpoint reference

Management endpoints are API-key authenticated with `Authorization: Bearer mantis_live_...`.
Expand Down
33 changes: 25 additions & 8 deletions cli.md
Original file line number Diff line number Diff line change
@@ -1,23 +1,40 @@
---
title: "CLI reference"
description: "Every mantis CLI command and flag, verified against the v0.2.0 source."
description: "Mantis CLI commands, options, and terminal output."
sidebarTitle: "CLI"
---

The `mantis` CLI is the primary way to work with a Mantis server (and with the
stateless [edge worker](/edge-deployment)). This page documents **every** command
and flag in the CLI, transcribed from the v0.2.0 source. For the conceptual
map — diagrams, mental model, common workflows — see `cli/COMMAND_MAP.md` in the
app repo.
The `mantis` CLI works with a Mantis server and the stateless
[edge worker](/edge-deployment). The
[command map](https://github.com/privacykey/mantis/blob/main/cli/COMMAND_MAP.md)
shows how the commands fit together.

New to the CLI? Run `mantis init` for guided, interactive setup, or `mantis`
with no arguments for a context-aware welcome screen.

<Note>
This reference covers CLI **v0.2.0**. Check yours with `mantis --version`, and
run `mantis doctor` after upgrading the server to confirm compatibility.
This reference covers the published CLI **v0.3.0**. The
[terminal output redesign](https://github.com/privacykey/mantis/pull/112) is
available when you build from `main`. Check your version with
`mantis --version` and run `mantis doctor` after upgrading the server.
</Note>

## Terminal output on main

`mantis --help` groups commands by task. The welcome screen shows next steps
for the server and edge setups it finds. Diagnostics in `mantis doctor`
distinguish failed checks from skipped checks and show recovery commands where
available.

`mantis status` puts tripped monitors first. In this example, **Finance share**
tripped four minutes ago. Run `mantis status ec7a10f3` to see what tripped it.

![Output from mantis status with sample data. One of three monitored keys is tripped, and one unmonitored key is omitted.](/images/cli-status.png)

For scripts, choose `--json` or the command's `--id-only` or `--url-only` flag
where available. Use `--color never` and `MANTIS_ASCII=1` when your terminal
needs plain text and ASCII symbols.

## Global flags

These can be combined with most commands. They're owned by the root `mantis`
Expand Down
7 changes: 6 additions & 1 deletion file-keys.md
Original file line number Diff line number Diff line change
Expand Up @@ -83,10 +83,15 @@ mantis download <key-id> --env ./.env
mantis download <key-id> --netrc ./.netrc
mantis download <key-id> --aws-credentials ./credentials

# Dashboard: key detail page → "file keys" card has download links for all formats
# Dashboard: open a key to download its artifact
# API: GET /api/keys/<id>/download?format=docx|xlsx|pptx|pdf|folder|nfc-label|apple-wallet|svg|html|md|eml|ics|vcf|rtf|cookies|bookmarks|env|aws-credentials|netrc|kubeconfig|ovpn|rdp (Bearer or session)
```

In the dashboard, use **new** to choose the file type first, or **bulk** to
create separate keys and download their artifacts in one ZIP. For documents and credential
bait, the first download marks that format on the key's detail page. Give each
format its own key so you can identify the artifact from its hit history.

**Office reader caveats**:
- ✅ Microsoft Office desktop apps — fetch external image on render (subject to **Protected View** for files marked "from internet"; first "Enable Editing" click triggers).
- ✅ LibreOffice (Writer/Calc/Impress) — fetches external content by default.
Expand Down
17 changes: 10 additions & 7 deletions getting-started.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,11 +11,11 @@ The CLI is the recommended way to drive mantis — the dashboard is a nice brows
brew install privacykey/tap/mantis
```

That gives you `mantis` on `$PATH` with shell completions, a man page, and the auto-update path from the Homebrew tap. (Building from source also works — see [`cli/README.md`](https://github.com/privacykey/mantis/tree/main/cli#install-from-this-repo) for `npm link` instructions.)
Homebrew puts `mantis` on `$PATH` with shell completions and a man page. Use `brew upgrade mantis` to update, or [build the CLI from source](https://github.com/privacykey/mantis/blob/main/cli/README.md#install-from-this-repo).

## 2. Pick where mantis lives

The CLI talks to either of two backends, with the same command surface:
The CLI uses `mantis new` for a server and `mantis edge mint` for a Cloudflare Worker.

| Backend | What it gives you | Where it runs |
|---|---|---|
Expand Down Expand Up @@ -78,7 +78,7 @@ mantis new

```bash
mantis new "ssh on prod" \
--notify-webhook https://discord.com/api/webhooks/... \
--notify discord:https://discord.com/api/webhooks/... \
--install shell --ssh-only \
--out ~/.zshrc.d/mantis.sh
```
Expand Down Expand Up @@ -108,8 +108,8 @@ mantis bulk-create \
--memo-template "{{area}} - {{device}}"
```

The output CSV is your input with `mantis_id`, `mantis_url`, and four more
columns appended. The input can also carry per-row `notify`, `response_kind`,
The output CSV keeps your input columns and appends the memo, key ID, public
ID, trigger URL, creation time, and any row error. The input can also carry per-row `notify`, `response_kind`,
`response_payload`, and `expires_at` columns so a row can vary from the rest —
`response_kind`, `response_payload`, and `expires_at` override the matching flag,
while a row's `notify` destinations are added on top of the `--notify` flags — see
Expand All @@ -125,8 +125,11 @@ The web dashboard at `/keys` is handy for clicking through a key's hits and seei
|---|---|
| `/keys` | `mantis list` |
| `/keys/<id>` | `mantis show <id>` or `mantis hits <id> --follow` |
| `/keys/new` | `mantis new` |
| `/inbox` (dev only) | `mantis hits last --follow` against a key pointing at `/inbox/demo` |
| **new** (`/keys/new`) | `mantis new` |
| **bulk** (`/keys/bulk`) | `mantis bulk-create` writes a CSV; the dashboard downloads a ZIP |
| **machine** (`/keys/device`) | `mantis device new` |

The optional [dev inbox](/dev-inbox) shows captured webhook payloads.

The dashboard authenticates by exchanging your API key for an httpOnly
`mantis_session` cookie. The cookie contains an opaque session token; the
Expand Down
8 changes: 8 additions & 0 deletions host-events.md
Original file line number Diff line number Diff line change
Expand Up @@ -161,6 +161,14 @@ move to an unguessable id.

For devices that do not expose useful webhooks, [`iot-helper/`](https://github.com/privacykey/mantis/tree/main/iot-helper) can watch LAN neighbor tables and log files, then fire the same Mantis URL for unexpected online/login events.

On `main`, regenerated Scrypted scripts report rejected HTTP
responses and delivery timeouts in the Scrypted script console. Reinstall the
generated script to pick up this behavior.

For Home Assistant OS or Supervised, use the
[local add-on packaging guide](https://github.com/privacykey/mantis/blob/main/iot-helper/homeassistant-addon/README.md)
to package the helper and copy the complete add-on folder into Home Assistant.

## What information each installer captures

Each installer sends `X-Mantis-*` headers alongside the hit, which the server parses into a structured `host_context` object exposed on the API + dashboard + CLI.
Expand Down
Binary file added images/cli-status.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
93 changes: 68 additions & 25 deletions llms-full.txt

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion llms.txt
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ This file indexes the mantis documentation site at https://docs.mantis.privacyke

- [HTTP API](https://docs.mantis.privacykey.org/api.md): Reference for key management endpoints, trigger responses, and webhook payloads.
- [Configuration](https://docs.mantis.privacykey.org/configuration.md): Required and optional environment variables for running Mantis.
- [CLI reference](https://docs.mantis.privacykey.org/cli.md): Every mantis CLI command and flag, verified against the v0.2.0 source.
- [CLI reference](https://docs.mantis.privacykey.org/cli.md): Mantis CLI commands, options, and terminal output.
- [CLI backup & restore](https://docs.mantis.privacykey.org/cli-backup.md): Export all your CLI profiles and plugin manifest into a passphrase-encrypted file, then restore on another machine.
- [Updating](https://docs.mantis.privacykey.org/updating.md): Update commands for the server, CLI, edge worker, IoT helper, and host installers.
- [Changelog](https://docs.mantis.privacykey.org/changelog.md): Published Mantis releases — CLI and server — what changed and where the full notes live.
Expand Down
Loading
Loading