Skip to main content

​
install & run

bunx screenpipe record

​
recording options

​
core

flagdescriptiondefault
-f, --fps <FLOAT>frames per second for recording1.0 (macOS: 0.5)
-p, --port <INT>API server port3030
--data-dir <PATH>data directory~/.screenpipe
--debugenable debug loggingfalse

​
audio

flagdescriptiondefault
-d, --audio-chunk-duration <INT>chunk duration (seconds)30
--disable-audiodisable audio recordingfalse
-i, --audio-device <STRING>audio device (repeatable)—
-a, --audio-transcription-engine <ENGINE>STT enginewhisper-large-v3-turbo
--vad-engine <ENGINE>voice activity detection (silero/webrtc)silero
--vad-sensitivity <LEVEL>VAD sensitivity (low/medium/high)high
transcription engines: deepgram, whisper-tiny, whisper-large, whisper-large-v3-turbo

​
vision

flagdescriptiondefault
--disable-visiondisable screen recordingfalse
-m, --monitor-id <INT>monitor to record (repeatable)all
-o, --ocr-engine <ENGINE>OCR engineplatform native
--ignored-windows <STRING>ignore windows by title (repeatable)—
--included-windows <STRING>only capture these windows (repeatable)—
--video-chunk-duration <INT>video chunk duration (seconds)60
OCR engines: apple-native, windows-native, tesseract, unstructured, custom

​
privacy

flagdescriptiondefault
-l, --language <LANG>languages to support (repeatable)—
--use-pii-removalredact PII from OCR textfalse

​
experimental

flagdescriptiondefault
--enable-ui-monitoringcapture UI events via accessibility (macOS)false
--enable-frame-cachevideo frame cachefalse
--capture-unfocused-windowscapture unfocused windowsfalse

​
subcommands

​
pipe management

pipes are scheduled AI agents that run on your screen data. see pipes docs for details. 
# list all pipes
bunx screenpipe pipe list

# install a pipe
bunx screenpipe pipe install /path/to/pipe
bunx screenpipe pipe install https://example.com/pipe.md

# enable/disable
bunx screenpipe pipe enable my-pipe
bunx screenpipe pipe disable my-pipe

# run once manually
bunx screenpipe pipe run my-pipe

# view logs
bunx screenpipe pipe logs my-pipe
bunx screenpipe pipe logs my-pipe -f  # follow

# delete
bunx screenpipe pipe delete my-pipe

​
add external data

add screen recordings from external sources (iPhone recordings, journal photos, etc.): 
bunx screenpipe add /path/to/videos --ocr-engine apple-native
optional: override metadata with a JSON file: 
bunx screenpipe add /path/to/videos --metadata-override metadata.json

​
status

bunx screenpipe status
bunx screenpipe status --json

​
audio devices

bunx screenpipe audio list
bunx screenpipe audio start <device-id>
bunx screenpipe audio stop <device-id>

​
vision devices

bunx screenpipe vision list

​
database

bunx screenpipe migrate

​
API endpoints

screenpipe serves a REST API on localhost:3030:
methodendpointdescription
GET/searchsearch screen & audio content
GET/healthserver health check
GET/audio/listlist audio devices
GET/vision/listlist monitors
GET/frames/{id}get frame data
GET/frames/{id}/ocrget frame OCR text
POST/tags/{type}/{id}add tags
DELETE/tags/{type}/{id}remove tags
POST/raw_sqlexecute raw SQL
POST/addadd content to database
GET/semantic-searchsemantic search
GET/search/keywordkeyword search

​
search example

curl "http://localhost:3030/search?q=meeting&limit=10&content_type=ocr"

​
search parameters

paramtypedescription
qstringsearch query
limitintmax results
offsetintpagination offset
content_typestringocr, audio, ui, all
start_timeISO 8601filter start
end_timeISO 8601filter end
app_namestringfilter by app
window_namestringfilter by window title
browser_urlstringfilter by browser URL
min_lengthintminimum text length
max_lengthintmaximum text length

​
shell completions

# bash
eval "$(screenpipe completions bash)"

# zsh
eval "$(screenpipe completions zsh)"

# fish
screenpipe completions fish | source

# powershell
screenpipe completions powershell | Out-String | Invoke-Expression
need help? join our discord.