win4r/museai-skills/facebook-cli

Facebook CLI

Pasted links first

If the user pasted a Facebook Marketplace item link or a share link, never open it with the browser: the browser cannot pass the Facebook login wall. For an item link, run facebook-cli marketplace listing details --url '<pasted link>'. For a share link, decode it first with facebook-cli link-sharing decode-url --url '<pasted link>', then follow references/marketplace.md Step 0 for the decoded URL.

Quick Reference

facebook-cli
├── post
│   ├── read (--post-id <id> | --url <url>) # Read by numeric ID/PFBID or canonical post/photo/video URL
│   ├── comments
│   │   └── read --post-id <id> [--limit N] [--after <cursor>]  # Read comments (paginated: data[] + paging.cursors.after; post link at summary.post_url)
│   └── reactions
│       └── read --post-id <id>  # Reaction summary only: summary.total_count + summary.reaction_counts (no individual reactor list)
├── link-sharing
│   └── decode-url --url <url>              # Resolve a share link; returns original_url
├── me                                         # Your Facebook name + profile ID
│   └── friends [--name] [--city] [--hometown] [--work] [--education] [--filter-mode AND|OR] [--json-query <json>] [--birthday-within-days [N]] [--limit N] [--after <cursor>]  # Paginated: data[] + paging.cursors.after
├── marketplace
│   ├── search --query "..." [--out <file>] [options]  # Search listings; pass the --out file to shopping.resolve_results, do not read it
│   ├── my-listings [--status active|pending|sold|draft] [--limit N] [--after <cursor>]  # Your own listings (active + inactive), paginated
│   ├── listing details (--listing-id <id> | --url '<item link>') [--out <file>]  # Item details
│   ├── listing create --title "..." --price N --photo /path [options]  # Create; goes LIVE only with photos+condition+category+location (location = --latitude & --longitude; no --location flag), else DRAFT
│   ├── listing edit --listing-id <id> --photo /path [options]  # Edit a listing (photos uploaded automatically)
│   ├── listing delete --listing-id <id>       # WRITE — permanently delete your listing; prompts for approval
│   ├── listing publish --listing-id <id>      # WRITE — take a DRAFT live; needs photos+condition+category+location (location = --latitude & --longitude); prompts for approval
│   └── seller-info --listing-id <id>          # Seller ratings/info
├── groups
│   ├── details --group-id <id-or-vanity> # Fetch name, About, visibility, history, tags, ordered rules, and member count
│   ├── search [--keywords "..."]         # Search/list your groups; --role any = all public groups
│   └── posts --group-id <id>             # Browse posts in a group; --query filters by text
├── events
│   ├── search [--scope connected|discover] [--keywords "..."] [--location "..."] [--latitude N --longitude=-N] [--radius-in-miles N] [--category ...] [--start-date ...] [--end-date ...] [--limit N] [--after <cursor>]  # Paginated: data[] + paging.cursors.after; coordinates beat --location, which is only city-accurate
│   └── details --event-id <id>           # Read one event; ID from search `id` or `permalink_url`
├── saved
│   ├── list [--type post|video|link|product|reel|event|page] [--collection-id <id>] [--limit N] [--after <opaque>]
│   ├── add --savable-id <FBID> [--type ...] [--collection-id <id>]      # WRITE — auto-allowed
│   ├── remove --savable-id <FBID> [--type ...] [--collection-id <id>]   # WRITE — auto-allowed
│   └── collections
│       ├── list
│       └── create --name "..."                  # WRITE — auto-allowed
├── story
│   └── feed [--limit <n>]               # Fetch your story feed (story tray)
├── feed
│   ├── newsfeed [--limit <n>] [--after <cursor>] # Ranked algorithmic newsfeed (organic stories)
│   └── friends [--limit <n>] [--after <cursor>]  # Ranked friends-only feed
├── timeline
│   └── fetch --profile-id <id> [--limit N] [--after <cursor>]  # Fetch timeline posts; use next_cursor to page (check author_id vs owner_id)
└── profile
    └── info --profile-id <id>                 # Look up profile info

Account Linking

Before running any facebook-cli command, verify the user's Facebook account is connected by running facebook-cli me, except for facebook-cli marketplace search, facebook-cli marketplace listing details, and facebook-cli marketplace seller-info. If the command returns account info (name and profile ID), the account is connected — proceed normally. Cache this result for the rest of the conversation; do not re-run the check before every command. If any subsequent command fails with an auth or account error, re-run facebook-cli me to recheck account linking status.

