A command line python utility to manage your social networks (X, Facebook, Instagram, LinkedIn, Discord, YouTube, TikTok, Threads, Telegram, and WhatsApp)

Current version: 2.0.5

Note

Agoras 2.0 uses a modular architecture (five PyPI packages), a platform-first CLI, and an OAuth callback server for supported networks.

Upgrading from Agoras 1.x? Import paths and CLI syntax changed — see the migration guide.

Agoras is a python utility that helps publish and delete posts on the most popular social networks (X (formerly Twitter), Facebook, Instagram, LinkedIn, Discord, YouTube, TikTok, Threads, Telegram, and WhatsApp).

This repository stores the application. There's also GitHub actions that you can incorporate into your workflows.

For more information, please read the full documentation.

Architecture

Agoras is split into five coordinated PyPI packages:

• agoras-common: Shared utilities, logging, and constants
• agoras-media: Image and video processing
• agoras-core: Abstract interfaces (SocialNetwork), Feed, and Sheet logic
• agoras-platforms: Platform implementations (X, Facebook, etc.)
• agoras: Command-line interface (depends on all above)

Key capabilities:

• Platforms: X, Facebook, Instagram, LinkedIn, Discord, YouTube, TikTok, Threads, Telegram, and WhatsApp
• OAuth callback server: Automatic local server for easier authentication on supported networks
• Platform-first CLI: agoras x post instead of agoras publish --network x --action post
• Modular installation: Install only what you need, or use pip install agoras for everything

Upgrading from 1.x? Import paths and CLI commands changed. See the migration guide.

Getting started

Local development

Clone the repository and use Docker-backed make targets for linting and tests:

$ git clone https://github.com/LuisAlejandro/agoras.git
$ cd agoras
$ git checkout develop
$ cp .env.example .env   # optional: platform credentials for integration tests
$ make image
$ make start
$ make console           # interactive shell inside the container
$ make lint
$ make test

For a host virtualenv without Docker, run make virtualenv then activate ./virtualenv/bin/activate. See CONTRIBUTING.rst for monorepo package layout and contributor workflows.

Installation

The agoras program is written in python and hosted on PyPI. Therefore, you can use pip to install the stable version:

$ pip install --upgrade agoras

If you want to install the development version (not recommended), you can install directly from GitHub like this:

$ pip install --upgrade https://github.com/LuisAlejandro/agoras/archive/develop.tar.gz

Modular Installation (v2.0+)

Starting with v2.0, Agoras is split into 5 separate packages for better modularity. The main CLI package automatically installs all dependencies:

$ pip install agoras  # Installs all 5 packages

For selective installation (advanced users only):

$ pip install agoras-common     # Just utilities and logging
$ pip install agoras-media      # Common + media processing
$ pip install agoras-core       # Common + media + core interfaces
$ pip install agoras-platforms  # All above + platform implementations
$ pip install agoras            # Everything including CLI

Package Architecture:

• agoras-common: Utilities, logging, shared constants
• agoras-media: Image and video processing
• agoras-core: Abstract interfaces (SocialNetwork), Feed, Sheet logic
• agoras-platforms: Platform implementations (X, Facebook, etc.)
• agoras: Command-line interface (depends on all above)

When to use each package:

• Most users: pip install agoras (installs everything including CLI)
• Python integrations: pip install agoras-platforms (no CLI, all platforms)
• Custom platforms: pip install agoras-core (interfaces only)
• Media processing: pip install agoras-media (no social features)
• Utilities only: pip install agoras-common (minimal dependencies)

Using the application

Quick Start

Post to X with the platform-first CLI (authorize once, then post with content flags only):

$ agoras x authorize \
    --consumer-key "${TWITTER_CONSUMER_KEY}" \
    --consumer-secret "${TWITTER_CONSUMER_SECRET}"

$ agoras x post \
    --text "Hello from Agoras!" \
    --image-1 "https://example.com/image.jpg"

See all available platforms:

$ agoras --help

See platform-specific commands:

$ agoras x --help
$ agoras facebook --help
$ agoras youtube --help

Supported Platforms

Agoras supports 10 social networks with intuitive platform-first commands:

• X (formerly Twitter): agoras x <action> - Full action set (post, video, like, share, delete)
• Facebook: agoras facebook <action> - Full action set (post, video, like, share, delete)
• Instagram: agoras instagram <action> - Post and video actions
• LinkedIn: agoras linkedin <action> - Full action set (post, video, like, share, delete)
• Discord: agoras discord <action> - Bot-based messaging (post, video, delete)
• YouTube: agoras youtube <action> - Video platform (video, like, delete)
• TikTok: agoras tiktok <action> - Photo slideshow posts and video uploads
• Threads: agoras threads <action> - Post, video, share, and delete
• Telegram: agoras telegram <action> - Post, video, and delete
• WhatsApp: agoras whatsapp <action> - Post, video, and template messages

Automation Commands

Publish from RSS/Atom feeds:

$ agoras utils feed-publish \
    --network x \
    --mode last \
    --feed-url "https://blog.example.com/feed.xml"

Run scheduled posts from Google Sheets:

$ agoras utils schedule-run \
    --network x \
    --sheets-id "${GOOGLE_SHEETS_ID}" \
    --sheets-name "Schedule" \
    --sheets-client-email "${GOOGLE_SHEETS_CLIENT_EMAIL}" \
    --sheets-private-key "${GOOGLE_SHEETS_PRIVATE_KEY}"

Examples of usage

• Using Agoras with X
• Using Agoras with Facebook
• Using Agoras with Instagram
• Using Agoras with LinkedIn
• Using Agoras with Discord
• Using Agoras with YouTube
• Using Agoras with TikTok
• Using Agoras with Threads
• Using Agoras with Telegram
• Using Agoras with WhatsApp
• Migration Guide (upgrading from 1.x)

Credentials

• How to get credentials for X
• How to get credentials for Facebook
• How to get credentials for Instagram
• How to get credentials for LinkedIn
• How to get credentials for Discord
• How to get credentials for YouTube
• How to get credentials for TikTok
• How to get credentials for Threads
• How to get credentials for Telegram
• How to get credentials for WhatsApp
• How to get credentials for Google spreadsheets

Getting help

If you have any doubts or problems, subscribe to our Discord server and ask for help. You can also ask your question on StackOverflow (tag it agoras) or drop me an email at luis@luisalejandro.org.

Contributing

See CONTRIBUTING for details.

Release history

See HISTORY for details.

License

Copyright (C) 2022-2026, Agoras Developers (read AUTHORS for a full list of copyright holders).

Released under a GPL-3 License.

Made with 💖 and 🍔

Web luisalejandro.org · GitHub @LuisAlejandro · Twitter @LuisAlejandro