facebook-cli (fb)

A command-line interface for managing Facebook Pages through the officially supported Meta Graph API.

fb auth login                          # OAuth login via browser
fb pages list                          # List your managed pages
fb posts create 123456 --message "Hello from the terminal!"
fb insights page 123456 --metrics page_impressions --period daily
fb api GET /me                         # Raw Graph API escape hatch

Features

• 33 commands across 11 groups: auth, pages, posts, comments, media, messenger, insights, capabilities, whoami, api, help, version
• JSON-first output — every command supports --json with a stable envelope schema for scripts and AI agents
• OAuth authentication — localhost redirect flow, token stored in OS keyring
• Honest capability detection — fb capabilities shows what your app can actually do (SUPPORTED / CONDITIONAL / RESTRICTED / UNSUPPORTED)
• Raw API escape hatch — fb api GET /path for anything the domain commands don't cover
• Secure by default — no passwords stored, tokens never printed, redaction everywhere

Installation

pip install facebook-cli

Or with pipx (recommended):

pipx install facebook-cli

From source:

git clone https://github.com/IFindMe/Facebook-cli.git
cd Facebook-cli
pip install -e .

Quick Start

1. Create a Meta Developer App

1. Go to developers.facebook.com
2. Click My Apps → Create App
3. Choose Business type
4. Add Facebook Login product
5. Set Valid OAuth Redirect URIs to http://localhost:8080/callback
6. Copy your App ID

2. Configure

mkdir -p ~/.config/facebook-cli
cat > ~/.config/facebook-cli/config.toml << 'EOF'
app_id = "YOUR_APP_ID_HERE"
EOF
chmod 600 ~/.config/facebook-cli/config.toml

Or use an environment variable:

export FB_APP_ID=YOUR_APP_ID_HERE

3. Login

fb auth login

This opens your browser for OAuth authorization. On success, tokens are stored in your OS keyring.

4. Start Managing

fb auth status                    # Check authentication
fb pages list                     # List managed pages
fb posts create PAGE_ID --message "Hello!"
fb insights page PAGE_ID --metrics page_impressions
fb capabilities                   # See what your app can do

Commands

Group	Commands	Description
fb auth	login, status, logout, refresh	OAuth authentication and token lifecycle
fb pages	list, info, feed, tagged	Page listing, info, feed, mentions
fb posts	list, create, edit, delete, reactions	Post CRUD and engagement
fb comments	list, reply, delete	Comment management
fb media	photo upload, video upload, reel publish, albums list, albums create	Media uploads and albums
fb messenger	conversations, messages, send	Page messaging (CONDITIONAL)
fb insights	page, post	Page and post analytics
fb capabilities	—	Discover what your app can access
fb whoami	—	Show authenticated user identity
fb api	GET, POST, DELETE	Raw Graph API escape hatch

Full command reference: COMMANDS.md

Configuration

Config file: ~/.config/facebook-cli/config.toml

app_id = "your_app_id"
default_page_id = "123456789"      # Optional: default page context
api_version = "v26.0"              # Optional: pin API version
scopes = ["pages_show_list"]       # Optional: override default scopes

Environment variables (override config):

Variable	Purpose
FB_APP_ID	Meta app ID
FB_ACCESS_TOKEN	Bypass stored auth (per-invocation)
FB_CLIENT_SECRET	App secret (per-invocation)
FB_API_VERSION	Override API version
FB_CONFIG_DIR	Override config directory

JSON Output

Every command supports --json for machine-readable output:

fb pages list --json

{
  "data": [
    {"id": "123456", "name": "My Page", "tasks": ["CREATE_CONTENT"]}
  ],
  "meta": {
    "schema_version": 1,
    "cli_version": "0.1.0",
    "api_version": "v26.0",
    "domain": "pages",
    "command": "pages list",
    "request_id": "abc123"
  },
  "pagination": {
    "has_next": false
  }
}

Use --quiet for data-only output (no meta/pagination):

fb pages list --json --quiet | jq '.[].name'

Security

• No passwords — OAuth only; the CLI never handles Facebook passwords
• Keyring storage — tokens stored in OS keyring, never in config files
• No token leakage — tokens never printed, logged, or in argv
• Redaction — access tokens redacted in all output paths
• Symlink protection — config directory symlink rejected at startup
• Escape hatch guard — fb api rejects inline access_token params

Non-Goals

The CLI intentionally does not support:

• Groups — API removed April 2024
• Personal profile publishing — not supported by Graph API
• Personal messaging — not supported by Graph API
• Events — restricted to Facebook Marketing Partners
• Marketing/Ads — deferred to v2
• Webhooks — deferred to v2

License

MIT