Screenpipe CLI

Run every CLI command exactly like this, from a clean temp directory so bun x cannot collide with a project's node_modules:

cd "$(mktemp -d)" && ${SCREENPIPE_CLI:-bun x screenpipe@latest} <command>

$SCREENPIPE_CLI is an already-resolved native binary that screenpipe publishes and refreshes for you. When it is set, a call costs ~0.15s. The bun x screenpipe@latest fallback runs when it is not (a plain terminal, a fresh install, an offline machine) and costs ~4s, because @latest re-resolves the npm registry every single time. Never replace the whole expression with just bun x screenpipe@latest — you would give up the fast path for no reason.

Rules: every invocation is cd "$(mktemp -d)" && ${SCREENPIPE_CLI:-bun x screenpipe@latest} … · keep the ${SCREENPIPE_CLI:-…} form intact · never drop the cd prefix · copy the examples below verbatim rather than shortening them · because the cd changes your working directory, any path you pass must be absolute (~/... or /...), never relative (./my-pipe).

Works on macOS, Linux, and Windows: the CLI always runs under bash, and mktemp is present on all three (on Windows via the bundled git-portable usr/bin).

Use status, search, and state-changing commands as the terminal surface. For repeated or SQL reads, use MCP or the local API (see screenpipe-api). Never use an external SQLite client on the live database.

Sandboxed shells: some agents (e.g. Codex) block all shell network access, so bun x cannot fetch the package and CLI calls to localhost:3030 fail instantly. If that happens, use the screenpipe MCP tools instead of the CLI.

Recorder quickstart