Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.screenpi.pe/llms.txt

Use this file to discover all available pages before exploring further.

want the fastest path? see the 5-minute quickstart →

​
desktop app or CLI?

chooseif you want
desktop appvisual timeline, pipes, connections, chat, settings, and guided permissions
CLIfree local recording, REST API access, and terminal-first workflows
download the desktop app and follow the installation instructions. works on macOS, Windows, and Linux. the app manages recording, settings, search, pipes, and AI connections — no terminal needed.

​
CLI

npx screenpipe@latest record
this starts the screenpipe daemon in the background and continuously records your screen. data is stored in ~/.screenpipe/ on your local machine.

​
troubleshooting: “npx screenpipe record” not working

if the command fails, try these fixes in order: unsupported platform: 
node -p "process.platform + '-' + process.arch"
if the output is not darwin-arm64, darwin-x64, linux-x64, or win32-x64, your platform is not supported. missing platform package (macOS/Windows/Linux): 
npm install screenpipe
# or
bun install screenpipe
the CLI needs the platform-specific binary. try a fresh install. macOS: binary blocked by Gatekeeper: if you see “app is damaged” or “permission denied”, run: 
xattr -d com.apple.quarantine ~/.npm/_npx/*/node_modules/screenpipe*/bin/screenpipe
or use the desktop app instead — it handles permissions automatically. Linux: missing system libraries: 
sudo apt install libasound2-dev ffmpeg  # ubuntu/debian
sudo dnf install alsa-lib ffmpeg         # fedora
Windows: .NET runtime missing: the screenpipe installer includes .NET, but if you’re using the CLI only, install .NET 8.0. port 3030 already in use: if screenpipe is already running, the CLI will fail to bind. check for existing processes: 
lsof -i :3030     # macOS/Linux
netstat -ano | findstr :3030  # Windows
still stuck? ask in Discord.

​
suppress CLI reminders (optional)

when running npx screenpipe record, the CLI prints a friendly reminder every 5 minutes to download the desktop app. if you prefer to run the CLI silently, disable the reminders: 
SCREENPIPE_NO_REMINDERS=1 npx screenpipe@latest record
or set it once in your shell: 
export SCREENPIPE_NO_REMINDERS=1
npx screenpipe@latest record

​
access your recorded timeline

after starting the CLI, you have three ways to access your screen history:
  1. Desktop app (easiest) — download the screenpipe app for a visual timeline and built-in search
  2. REST API — query recorded content directly via curl or code (see below)
  3. AI assistants — connect Claude, Cursor, or other tools via MCP

​
verify it’s running

once screenpipe starts, it serves an API on localhost:3030: 
# check health
curl http://localhost:3030/health

# search your screen history
curl "http://localhost:3030/search"

​
API authentication (required)

the search endpoint requires an API key. get your key by running: 
screenpipe auth token
then use it in curl: 
curl "http://localhost:3030/search?q=example" \
  -H "Authorization: Bearer <your-api-key>"
or set it as an environment variable: 
export SCREENPIPE_API_KEY=$(screenpipe auth token)
curl "http://localhost:3030/search?q=example" \
  -H "Authorization: Bearer $SCREENPIPE_API_KEY"

​
connect to AI

screenpipe works with any AI that supports MCP or HTTP APIs:
integrationhow
claude desktopadd screenpipe as MCP server (guide)
cursoradd screenpipe MCP to your project (guide)
claude codeuse screenpipe MCP or curl the API (guide)
ollamaconfigure in app settings, use any local model

​
what’s next?

browse pipes

see all available automations — day recap, standup, time tracking, and more

connect your AI

add screenpipe to Claude, Cursor, ChatGPT, or any AI tool

connect your apps

link Gmail, Calendar, Notion, Obsidian for richer context

what can I do?

explore use cases — loop closing, meeting notes, time tracking, and more

API recipes

copy-paste local API workflows for search, meetings, speakers, frames, and retention
download screenpipe →