kicau

A CLI for X (Twitter) that talks to the private GraphQL API using your existing session cookies. No developer app, no OAuth dance. Every tweet it fetches is archived to a local SQLite database and is searchable offline.

dancing with the cat by typing kicau mania in your terminal

Install

curl -fsSL https://raw.githubusercontent.com/gitshrl/kicau/main/scripts/install.sh | sh

Linux x86_64 and macOS on Apple silicon. No Rust, no build, no dependencies.

Authentication

Run kicau login once. It reads your X session straight from a browser you are signed into (Chrome, Edge, Firefox, or Safari), verifies it, and writes ~/.kicau/config.toml — no copy-paste. With no browser session it falls back to prompting for the two cookies by hand. Re-run it any time to refresh an expired session. kicau config shows where everything lives.

# ~/.kicau/config.toml
[credentials]
auth_token = "..."
ct0 = "..."

kicau resolves auth_token and ct0 in this order:

1. --auth-token / --ct0 flags
2. KICAU_AUTH_TOKEN / KICAU_CT0 environment variables
3. ~/.kicau/config.toml [credentials]

Check what resolved with kicau check.

Usage

# setup
kicau login # read your X session from the browser (or paste cookies)
kicau whoami # confirm which account the cookies belong to

# read from X
kicau read 2074208949205881033 # one post, by id or full URL
kicau search "rust async"
kicau user ClaudeDevs # someone's recent posts
kicau home -n 30 # your home timeline
kicau tweets # your own posts; kicau tweets ClaudeDevs for someone else's
kicau bookmarks # sync new bookmarks from X to SQLite, show the newest
kicau bookmarks -n 50 # show 50 (still syncs all new)
kicau bookmarks --all # re-fetch every bookmark, not just new ones

# write to X (every write takes --dry-run)
kicau tweet "hello from kicau"
kicau tweet "with a picture" --media photo.png --alt "a description"
kicau reply <id-or-url> "nice thread"
kicau like <id> ; kicau retweet <id> ; kicau bookmark <id>

# offline, over your local archive
kicau find "loops"

# just for fun
kicau mania # a cat dancing in ASCII

Commands

Read read · search · mentions · replies · thread · user · tweets · home · bookmarks · list · dms · dm

Write tweet · reply · delete · like/unlike · retweet/unretweet · bookmark/unbookmark · follow/unfollow · blocks · mutes · upload

Local data find (FTS over archived tweets) · log (recent archived) · graph (follow-graph snapshot) · profiles (profile snapshot) · db stats · backup export|import · import (X data export)

Setup / maintenance init (create config, prompt for cookies) · config (show paths and credential source) · whoami · check · mcp (serve the archive to agents)

Fun mania

Run kicau <command> --help for options. Every write supports --dry-run.

Global flags

Flag	Effect
--json	machine-readable JSON output
--plain	no color/emoji, stable text
--no-db	skip archiving to SQLite
--auth-token / --ct0	override cookies
--timeout <ms>	request timeout (default 30000)

Local storage

• ~/.kicau/kicau.sqlite holds the tweet archive (tweets, profiles, collections, follow edges, profile snapshots, DMs), with FTS5 full-text search.
• Reads archive by default; find and log query it with no network.
• kicau backup export <dir> writes each table as git-friendly JSONL; backup import <dir> restores.

Use from an agent (MCP)

kicau mcp serves the archive over the Model Context Protocol on stdio, so an agent can query what you have saved. Register it once:

claude mcp add kicau -- kicau mcp

It exposes five tools:

• search_archive: full-text search over your archive
• list_bookmarks: archived bookmarks
• recent_tweets: the most recently archived posts
• archive_stats: counts and size
• read_tweet: fetch one post live by id or URL (Article body included), and archive it

The first four read the local archive and touch no network. read_tweet is the only tool that calls X, using your cookies; without them it says to run kicau login rather than failing. The surface reads and fetches only: it never posts, likes, follows, or deletes, so an agent can read your feed but cannot act as you.

install.sh also drops a kicau skill into any agent framework you already have (~/.claude, ~/.agents, ~/.openclaw, ~/.hermes), so the assistant knows kicau's commands and MCP tools. Frameworks you do not have are skipped.