screenpipe Screenpipe CLI
Use bun x screenpipe@latest to run CLI commands. No separate install needed.
IMPORTANT: Always run bun x commands from a clean temp directory to avoid node_modules conflicts:
cd "$(mktemp -d)" && bun x screenpipe@latest <command>
Shell
- All platforms →
bash(on Windows, the bundled git-portable bash is used automatically)
Pipe Management
Pipes are markdown-based AI automations that run on schedule. Each pipe lives at ~/.screenpipe/pipes/<name>/pipe.md.
Commands
bun x screenpipe@latest pipe list # List all pipes (compact table)
bun x screenpipe@latest pipe enable <name> # Enable a pipe
bun x screenpipe@latest pipe disable <name> # Disable a pipe
bun x screenpipe@latest pipe run <name> # Run once immediately (for testing)
bun x screenpipe@latest pipe logs <name> # View execution logs
bun x screenpipe@latest pipe install <url-or-path> # Install from GitHub or local path
bun x screenpipe@latest pipe delete <name> # Delete a pipe
bun x screenpipe@latest pipe models list # View AI model presets
Creating a Pipe
Create ~/.screenpipe/pipes/<name>/pipe.md with YAML frontmatter + prompt:
---
schedule: every 30m
enabled: true
preset: ["Primary", "Fallback"]
---
Your prompt instructions here. The AI agent executes this on schedule.
## What to do
1. Query screenpipe search API for recent activity
2. Process results
3. Output summary / send notification
Schedule syntax: every 30m, every 1h, every day at 9am, every monday at 9am, or cron: */30 * * * *, 0 9 * * *
Config fields: schedule, enabled (bool), preset (string or array — e.g. "Oai" or ["Primary", "Fallback"]), history (bool — include previous output as context)
Screenpipe prepends a context header with time range, timezone, OS, and API URL before each execution. No template variables needed.
After creating:
bun x screenpipe@latest pipe install ~/.screenpipe/pipes/my-pipe
bun x screenpipe@latest pipe enable my-pipe
bun x screenpipe@latest pipe run my-pipe # terminal-only; in-app chat uses the workflow below
Testing from in-app chat
The cloud JWT is intentionally absent from Bash. Do not expose or recover it, and do not use standalone pipe run. Test through the authenticated desktop runtime:
api="${SCREENPIPE_LOCAL_API_URL:-http://localhost:3030}"
auth="Authorization: Bearer $SCREENPIPE_LOCAL_API_KEY"
curl -sS -X POST -H "$auth" "$api/pipes/my-pipe/run"
curl -sS -H "$auth" "$api/pipes/my-pipe/logs"
{"success":true} means the run started, not that it passed. Poll for a new terminal log. Bind only after success: true; otherwise report its stderr and leave the Live View unchanged.
Editing Config
Edit frontmatter in ~/.screenpipe/pipes/<name>/pipe.md directly, or use the API:
curl -X POST http://localhost:3030/pipes/<name>/config \
-H "Content-Type: application/json" \
-d '{"config": {"schedule": "every 1h", "enabled": true}}'
Rules
- Use
pipe list(not--json) — table output is compact - Never dump full pipe JSON — can be 15MB+
- Check logs first when debugging:
pipe logs <name> - Outside in-app chat, use
pipe run <name>before waiting for a schedule; in-app chat uses the authenticated runtime above
Connection Management
Manage integrations (Telegram, Slack, Discord, Email, Todoist, Teams) from the CLI.
Commands
bun x screenpipe@latest connection list # List all connections + status
bun x screenpipe@latest connection list --json # JSON output
bun x screenpipe@latest connection get <id> # Show status + non-secret settings
bun x screenpipe@latest connection get <id> --json # JSON output
bun x screenpipe@latest connection set <id> key=val # Save credentials
bun x screenpipe@latest connection test <id> # Test a connection
bun x screenpipe@latest connection remove <id> # Remove credentials
Examples
# Set up Telegram
bun x screenpipe@latest connection set telegram bot_token=123456:ABC-DEF chat_id=5776185278
# Set up Slack webhook
bun x screenpipe@latest connection set slack webhook_url=https://hooks.slack.com/services/...
# Verify it works
bun x screenpipe@latest connection test telegram
# Check what's connected
bun x screenpipe@latest connection list
Connection IDs: telegram, slack, discord, email, todoist, teams, google-calendar, openclaw
Credentials are stored locally and are not printed by connection get.
Per-integration details: don't guess API shapes from this skill. Run connection list for self-describing local endpoints. connection get <id> returns only status and non-secret settings.
Publishing pipes to the store
screenpipe pipe publish <pipe-name>
Reads ~/.screenpipe/pipes/<pipe-name>/pipe.md, extracts title/description/icon/category from YAML frontmatter, and publishes to the screenpipe pipe store. Requires auth (SCREENPIPE_API_KEY env var or ~/.screenpipe/auth.json).