screenpipe-cli

name	screenpipe-cli
description	Use when an agent needs to operate the screenpipe CLI MCP connector for ScreenApp API tasks, including checking auth, asking questions about ScreenApp recordings, uploading local media, registering webhooks, tagging resources, updating profiles, or discovering generated OpenAPI endpoint tools.

ScreenPipe CLI

Quick Start

Use screenpipe --llms to inspect available commands and screenpipe --mcp to start the MCP stdio server. Use screenpipe mcp add to register the connector with supported local agents.

Treat the CLI as the primary interface. MCP is optional; every documented endpoint should be reachable by ordinary CLI invocation through screenpipe api <operationId> or a curated command that handles payloads the generated OpenAPI mapper cannot express ergonomically.

Required environment for live ScreenApp API calls:

export SCREENAPP_API_TOKEN="..."
export SCREENAPP_TEAM_ID="..."

Optional environment:

export SCREENAPP_DEFAULT_FOLDER_ID="..."
export SCREENAPP_BASE_URL="https://api.screenapp.io"

Alternatively, copy the repo .env.example to .env; the CLI loads repo-local .env values automatically. Never print or commit .env.

Command Workflow

1. Run screenpipe auth status before live API work to confirm credentials are configured without exposing secrets.
2. Prefer curated commands for common tasks:
   • screenpipe files ask <fileId> --prompt "..."
   • screenpipe upload simple <path>
   • screenpipe upload multipart <path>
   • screenpipe upload fallbackPart <path> --fileId <id> --partNumber <n>
   • screenpipe webhook register --name <name> --url <url>
   • screenpipe tag file <fileId> --key <key> --value <value>
   • screenpipe profile update --name <name>
3. Use screenpipe api --help for generated tools covering every endpoint in openapi.yml.
4. Use command help progressively: screenpipe --help, then screenpipe <group> --help, then screenpipe <group> <command> --help.
5. Use --format json for machine-readable command output.

Safety

Do not print or persist SCREENAPP_API_TOKEN. Do not run live upload or profile mutation commands unless the user has asked for the action and provided the target file/resource identifiers.