> ## Documentation Index > Fetch the complete documentation index at: https://docs.screenpipe.com/llms.txt > Use this file to discover all available pages before exploring further. # Install Screenpipe on macOS, Windows, and Linux > Install Screenpipe on macOS, Windows, or Linux. Record everything on screen and search screen history on Mac, Windows, and Linux. Start recording in minutes. Want the fastest path? See the [5-minute quickstart →](/quickstart) ## Free vs. Paid options Screenpipe offers three installation paths: 1. **CLI (fully free)** — `npx -y screenpipe@latest record` for local recording, search, and API access from the terminal. Open-source MIT license. 2. **Tauri desktop app (fully free)** — clone [github.com/screenpipe/screenpipe](https://github.com/screenpipe/screenpipe) and build locally for a visual timeline and UI. Open-source MIT license. No commercial support. 3. **Commercial desktop app** — download from [screenpi.pe/onboarding](https://screenpi.pe/onboarding) for prebuilt binaries, auto-updates, support, team sync, and enterprise auth. Free 7-day trial. ## Desktop app or CLI? | Choose | If you want | | - | - | | Desktop app | Visual timeline, scheduled tasks, connections, chat, settings, and guided permissions | | CLI | Free local recording, REST API access, and terminal-first workflows | ## Desktop app (recommended) Download the [desktop app](https://screenpi.pe/onboarding) and follow the installation instructions. Works on macOS, Windows, and Linux. The app manages recording, settings, search, scheduled tasks, and AI connections — no terminal needed. ## CLI ```bash theme={"system"} npx -y 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 -y Screenpipe\@latest record" not working If the command fails, try these fixes in order: **Unsupported platform:** ```bash theme={"system"} 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):** ```bash theme={"system"} npx -y screenpipe@latest --version ``` the CLI needs the platform-specific binary. re-running with `npx -y screenpipe@latest` pulls a fresh copy. **macOS: binary blocked by Gatekeeper:** If you see "app is damaged" or "permission denied", run: ```bash theme={"system"} 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:** ```bash theme={"system"} 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](https://dotnet.microsoft.com/en-us/download/dotnet/8.0). **Port 3030 already in use:** If Screenpipe is already running, the CLI will fail to bind. Check for existing processes: ```bash theme={"system"} lsof -i :3030 # macOS/Linux netstat -ano | findstr :3030 # Windows ``` Still stuck? [ask in Discord](https://discord.gg/screenpipe). ### Suppress CLI reminders (optional) When running `npx -y screenpipe@latest 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: ```bash theme={"system"} SCREENPIPE_NO_REMINDERS=1 npx -y screenpipe@latest record ``` Or set it once in your shell: ```bash theme={"system"} export SCREENPIPE_NO_REMINDERS=1 npx -y 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](https://screenpi.pe/onboarding) 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`. **API authentication is enabled by default** for security: ```bash theme={"system"} # get your API key SCREENPIPE_API_KEY=$(npx -y screenpipe@latest auth token) # check health curl http://localhost:3030/health \ -H "Authorization: Bearer $SCREENPIPE_API_KEY" # search your screen history curl "http://localhost:3030/search?q=example" \ -H "Authorization: Bearer $SCREENPIPE_API_KEY" ``` If you get an `unauthorized` error, you forgot the API key header. See "API authentication" section below for more options. ## Check and update your version To ensure you're running the latest version: ```bash theme={"system"} # check your current version npx -y screenpipe@latest --version ``` To update to the latest version, just run with `@latest` — it always pulls the newest release: ```bash theme={"system"} npx -y screenpipe@latest record ``` The latest version is always available at npm. If you're on an older version, you'll see a warning when you run `npx -y screenpipe@latest record`. ### API authentication API authentication is **enabled by default** when Screenpipe starts. Get your API key: ```bash theme={"system"} npx -y screenpipe@latest auth token ``` **Option 1: pass the key in the header (recommended)** ```bash theme={"system"} curl "http://localhost:3030/search?q=example" \ -H "Authorization: Bearer " ``` **Option 2: set the environment variable** ```bash theme={"system"} export SCREENPIPE_API_KEY=$(npx -y screenpipe@latest auth token) curl "http://localhost:3030/search?q=example" \ -H "Authorization: Bearer $SCREENPIPE_API_KEY" ``` **Option 3: pass as a query parameter (less secure)** ```bash theme={"system"} curl "http://localhost:3030/search?q=example&token=" ``` If you get `{"error":"unauthorized: API access requires authentication..."}`, double-check that you're passing the correct auth header or token. ## Connect to AI Screenpipe works with any AI that supports MCP or HTTP APIs. The fastest path is one command — it installs the Screenpipe skills and registers the MCP server for your agent: ```bash theme={"system"} npx -y screenpipe@latest agent setup ``` Where `` is one of `openclaw`, `hermes`, `claude-code`, `claude-desktop`, `codex`, `cursor`, or `windsurf`. Add `--api-url ` if Screenpipe runs on another machine. Prefer to wire it up manually? Here's where each tool plugs in: | Integration | How | | - | - | | **Claude desktop** | Add Screenpipe as MCP server ([guide](/mcp-server)) | | **Cursor** | Add Screenpipe MCP to your project ([guide](/mcp-server)) | | **Claude Code** | Use Screenpipe MCP or curl the API ([guide](/claude-code)) | | **Ollama** | Configure in app settings, use any local model | ## What's next? See all available automations — day recap, standup, time tracking, and more Add Screenpipe to Claude, Cursor, ChatGPT, or any AI tool Link Calendar, Google Docs, Notion, Obsidian for richer context Explore use cases — loop closing, meeting notes, time tracking, and more Copy-paste local API workflows for search, meetings, speakers, frames, and retention * [Search your screen history](/search-screen-history) — find anything you've seen * [API reference](/cli-reference) — REST API endpoints and parameters * [Troubleshooting](/troubleshooting) — fix common issues * [Join our Discord](https://discord.gg/screenpipe) — get help from the community [Download Screenpipe →](https://screenpi.pe/onboarding) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.