Skip to main content

​
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
First time: Chrome window opens, you log in to sites manually. Sessions persist across restarts — you only log in once. When multiple profiles exist and --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
System Chrome works but sites may detect automation (bot blocks, captchas). Playwright/Puppeteer Chromium has stealth built in — recommended for headless. No browser installed? Install one: 
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
After login, MonoSurf detects your account name and saves it to the profile.

​
Commands by Platform

​
X (Twitter) — x.com

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 &
Posts file format: 
First post goes here.
---
Second post with
multiple lines.
---
Third post.
First post goes immediately. Subsequent posts are spaced by the interval with random jitter applied.

​
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
Browse launches a temporary headless Chromium that is destroyed when done.

​
Output Formats

​
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

FlagDescription
--profile <name>Select profile (asked if multiple exist)
--browser <id>Select browser engine (from monosurf browsers)
--headlessNo window (background automation)
--limit <n>Maximum items to return (default: 20)
--jsonOutput as JSON array
--visibleShow 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

  1. Create ~/Library/Application Support/Monolex/monosurf/sites/{domain}.json
  2. Define commands with URL, wait selector, extraction JS
  3. Run monosurf sites sign to seal
  4. Test: monosurf {domain} {command} --profile work
No code changes. No rebuilding. Instant.