Documentation Index
Fetch the complete documentation index at: https://docs.monolex.ai/llms.txt
Use this file to discover all available pages before exploring further.
Usage
Quick Start
# 1. Create a profile and log in
monosurf start --profile work # Chrome window opens
# → Log in to X.com in that window
# → Session is saved. Close when done.
# 2. Grant access and use
monosurf auth grant read 1h
monosurf x.com trending --profile work
monosurf news.ycombinator.com top --profile work
Setup
Requirements
- Chrome browser installed (or Playwright/Puppeteer Chromium)
- macOS, Windows, or Linux
Profiles
Each profile is an isolated Chrome instance with its own login sessions.
monosurf start --profile work # Start visible Chrome (for login)
monosurf start --profile personal # Another Chrome, different account
monosurf start --profile work --headless # No window (automation)
monosurf stop --profile work # Stop Chrome
monosurf profiles # List all profiles + status
--profile is not specified, MonoSurf asks which one to use.
Browsers
MonoSurf auto-detects available browsers:
monosurf browsers
1. Google Chrome 146.0 (system)
2. Playwright chromium 145.0 (playwright)
3. Puppeteer Chrome 146.0 (puppeteer)
monosurf start --profile work --browser 2 # Use Playwright Chromium
npx playwright install chromium # Playwright Chromium (~200MB)
npx puppeteer browsers install chrome # Puppeteer Chrome (~200MB)
Login to Sites
monosurf login x.com # Opens Chrome, you log in, account detected
monosurf login reddit.com
monosurf login threads.net
monosurf x.com search "rust programming" --limit 10
monosurf x.com timeline @AnthropicAI --limit 5
monosurf x.com read https://x.com/user/status/123456
monosurf x.com trending
monosurf x.com post "Hello world" # requires write grant
monosurf x.com post 'First line
second line
third line' # multiline post
monosurf x.com reply https://x.com/... "Great thread!"
Hacker News — news.ycombinator.com
monosurf news.ycombinator.com top --limit 10
monosurf news.ycombinator.com new --limit 10
monosurf news.ycombinator.com ask --limit 5
monosurf news.ycombinator.com show --limit 5
monosurf news.ycombinator.com search "browser automation"
monosurf news.ycombinator.com read 12345678
GitHub — github.com
monosurf github.com trending --limit 10
monosurf github.com trending-weekly --limit 10
monosurf github.com search "terminal emulator"
Reddit — reddit.com
monosurf reddit.com hot rust --limit 10
monosurf reddit.com hot programming --limit 5
monosurf reddit.com new webdev --limit 10
monosurf reddit.com search "AI terminal"
monosurf reddit.com front --limit 10
Threads — threads.net
monosurf threads.net feed --limit 10
monosurf threads.net search "AI programming"
monosurf threads.net profile @monolexai --limit 5
monosurf threads.net read https://threads.net/@user/post/123
monosurf threads.net post "Hello from monosurf" # requires write grant
monosurf threads.net reply https://threads.net/@user/post/123 "Great post!"
Product Hunt — producthunt.com
monosurf producthunt.com today --limit 10
Batch Posting
Post multiple messages from a file on a schedule:
# posts.txt — one post per block, separated by ---
monosurf x.com batch posts.txt # 1h interval, ±15m jitter
monosurf x.com batch posts.txt --interval 2h # custom interval
monosurf x.com batch posts.txt --jitter 20m # custom jitter range
monosurf reddit.com batch posts.txt # works with any site plugin
# Monitor and control
monosurf batch status # check progress
monosurf batch stop # graceful stop
# Run in background
nohup monosurf x.com batch posts.txt &
First post goes here.
---
Second post with
multiple lines.
---
Third post.
Browse Mode (No Login)
Crawl any public page without a profile or login:
monosurf browse https://example.com # Print page text
monosurf browse https://example.com --eval "document.title" # Evaluate JS
monosurf browse https://example.com --visible # Show browser window
Default (Human-readable)
Elon Musk @elonmusk · 2026-04-03T03:08:43.000Z
Tesla
replies:649 reposts:269 likes:2890
---
Anthropic @AnthropicAI · 2026-04-02T16:59:42.000Z
New research: Emotion concepts in LLMs...
replies:691 reposts:2504 likes:11474
[2 items]
JSON (Machine-readable)
monosurf x.com search "rust" --json
Options
| Flag | Description |
|---|
--profile <name> | Select profile (asked if multiple exist) |
--browser <id> | Select browser engine (from monosurf browsers) |
--headless | No window (background automation) |
--limit <n> | Maximum items to return (default: 20) |
--json | Output as JSON array |
--visible | Show browser window (browse mode) |
--interval <dur> | Time between batch posts (default: 1h) |
--jitter <dur> | Random offset ± applied to interval (default: 15m) |
Auth Management
monosurf auth grant read 1h # Read access for 1 hour
monosurf auth grant write 30m # Write access for 30 minutes
monosurf auth revoke # Lock everything immediately
monosurf auth status # Show active grants
Site Management
monosurf sites # List installed plugins
monosurf sites index # Re-index after adding plugins
monosurf sites search "tech" # Search plugins by tag
monosurf sites sign # Seal all plugins (checksum)
monosurf sites verify # Check for tampering
monosurf sites pull x.com # Download official plugin
monosurf sites push x.com # Upload to registry
monosurf sites reset x.com # Restore from official backup
Adding a New Site
- Create
~/Library/Application Support/Monolex/monosurf/sites/{domain}.json
- Define commands with URL, wait selector, extraction JS
- Run
monosurf sites sign to seal
- Test:
monosurf {domain} {command} --profile work
No code changes. No rebuilding. Instant.
