fb

Facebook as structured data, from one pure-Go binary.

There is no app id, no developer app and no API token anywhere in this tool.
fb reads the data the site already ships to a signed-out browser.

fb page nasa --fields id,handle,name,likes,followers,category

╭─────────────────┬────────┬──────────────────────────────────────────────────────┬────────────┬────────────┬─────────────────────────╮
│ ID              │ HANDLE │ NAME                                                 │ LIKES      │ FOLLOWERS  │ CATEGORY                │
├─────────────────┼────────┼──────────────────────────────────────────────────────┼────────────┼────────────┼─────────────────────────┤
│ 100044561550831 │ NASA   │ NASA - National Aeronautics and Space Administration │ 28,660,738 │ 28,000,000 │ Government organisation │
╰─────────────────┴────────┴──────────────────────────────────────────────────────┴────────────┴────────────┴─────────────────────────╯

Full documentation: facebook-cli.tamnd.com.

Why

There are three ways to get data out of Facebook.

The Graph API wants an app, a review and a token, and then does not have most of this.
A headless browser works and costs you a browser per read.

fb takes the third route.
Signed-out facebook.com renders through Relay, and the page ships the query results inline as <script type="application/json" data-sjs> blocks: the same objects the site's own JavaScript renders from.
fb extracts them, stitches them and parses them into typed records.

One static binary, nothing to sign up for.

Install

go install github.com/tamnd/facebook-cli/cmd/fb@latest
brew install --cask tamnd/tap/fb

Prebuilt archives for Linux, macOS, Windows and FreeBSD, plus deb, rpm and apk packages, SBOMs and signed checksums, are on the releases page.

docker run --rm -v ~/data/fb:/data ghcr.io/tamnd/fb page nasa

From source:

git clone https://github.com/tamnd/facebook-cli
cd facebook-cli
make build      # produces ./bin/fb

Quick start

fb id nasa                                  # what is this string? no request made
fb page nasa                                # a Page or profile, whole
fb post 'https://www.facebook.com/NASA/posts/1587860636042640/'
fb comments "$URL" -n 20                    # from the same read
fb reactions "$URL"                         # all seven types, signed out
fb photos nasa -n 20 --fields id,size,alt
fb video 1380134307388381 --transcript
fb edges nasa                               # what that read claims about everything else
fb crawl nasa --depth 2 --budget 50 --store ./nasa.db
fb query "select kind, count(*) from nodes group by kind" --store ./nasa.db
fb export --store ./nasa.db --format turtle

Eight surfaces, two tiers

fb surfaces      # the eight places fb reads, and what each answers
fb tiers         # the two tiers, and what each needs
fb routes        # which surface and operation answers which command

Tier 0 needs nothing at all, and nearly everything lives there: pages, profiles, posts, comments, all seven reaction types, photos with their alt text, videos with captions and transcripts, events with RSVP counts, and a public group's shell.

Tier 1 is two cookies from a browser you are already signed into, and it buys exactly three things: the timeline past the first post, group discussions, and search.

fb auth import --c-user <id> --xs <token>

Every record says what it did not see

{"tier":0,"surfaces":["s1","s3"],
 "sources":["https://www.facebook.com/profile.php?id=100044561550831"],
 "via":{"followers":"s1","likes":"s3","talking_about":"s3"},
 "missed":["comments past the first 20"],
 "fetched_at":"2026-07-29T18:02:57Z"}

via is there because likes and followers are different numbers from different surfaces, and pretending they are one field is a bug.
missed is there because a post with 532 comments read from a permalink that ships twenty should not look like a post with twenty comments.

Claims, not just records

A record is what one page said about itself.
A claim is what it said about something else, and that is the part that composes.

fb edges nasa --fields predicate,to,note

╭──────────────┬────────────────────────────────────────────────────────────────────────────────┬──────────────────────────────────────────────────────╮
│ PREDICATE    │ TO                                                                             │ NOTE                                                 │
├──────────────┼────────────────────────────────────────────────────────────────────────────────┼──────────────────────────────────────────────────────┤
│ delegates_to │ fb://page/54971236771                                                          │ NASA - National Aeronautics and Space Administration │
│ covers       │ fb://photo/1496429661852405                                                    │                                                      │
│ covers       │ fb://photo/416661036495945                                                     │                                                      │
│ links_to     │ fb://external/5bc0ad51cb2d1c745e141f87a537df877be241e909da9e7059bd133937fc133a │ https://www.nasa.gov/nasa-app/                       │
│ links_to     │ fb://external/639a6da94698ad1a2274a8d490f69c4a97615e451e0f70ebbf0d35b4c43c7a5f │ https://www.nasa.gov/                                │
│ authored     │ fb://post/1589486402546730                                                     │ NASA - National Aeronautics and Space Administration │
│ attaches     │ fb://video/1629850552078859                                                    │                                                      │
╰──────────────┴────────────────────────────────────────────────────────────────────────────────┴──────────────────────────────────────────────────────╯

Nineteen predicates, stable fb://kind/id URIs, and every claim carrying the URL, the surface and the tier that asserted it.
fb graph walks them, fb crawl keeps them in SQLite, and fb rdf and fb export write them as schema.org with RDF-star provenance.

Commands

fb <command> --help is generated from the operation definitions, so it cannot drift from the code.

Read-only, and checked

fb never posts, likes, comments, follows or joins anything.

Every request is a GET, except one form post to the GraphQL endpoint that replays a query the page itself shipped.
That is enforced rather than asserted: a test parses the package as source and fails the build if a second non-GET appears anywhere, if that replay's URL stops being the GraphQL endpoint, if any string in the package ends in Mutation, or if any registered operation is anything but a read.

Another test asserts the archive format redacts the cookie header, because captures get pasted into issues.

Configuration

Everything lives in one directory: the page cache, the session file, and the default store.

fb config show
fb config path

FB_DATA_DIR moves it, and it is the only environment variable fb reads.
One directory rather than three because splitting cache from data means a Docker user mounts one volume and silently loses the other.

Exit codes

Exit 4 is the one to handle.
It covers a genuinely private thing and a refusal that lifts on its own, and the message says which.
The throttle is per URL rather than per address, so when /nasa walls, /nasa/photos usually still answers.

Development

make test    # go test ./...
make vet     # go vet ./...
make build   # ./bin/fb
make smoke   # run every command and assert it works or walls cleanly

cli/ is the command tree.
fb/ is the library under it: the client, the cache, the Relay extraction, the parsers and the store.
pkg/fbid/ classifies ids and URLs with no other dependency and is importable on its own.
pkg/graph/ and pkg/rdf/ are the claim model and its vocabulary.

The parser tests read fb archive captures of real pages, so they exercise the bytes Facebook actually served rather than a hand-written approximation.

License

Apache-2.0. See LICENSE.