Agent Skills: Screenpipe CLI

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

1. Use pipe list (not --json) — table output is compact
2. Never dump full pipe JSON — can be 15MB+
3. Check logs first when debugging: pipe logs <name>
4. 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).