{"slug":"screenpipe-cli","title":"screenpipe-cli","summary":"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.","platform":"Claude","tags":[],"authorName":"LLM Mart","authorSlug":"llm-mart","score":0,"source":"github","price":null,"verified":false,"createdAt":"2026-10-29T19:13:19.637104Z","repo":{"url":"https://github.com/tonydzi/second-brain-starter-kit","stars":15,"forks":5,"license":"MIT","updatedAt":"2026-11-19T13:51:48Z"},"bodyHtml":"<hr>\n<h2>name: screenpipe-cli\ndescription: 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.</h2>\n<h1>Screenpipe CLI</h1>\n<p>Run every CLI command exactly like this, from a clean temp directory so <code>bun x</code> cannot collide with a project's <code>node_modules</code>:</p>\n<pre><code>cd \"$(mktemp -d)\" &amp;&amp; ${SCREENPIPE_CLI:-bun x screenpipe@latest} &lt;command&gt;\n</code></pre>\n<p><code>$SCREENPIPE_CLI</code> is an already-resolved native binary that screenpipe publishes and refreshes for you. When it is set, a call costs <strong>~0.15s</strong>. The <code>bun x screenpipe@latest</code> fallback runs when it is not (a plain terminal, a fresh install, an offline machine) and costs <strong>~4s</strong>, because <code>[аккаунт]</code> re-resolves the npm registry every single time. Never replace the whole expression with just <code>bun x screenpipe@latest</code> — you would give up the fast path for no reason.</p>\n<p><strong>Rules:</strong> every invocation is <code>cd \"$(mktemp -d)\" &amp;&amp; ${SCREENPIPE_CLI:-bun x screenpipe@latest} …</code> · keep the <code>${SCREENPIPE_CLI:-…}</code> form intact · never drop the <code>cd</code> prefix · copy the examples below verbatim rather than shortening them · because the <code>cd</code> changes your working directory, <strong>any path you pass must be absolute</strong> (<code>~/...</code> or <code>/...</code>), never relative (<code>./my-pipe</code>).</p>\n<p>Works on macOS, Linux, and Windows: the CLI always runs under bash, and <code>mktemp</code> is present on all three (on Windows via the bundled git-portable <code>usr/bin</code>).</p>\n<p>Use <code>status</code>, <code>search</code>, and state-changing commands as the terminal surface. For repeated or SQL reads, use MCP or the local API (see <code>screenpipe-api</code>). Never use an external SQLite client on the live database.</p>\n<blockquote>\n<p><strong>Sandboxed shells:</strong> some agents (e.g. Codex) block all shell network access, so <code>bun x</code> cannot fetch the package and CLI calls to <code>localhost:3030</code> fail instantly. If that happens, use the screenpipe MCP tools instead of the CLI.</p>\n</blockquote>\n<h2>Recorder quickstart</h2>\n<p>For a CLI-only user who wants this computer recorded continuously, use this sequence:</p>\n<pre><code>cd \"$(mktemp -d)\" &amp;&amp; ${SCREENPIPE_CLI:-bun x screenpipe@latest} doctor\ncd \"$(mktemp -d)\" &amp;&amp; ${SCREENPIPE_CLI:-bun x screenpipe@latest} service install\ncd \"$(mktemp -d)\" &amp;&amp; ${SCREENPIPE_CLI:-bun x screenpipe@latest} status\n</code></pre>\n<p><code>service install</code> defaults to <strong>recorder mode</strong>: screen + audio capture, local indexing, and the API, launched at boot/login and restarted after failures. On macOS, resolve Screen Recording, Microphone, and Accessibility permission warnings reported by <code>doctor</code>; a background service cannot bypass OS consent.</p>\n<p>Use the foreground process only for an interactive session or live debugging:</p>\n<pre><code>cd \"$(mktemp -d)\" &amp;&amp; ${SCREENPIPE_CLI:-bun x screenpipe@latest} record\n</code></pre>\n<p>Use API-only server mode only when the machine should serve existing or synced data without recording itself:</p>\n<pre><code>cd \"$(mktemp -d)\" &amp;&amp; ${SCREENPIPE_CLI:-bun x screenpipe@latest} service install --mode server\n</code></pre>\n<p>Running <code>service install</code> again switches modes and restarts the service immediately. <code>service uninstall</code> stops and removes it.</p>\n<h2>Status and diagnostics</h2>\n<p>Start every investigation with:</p>\n<pre><code>cd \"$(mktemp -d)\" &amp;&amp; ${SCREENPIPE_CLI:-bun x screenpipe@latest} status\n</code></pre>\n<p>This reports the distinction that matters:</p>\n<ul>\n<li><code>recording normally</code>: the API is healthy and at least one capture stream is active</li>\n<li><code>serving normally</code>: intentional server mode; the API is healthy and local capture is disabled</li>\n<li><code>not capturing</code>: the process is up but no capture stream is active</li>\n<li><code>needs attention</code>: the health endpoint reports degraded/unhealthy capture</li>\n<li><code>stopped</code>: no screenpipe health endpoint answered on the selected port</li>\n</ul>\n<p>It also prints screen/audio freshness, active devices, history counts, total storage, and the exact SQLite path. Do not infer recording from a PID, an open port, or <code>service status</code>; those prove a process exists, not that new data is arriving.</p>\n<p>For scripts and agents, use structured output:</p>\n<pre><code>cd \"$(mktemp -d)\" &amp;&amp; ${SCREENPIPE_CLI:-bun x screenpipe@latest} status --json\n</code></pre>\n<p>Important fields are <code>running</code>, <code>health.status</code>, <code>health.frame_status</code>, <code>health.audio_status</code>, <code>last_capture</code>, <code>last_audio_capture</code>, <code>storage_size_bytes</code>, and <code>database_path</code>. Treat <code>running: true</code> as API availability only; inspect capture status and timestamps before claiming recording is healthy.</p>\n<p>Useful follow-ups:</p>\n<pre><code>cd \"$(mktemp -d)\" &amp;&amp; ${SCREENPIPE_CLI:-bun x screenpipe@latest} service status\ncd \"$(mktemp -d)\" &amp;&amp; ${SCREENPIPE_CLI:-bun x screenpipe@latest} doctor\ncd \"$(mktemp -d)\" &amp;&amp; ${SCREENPIPE_CLI:-bun x screenpipe@latest} diagnose --dry-run\n</code></pre>\n<p><code>diagnose --dry-run</code> saves a support bundle locally and does not upload it. Do not run <code>diagnose</code> without <code>--dry-run</code> unless the user explicitly wants to send diagnostics to screenpipe support.</p>\n<h2>Query local history</h2>\n<p><code>search</code> is Screenpipe's supported daemon-free fallback. Prefer JSON Lines; never replace it with a direct database command:</p>\n<pre><code>cd \"$(mktemp -d)\" &amp;&amp; ${SCREENPIPE_CLI:-bun x screenpipe@latest} search --start \"30m ago\" --json\ncd \"$(mktemp -d)\" &amp;&amp; ${SCREENPIPE_CLI:-bun x screenpipe@latest} search \"project alpha\" --start \"7d ago\" --json\ncd \"$(mktemp -d)\" &amp;&amp; ${SCREENPIPE_CLI:-bun x screenpipe@latest} search --content-type audio --start \"2h ago\" --json\ncd \"$(mktemp -d)\" &amp;&amp; ${SCREENPIPE_CLI:-bun x screenpipe@latest} search --app \"Code\" --focused --start \"1d ago\" --json\n</code></pre>\n<p>Use <code>--limit</code>, <code>--offset</code>, <code>--end</code>, <code>--window</code>, <code>--browser-url</code>, <code>--speaker</code>, and <code>--max-content-length</code> to bound output. An empty result is not evidence that capture is healthy; check <code>status</code> and freshness separately.</p>\n<h3>SQL analysis through Screenpipe</h3>\n<p>When the daemon is running, use the MCP <code>query_recordings</code> tool. If MCP is unavailable but authenticated localhost requests work, use the daemon's read-only SQL endpoint:</p>\n<pre><code>curl -sS -X POST \"${SCREENPIPE_LOCAL_API_URL:-http://localhost:3030}/raw_sql\" \\\n  -H \"Authorization: Bearer $SCREENPIPE_LOCAL_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"query\":\"SELECT COUNT(*) AS frame_count FROM frames LIMIT 1\"}'\n</code></pre>\n<p>Never access live <code>db.sqlite</code>, <code>db.sqlite-wal</code>, or <code>db.sqlite-shm</code> directly. If MCP, API, and CLI are unavailable, report it. Run database checks or recovery only through Screenpipe with the recorder stopped.</p>\n<h2>Shell</h2>\n<ul>\n<li><strong>All platforms</strong> → <code>bash</code> (on Windows, the bundled git-portable bash is used automatically)</li>\n</ul>\n<blockquote>\n<p><strong>Note:</strong> the bash tool truncates output around ~50 KB. Long listings (<code>connection list</code>, <code>pipe list</code>, etc.) are sorted with connected/enabled rows first, but if you need a specific row, pipe through <code>grep</code> or <code>head</code> rather than scanning the full output — e.g. <code>cd \"$(mktemp -d)\" &amp;&amp; ${SCREENPIPE_CLI:-bun x screenpipe@latest} connection list | grep -E 'browser|connected'</code>.</p>\n</blockquote>\n<hr>\n<h2>Pipe Management</h2>\n<p>Pipes are markdown-based AI automations that run on schedule. Each pipe lives at <code>~/.screenpipe/pipes/&lt;name&gt;/pipe.md</code>.</p>\n<h3>Commands</h3>\n<pre><code>cd \"$(mktemp -d)\" &amp;&amp; ${SCREENPIPE_CLI:-bun x screenpipe@latest} pipe list                    # List all pipes (compact table)\ncd \"$(mktemp -d)\" &amp;&amp; ${SCREENPIPE_CLI:-bun x screenpipe@latest} pipe enable &lt;name&gt;           # Enable a pipe\ncd \"$(mktemp -d)\" &amp;&amp; ${SCREENPIPE_CLI:-bun x screenpipe@latest} pipe disable &lt;name&gt;          # Disable a pipe\ncd \"$(mktemp -d)\" &amp;&amp; ${SCREENPIPE_CLI:-bun x screenpipe@latest} pipe run &lt;name&gt;              # Run once immediately (for testing)\ncd \"$(mktemp -d)\" &amp;&amp; ${SCREENPIPE_CLI:-bun x screenpipe@latest} pipe logs &lt;name&gt;             # View execution logs\ncd \"$(mktemp -d)\" &amp;&amp; ${SCREENPIPE_CLI:-bun x screenpipe@latest} pipe install &lt;url-or-abs-path&gt;  # Install from GitHub or an absolute local path\ncd \"$(mktemp -d)\" &amp;&amp; ${SCREENPIPE_CLI:-bun x screenpipe@latest} pipe delete &lt;name&gt;           # Delete a pipe\ncd \"$(mktemp -d)\" &amp;&amp; ${SCREENPIPE_CLI:-bun x screenpipe@latest} pipe models list             # View AI model presets\n</code></pre>\n<h3>Creating a Pipe</h3>\n<p>Create <code>~/.screenpipe/pipes/&lt;name&gt;/pipe.md</code> with YAML frontmatter + prompt:</p>\n<pre><code>---\nschedule: every 30m\nenabled: true\npreset: [\"Primary\", \"Fallback\"]\n---\n\nYour prompt instructions here. The AI agent executes this on schedule.\n\n## What to do\n\n1. Query screenpipe search API for recent activity\n2. Process results\n3. Output summary / send notification\n</code></pre>\n<p><strong>Schedule syntax</strong>:</p>\n<ul>\n<li>Recurring: <code>every 30m</code>, <code>every 1h</code>, <code>every day at 9am</code>, <code>every monday at 9am</code>, or cron <code>*/30 * * * *</code>, <code>0 9 * * *</code></li>\n<li>One-off (fires once, then auto-disables): <code>at &lt;RFC3339 timestamp&gt;</code> — e.g. <code>at 2026-04-29T17:00:00-07:00</code></li>\n<li>Manual only: <code>manual</code> (run via <code>pipe run</code> or API trigger)</li>\n</ul>\n<p><strong>One-off scheduled tasks</strong> (use this when the user says \"in 2 days\", \"tomorrow at 5pm\", \"next Monday\", \"remind me to check X later\", or any other future-time deferred action):</p>\n<pre><code>---\nschedule: at 2026-04-29T17:00:00-07:00\nenabled: true\npreset: auto\n---\n\nCheck Gmail for a reply from Mark about the HIPAA evidence pack.\nIf found, summarize and send a notification. If not, note it.\n</code></pre>\n<p>Resolve \"in 2 days\" / \"tomorrow 5pm\" / \"next Monday\" against the user's local timezone (which is in the context header), format as RFC3339 with offset, and put it in the <code>at &lt;iso&gt;</code> schedule.</p>\n<p>When fired, the pipe auto-disables itself — <code>enabled: false</code> is set in the local-overrides file. The pipe.md stays on disk as history. Users see upcoming one-offs in the chat sidebar's \"upcoming\" section with a countdown (\"in 2d 4h\"). To cancel before fire time: <code>pipe disable &lt;name&gt;</code>. To re-run after firing: <code>pipe enable &lt;name&gt;</code> then <code>pipe run &lt;name&gt;</code> (or set a new <code>at &lt;iso&gt;</code>).</p>\n<p><strong>Config fields</strong>: <code>schedule</code>, <code>enabled</code> (bool), <code>preset</code> (string or array — e.g. <code>\"Oai\"</code> or <code>[\"Primary\", \"Fallback\"]</code>), <code>history</code> (bool — include previous output as context)</p>\n<p>Screenpipe prepends a context header with time range, timezone, OS, and API URL before each execution. No template variables needed.</p>\n<p>After creating:</p>\n<pre><code>cd \"$(mktemp -d)\" &amp;&amp; ${SCREENPIPE_CLI:-bun x screenpipe@latest} pipe install ~/.screenpipe/pipes/my-pipe\ncd \"$(mktemp -d)\" &amp;&amp; ${SCREENPIPE_CLI:-bun x screenpipe@latest} pipe enable my-pipe\ncd \"$(mktemp -d)\" &amp;&amp; ${SCREENPIPE_CLI:-bun x screenpipe@latest} pipe run my-pipe   # terminal-only; in-app chat uses the workflow below\n</code></pre>\n<h3>Testing from in-app chat</h3>\n<p>The cloud JWT is intentionally absent from Bash. Do not expose or recover it, and do not use standalone <code>pipe run</code>. Test through the authenticated desktop runtime:</p>\n<pre><code>api=\"${SCREENPIPE_LOCAL_API_URL:-http://localhost:3030}\"\nauth=\"Authorization: Bearer $SCREENPIPE_LOCAL_API_KEY\"\ncurl -sS -X POST -H \"$auth\" \"$api/pipes/my-pipe/run\"\ncurl -sS -H \"$auth\" \"$api/pipes/my-pipe/logs\"\n</code></pre>\n<p><code>{\"success\":true}</code> means the run started, not that it passed. Poll for a new terminal log. Bind only after <code>success: true</code>; otherwise report its <code>stderr</code> and leave the Live View unchanged.</p>\n<h3>Editing Config</h3>\n<p>Edit frontmatter in <code>~/.screenpipe/pipes/&lt;name&gt;/pipe.md</code> directly, or use the API:</p>\n<pre><code>curl -X POST http://localhost:3030/pipes/&lt;name&gt;/config \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"config\": {\"schedule\": \"every 1h\", \"enabled\": true}}'\n</code></pre>\n<h3>Output &amp; Artifacts</h3>\n<p>Pipes can produce user-facing output files that appear in the Artifacts library.</p>\n<p><strong>Standard path</strong> — for files inside the pipe directory:</p>\n<ul>\n<li>Declare them in frontmatter under <code>artifacts:</code>:\n<pre><code>artifacts:\n  - path: \"output/report.md\"\n    title: \"Weekly Report\"\n    kind: \"markdown\"\n</code></pre>\n</li>\n<li>Write results to the declared path. After execution, they are auto-registered.</li>\n</ul>\n<p><strong>External path</strong> — for files outside the pipe directory (shared locations, user folders, vaults):</p>\n<ul>\n<li>Use the <code>register_artifact</code> tool during execution:\n<pre><code>register_artifact(file_path=\"/path/to/deliverable.md\", title=\"Weekly Report\")\n</code></pre>\n</li>\n<li>The tool registers an existing file by its absolute path. The file must already exist on disk.</li>\n<li>Only register finished deliverables — not scratch files, caches, or internal state.</li>\n</ul>\n<h3>Rules</h3>\n<ol>\n<li>Use <code>pipe list</code> (not <code>--json</code>) — table output is compact</li>\n<li>Never dump full pipe JSON — can be 15MB+</li>\n<li>Check logs first when debugging: <code>pipe logs &lt;name&gt;</code></li>\n<li>Outside in-app chat, use <code>pipe run &lt;name&gt;</code> before waiting for a schedule; in-app chat uses the authenticated runtime above</li>\n</ol>\n<hr>\n<h2>Connection Management</h2>\n<p>Manage integrations (Telegram, Slack, Discord, Email, Todoist, Teams) from the CLI.</p>\n<h3>Commands</h3>\n<pre><code>cd \"$(mktemp -d)\" &amp;&amp; ${SCREENPIPE_CLI:-bun x screenpipe@latest} connection list              # List all connections + status\ncd \"$(mktemp -d)\" &amp;&amp; ${SCREENPIPE_CLI:-bun x screenpipe@latest} connection list --json       # JSON output\ncd \"$(mktemp -d)\" &amp;&amp; ${SCREENPIPE_CLI:-bun x screenpipe@latest} connection get &lt;id&gt;          # Show status + non-secret settings\ncd \"$(mktemp -d)\" &amp;&amp; ${SCREENPIPE_CLI:-bun x screenpipe@latest} connection get &lt;id&gt; --json   # JSON output\ncd \"$(mktemp -d)\" &amp;&amp; ${SCREENPIPE_CLI:-bun x screenpipe@latest} connection set &lt;id&gt; key=val  # Save credentials\ncd \"$(mktemp -d)\" &amp;&amp; ${SCREENPIPE_CLI:-bun x screenpipe@latest} connection test &lt;id&gt;         # Test a connection\ncd \"$(mktemp -d)\" &amp;&amp; ${SCREENPIPE_CLI:-bun x screenpipe@latest} connection remove &lt;id&gt;       # Remove credentials\n</code></pre>\n<h3>Examples</h3>\n<pre><code># Set up Telegram\ncd \"$(mktemp -d)\" &amp;&amp; ${SCREENPIPE_CLI:-bun x screenpipe@latest} connection set telegram bot_token=123456:ABC-DEF chat_id=[id]\n\n# Set up Slack webhook\ncd \"$(mktemp -d)\" &amp;&amp; ${SCREENPIPE_CLI:-bun x screenpipe@latest} connection set slack webhook_url=https://hooks.slack.com/services/...\n\n# Verify it works\ncd \"$(mktemp -d)\" &amp;&amp; ${SCREENPIPE_CLI:-bun x screenpipe@latest} connection test telegram\n\n# Check what's connected\ncd \"$(mktemp -d)\" &amp;&amp; ${SCREENPIPE_CLI:-bun x screenpipe@latest} connection list\n</code></pre>\n<p>Connection IDs: <code>telegram</code>, <code>slack</code>, <code>discord</code>, <code>email</code>, <code>todoist</code>, <code>teams</code>, <code>google-calendar</code>, <code>openclaw</code></p>\n<p>Credentials are stored locally and are not printed by <code>connection get</code>.</p>\n<p><strong>Per-integration details</strong>: don't guess API shapes from this skill. Run <code>connection list</code> for self-describing local endpoints. <code>connection get &lt;id&gt;</code> returns only status and non-secret settings.</p>\n<h2>Publishing pipes to the store</h2>\n<pre><code>screenpipe pipe publish &lt;pipe-name&gt;\n</code></pre>\n<p>Reads <code>~/.screenpipe/pipes/&lt;pipe-name&gt;/pipe.md</code>, extracts title/description/icon/category from YAML frontmatter, and publishes to the screenpipe pipe store. Requires auth (SCREENPIPE_API_KEY env var or <code>~/.screenpipe/auth.json</code>).</p>\n\n<hr>\n<p><strong>Like this skill?</strong> It is part of <a href=\"https://github.com/tonydzi/second-brain-starter-kit\">second-brain-starter-kit</a>: the second brain we built for ourselves and run every day at Palo Alto AI Research Lab. Install the whole set with <code>npx skills add tonydzi/second-brain-starter-kit</code>. Everything is open source and free, so take what you need.</p>\n<p>Flagships worth a look on their own: <a href=\"https://github.com/tonydzi/secondop-panel\">secondop-panel</a> (a second opinion from a panel of external models), <a href=\"https://github.com/tonydzi/claude-memory-tidy\">claude-memory-tidy</a> (stop your agent's memory from rotting), <a href=\"https://github.com/tonydzi/telegram-mcp-kit\">telegram-mcp-kit</a> (your own Telegram over MCP in about 15 minutes).</p>\n<p>Author: <strong>Anton Dziatkovskii</strong>, Palo Alto AI Research Lab. Telegram <a href=\"https://t.me/tonydzi\">@tonydzi</a> - WhatsApp <a href=\"https://wa.me/13412229178\">+1 341 222 9178</a> - X <a href=\"https://x.com/Tony_Stef_\">@Tony_Stef_</a></p>\n<p><strong>Engineers: want to test-drive this setup?</strong> Message me. I hand out free starter seeds to engineers who test and report back, and custom skill requests are welcome.</p>\n","files":[{"path":"SKILL.md","sizeBytes":15696,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"clean","suspicious":0,"notes":0,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-10-29T19:28:09.973542Z","sha256":"0C35575BCFFE7DBDA9B801F272B0F982E6CEE7E1CE57E19B47CF3C797FA386BA","sizeBytes":5979},"review":null,"source":{"repositoryUrl":"https://github.com/tonydzi/second-brain-starter-kit","path":"skills/screenpipe-cli","license":"MIT","commit":"fdb53d7f98ebafccbe3daf2dac0d5fa3600eb282","subtreeSha":"D48B5FE2CF6C678FD02439C59AF99B61458CAC98AA124DE9C82E0EB1A35149CF","lastSyncedAt":"2026-11-19T20:10:55.345847Z"},"reviewedAt":"2026-10-29T19:28:17.170069Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/tonydzi/second-brain-starter-kit/tree/master/skills/screenpipe-cli"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install tonydzi-second-brain-starter-kit@llmmart"},{"target":"git","command":"git clone https://github.com/tonydzi/second-brain-starter-kit.git"}]}