# Screenpipe CLI

Set up and operate screenpipe from the terminal, including always-on recording, service...

- Repository: https://github.com/screenpipe/screenpipe (22202 stars)
- Category: Testing
- License: see repository
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add screenpipe/screenpipe --skill screenpipe-cli -g -a claude-code -y`
Codex: `npx skills add screenpipe/screenpipe --skill screenpipe-cli -g -a codex -y`
Cursor: `npx skills add screenpipe/screenpipe --skill screenpipe-cli -g -a cursor -y`
Gemini CLI: `npx skills add screenpipe/screenpipe --skill screenpipe-cli -g -a gemini-cli -y`

## Description

Set up and operate screenpipe from the terminal, including always-on recording, service modes, capture health, storage, local search, pipes, and connections. Use when the user asks to install, run, inspect, query, automate, or debug screenpipe without relying on the desktop app.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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`:

```bash
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

For a CLI-only user who wants this computer recorded continuously, use this sequence:

The rest: https://github.com/screenpipe/screenpipe/blob/HEAD/crates/screenpipe-core/assets/skills/screenpipe-cli/SKILL.md