Peep

peep 👀 — read X/Twitter from the CLI

Knowledge skill — no scripts; the agent drives the peep CLI directly. Requires the peep binary.

peep read https://x.com/user/status/123...   # read a tweet (URL or bare ID both work)
peep thread 1234567890123456789              # full conversation thread
peep search "from:steipete" -n 5             # search
peep bookmarks -n 10                         # your bookmarks
peep whoami                                  # which account am I?

Use peep to READ. It hits X's undocumented GraphQL with cookie auth; X blocks bots fast, so avoid posting. Write commands (tweet/reply/follow/…) are off by default — see Write commands.

Setup / Install

peep is a standalone binary published as a GitHub release from devskale/peep. It needs no Python/Node runtime — just the binary on your PATH. Pick one install method:

Option 1 — GitHub release binary (recommended, macOS + Linux)

Grab the prebuilt binary for your platform from the latest release:

# macOS (arm64/x86_64)
curl -sL https://github.com/devskale/peep/releases/download/latest/peep-darwin -o peep
# Linux x64
# curl -sL https://github.com/devskale/peep/releases/download/latest/peep-linux-x64 -o peep

chmod +x peep
sudo mv peep /usr/local/bin/          # or ~/.local/bin (add to PATH)

Option 2 — install script (auto-detects OS/arch)

curl -sL https://raw.githubusercontent.com/devskale/peep/main/scripts/install.sh | sh

Fetches the latest GitHub release and drops peep into /usr/local/bin (or ~/.local/bin if not writable). If it lands in ~/.local/bin, add that to your PATH:

export PATH="$HOME/.local/bin:$PATH"   # add to ~/.bashrc / ~/.zshrc

Note: the install script currently builds macOS + Linux x64 binaries only. For Linux arm64, use the direct release download or build from source.

Option 3 — build from source (needs bun)

git clone https://github.com/devskale/peep && cd peep
bun install && bun run build:binary   # produces ./peep
sudo mv peep /usr/local/bin/

Verify

peep --version   # → 0.9.0 (…)
peep check       # → which credentials are sourced + from where
peep whoami      # → the X account the cookies belong to (needs auth, below)

Auth isn't part of install. peep reuses your logged-in X browser session — see Authentication. Until you've logged into x.com in a browser, whoami will report missing credentials.

Authentication (read this first)

peep reuses your logged-in X/Twitter browser session — no passwords, no API keys. Credentials resolve in order: --auth-token/--ct0 flags → AUTH_TOKEN/CT0 env vars → browser cookies (Safari/Chrome/Firefox, via --cookie-source).

• peep check — shows which credentials are sourced and from where.
• peep whoami — prints the account the cookies belong to.
• 403 / auth errors → cookies are stale; re-log into x.com in your browser, then retry.
• Chromium variants (Arc/Brave): pass the profile cookie DB via --chrome-profile-dir.

Persistent config at ~/.config/peep/config.json5 (JSON5):

{ cookieSource: ["safari", "chrome"], chromeProfileDir: "/path/to/Chromium/Profile" }

Reading tweets (primary use)

peep read <id-or-url>              # tweet text (bare ID or full URL both accepted)
peep <id-or-url>                   # shorthand for `read`
peep thread <id-or-url>            # the author's self-reply chain
peep replies <id-or-url>           # everyone's replies to a tweet
peep search "<query>" -n 20        # from:user, since:2025-01-01, hashtags, …
peep mentions                      # tweets mentioning you (--user @handle for someone else)
peep user-tweets @handle -n 50     # a user's profile timeline
peep home -n 20                    # "For You" feed (--following for the following feed)
peep bookmarks -n 10               # your bookmarks (--folder-id for a bookmark folder)
peep likes -n 10                   # your likes
peep news --ai-only -n 10          # AI-curated trending news from Explore tabs
peep list-timeline <list-id> -n 20 # tweets from a list
peep following -n 20               # who you follow
peep followers -n 20               # who follows you
peep about @handle                 # account origin / location info

Output modes (global flags)

Prefer --json when summarizing/extracting; --plain for clean readable text.

Pagination — the common gotcha

Most list commands take -n COUNT for a quick page. To page further you must opt in:

peep bookmarks --all --max-pages 3 --json          # paginate, cap at 3 pages
peep search "x" --all --cursor "<cursor>" --json   # continue from a prior page

• --max-pages requires --all (or --cursor); using it alone is an error (exit 2).
• With pagination, --json output becomes { tweets, nextCursor } — keep nextCursor to continue.
• user-tweets auto-paginates when -n > 20.

Starred bookmarks, inbox & cache (local-first)

Every read silently populates ~/.peep/cache.db (SQLite + FTS5):

peep cache --stats                                  # cache stats (tweet/profile/bookmark counts)
peep local-search "typescript" --author @steipete # offline FTS5 search
peep archive import ~/Downloads/twitter.zip       # import an X data export

Triage bookmarks with metadata and run an AI-ranked inbox:

peep starred --unread --priority critical
peep starred note <id> "follow up"                # + tag / priority / folder / revisit / mark-read
peep inbox --score                                # AI-ranked mentions (needs OPENAI_API_KEY)
peep research "codex" --thread-depth 10           # bookmarks → markdown brief (thread + links)

→ Full detail in references/data.md. Read when managing bookmarks, the inbox, or working offline.

Write commands — disabled by default, discouraged

tweet, reply, follow, unfollow, unbookmark are off unless you pass --allow-write (or set allowWrite: true / PEEP_ALLOW_WRITE=1).

Don't automate posting. X blocks bots quickly. Use peep to read; if posting is unavoidable, prefer browser automation (surf / rodney skills) or the paid X API. unbookmark is the one write op that's safe and useful.

Troubleshooting

Exit codes: 0 success · 1 runtime (network/auth) · 2 invalid usage.

References

• references/commands.md — exhaustive command + flag reference (bookmarks expansion flags, news tab filters, list / social-graph options). Read when a command needs a flag not shown above.
• references/data.md — starred bookmarks, AI inbox, local cache, archive import, blocks & mutes, profile bot-scan. Read when triaging bookmarks or working offline.