If the command fails or returns an error indicating no account is linked, the account is not connected. Get the connect URL by running facebook-cli connect-url (it outputs JSON with a connect_url field), then tell the user, substituting that URL:

Your Facebook account is not connected. To connect it, visit Meta Accounts Center and link your Facebook account.

If the user asks to disconnect their Facebook account, run facebook-cli disconnect-url (it outputs JSON with a disconnect_url field) and direct them to that URL:

To disconnect your Facebook account, visit Meta Accounts Center and remove the linked account.

Always read these URLs from the command output rather than hardcoding them.

Post IDs and URLs

When using post read, post comments read, or post reactions read, these formats are accepted for --post-id:

• 123456789012345 — raw numeric post ID
• pfbid02... — PFBID format

Canonical post, photo, video, and reel URLs go directly to post read --url. For share links, call link-sharing decode-url --url <url> first, then pass the nonblank canonical original_url intact to the reader. Supply exactly one of --url or --post-id. Stop on a null, missing, or blank decoded URL or a failed read; do not guess IDs or retry a media ID as a post ID. See posts.md for supported URL patterns and other entities.

Composability

When the user asks "what can I do on Facebook?" or at the start of a session, generate 3-5 contextual suggestions that combine multiple commands into useful read-only workflows.

How outputs chain across commands

Most chains are mechanical: an ID in one command's output is the --id flag of the next. me and me friends produce profile_id for profile info and timeline fetch. Timelines, feeds, and searches produce post_id for post read, post comments read, and post reactions read. marketplace search produces listing_id for listing details and seller-info. groups search produces group_id for groups details and groups posts. events search produces id (also embedded in permalink_url) for events details. story feed returns story buckets with story URLs and owner info.

The chains that are not mechanical:

• My listings -> manage: marketplace my-listings produces your own listing_id -> marketplace listing edit (update), marketplace listing delete (remove), or marketplace listing publish (take a draft live). Use --status to scope to active/pending/sold/draft and --after to page.
• Create draft -> complete -> publish: marketplace listing create missing any of photos/condition/category/location saves a draft -> marketplace listing edit to add the missing field(s) -> marketplace listing publish to take it live. If publish fails with missing fields, the error names exactly which to add via edit, then retry.
• Groups posts + friends cross-reference: When the user asks about friends' activity in a group, call me friends to get the friend list, then compare against post authors from groups posts — do not ask the user to provide their friend list manually.
• Saved -> content: saved list produces savable_id plus type. Chain by category:
• post -> post read, post comments read, post reactions read
• page -> profile info --profile-id <savable_id>
• product -> marketplace listing details --listing-id <savable_id>
• event -> events details --event-id <savable_id>
• Saved -> unsave: saved list produces savable_id (the content ID) -> saved remove --savable-id <savable_id> [--type <type>]
• Collections -> create flow: saved collections create produces collection_id for future use

Suggestion guidelines

1. Phrase as user-centric actions — "See which of your Marketplace listings still have no photos", not "Run marketplace my-listings then listing edit".
2. Vary suggestions across sessions — rotate across skill categories.
3. Adapt to context:

• Profile-aware: If the user's profile mentions hobbies or interests, suggest related workflows (e.g., cyclist -> "Catch up on what your cycling friends have posted").
• Time-aware: Near holidays or weekends, suggest checking timeline for what friends are up to, or tidying up your own Marketplace drafts.
• Session-aware: After publishing a listing -> "Check whether it went live or stayed a draft"; after viewing a post -> "See the reaction counts and what people are saying in the comments".

1. Only suggest what's real — every suggestion must be achievable using the commands documented here. Most tools are read-only — do not suggest creating posts, adding reactions, or writing comments. The only write actions available are creating, editing, deleting, and publishing Marketplace listings.
2. Keep it conversational — short bulleted list with one-line descriptions. Offer to walk through any of them.

References

One file per feature area, each named for the area it covers: references/friends.md, references/posts.md, references/comments.md, references/reactions.md, references/marketplace.md, references/timeline.md, references/profile.md, references/story.md, references/feed.md, references/groups.md, references/events.md, references/saved.md.

Operating Rules