Migration Guide: Legacy to New CLI¶

Note

v2.0 Package Split: This guide covers CLI migration (v2.0+). For v2.0 package split and import path changes, see the sections below on “Package Installation” and “Import Path Changes”.

Overview¶

Agoras 2.0+ introduces a new CLI structure that’s more intuitive, discoverable, and aligned with how users think about social media operations. This guide helps you migrate from the legacy agoras publish command to the new platform-first command structure.

Package Installation (v2.0+)¶

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

Full Installation (Recommended for Most Users):

$ pip install agoras  # Installs all 5 packages including CLI

This installs: - agoras-common: Utilities, logging, shared constants - agoras-media: Image and video processing - agoras-core: Abstract interfaces, Feed, Sheet logic - agoras-platforms: Platform implementations - agoras: Command-line interface

Selective Installation (Advanced Users):

Install only the packages you need:

# Just utilities and logging
$ pip install agoras-common

# Media processing (includes common)
$ pip install agoras-media

# Core interfaces and business logic (includes common + media)
$ pip install agoras-core

# Platform implementations (includes all above)
$ pip install agoras-platforms

# CLI tool (includes everything)
$ pip install agoras

Package Dependencies:

The packages follow a layered dependency structure:

agoras (CLI)
└── agoras-platforms
    └── agoras-core
        ├── agoras-media
        └── agoras-common

When to Use Each Package:

Most users: pip install agoras (full CLI installation)
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)

Breaking Change: The monolithic agoras package structure has been removed. You must install from the new package structure.

Import Path Changes (v2.0)¶

All import paths have changed due to the package split. This section provides a comprehensive mapping of old v1.x imports to new v2.0 imports.

Common Utilities¶

v1.x Import	v2.0 Import
`from agoras.core.logger import logger`	`from agoras.common.logger import logger`
`from agoras.core.utils import parse_metatags`	`from agoras.common.utils import parse_metatags`
`from agoras import __version__`	`from agoras.common.version import __version__`

Media Processing¶

v1.x Import	v2.0 Import
`from agoras.core.media import MediaFactory`	`from agoras.media import MediaFactory`
`from agoras.core.media.image import Image`	`from agoras.media.image import Image`
`from agoras.core.media.video import Video`	`from agoras.media.video import Video`
`from agoras.core.media.factory import MediaFactory`	`from agoras.media.factory import MediaFactory`

Core Interfaces¶

v1.x Import	v2.0 Import
`from agoras.core.base import SocialNetwork`	`from agoras.core.interfaces import SocialNetwork`
`from agoras.core.api.base import BaseAPI`	`from agoras.core.api_base import BaseAPI`

Platform Implementations¶

v1.x Import	v2.0 Import
`from agoras.core.facebook import Facebook`	`from agoras.platforms.facebook import Facebook`
`from agoras.core.api.facebook import FacebookAPI`	`from agoras.platforms.facebook.api import FacebookAPI`
`from agoras.core.twitter import Twitter`	`from agoras.platforms.x import X`
`from agoras.core.api.twitter import TwitterAPI`	`from agoras.platforms.x.api import XAPI`
`from agoras.core.instagram import Instagram`	`from agoras.platforms.instagram import Instagram`
`from agoras.core.linkedin import LinkedIn`	`from agoras.platforms.linkedin import LinkedIn`
`from agoras.core.discord import Discord`	`from agoras.platforms.discord import Discord`
`from agoras.core.youtube import YouTube`	`from agoras.platforms.youtube import YouTube`
`from agoras.core.tiktok import TikTok`	`from agoras.platforms.tiktok import TikTok`

New Platforms (v2.0 only):

from agoras.platforms.telegram import Telegram
from agoras.platforms.threads import Threads
from agoras.platforms.whatsapp import WhatsApp
from agoras.platforms.x import X  # Twitter rebrand

Core Business Logic (Unchanged)¶

These imports remain the same in v2.0:

from agoras.core.feed import Feed
from agoras.core.feed.manager import FeedManager
from agoras.core.sheet import Sheet
from agoras.core.sheet.manager import SheetManager

CLI Commands¶

v1.x Import	v2.0 Import
`from agoras.commands.publish import PublishCommand`	`from agoras.cli.commands.publish import PublishCommand`
`from agoras.cli import main`	`from agoras.cli.main import main`

Authentication¶

v1.x Import	v2.0 Import
`from agoras.core.api.auth.base import BaseAuthManager`	`from agoras.core.auth.base import BaseAuthManager`
`from agoras.core.api.auth.storage import TokenStorage`	`from agoras.core.auth.storage import TokenStorage`
`from agoras.core.api.auth.callback_server import CallbackServer`	`from agoras.core.auth.callback_server import CallbackServer`

Understanding the Package Split¶

Why Split the Package?¶

The monolithic package structure in v1.x had several limitations:

Heavy Dependencies: All users had to install media processing libraries even if they only needed basic posting
Tight Coupling: Platform implementations were mixed with core interfaces
Large Install Size: Single package contained everything
Hard to Extend: Difficult to build custom integrations without pulling in all dependencies

The v2.0 modular architecture addresses these issues:

Selective Installation: Install only what you need
Clear Boundaries: Each package has a well-defined purpose
Smaller Footprint: Minimal installations for specific use cases
Better Extensibility: Easy to build custom platforms using just agoras-core

Package Responsibilities¶

agoras-common (Foundation)

Shared utilities and helper functions
Logging configuration
Version information
No external dependencies beyond Python standard library

agoras-media (Media Processing)

Image processing (Pillow)
Video processing (moviepy)
Media factory for creating media objects
Depends on: agoras-common

agoras-core (Business Logic)

Abstract SocialNetwork interface
Base API classes
Authentication infrastructure
Feed automation logic
Google Sheets integration
Depends on: agoras-common, agoras-media

agoras-platforms (Platform Implementations)

Concrete platform implementations (Facebook, Twitter, etc.)
Platform-specific API clients
Platform authentication handlers
Depends on: agoras-core (which includes media and common)

agoras (CLI Tool)

Command-line interface
Platform command handlers
Utility commands (feed, schedule)
Depends on: agoras-platforms (which includes all others)

Migration Strategy¶

Update Installation: Change pip install agoras to ensure you get v2.0+ (or use specific packages)
Update Imports: Use the import mapping table above to update all Python imports
Test Incrementally: Start with non-critical scripts, then migrate production code
Update CI/CD: Ensure build pipelines install the correct packages
Check Dependencies: If you only need specific functionality, consider installing only relevant packages

Why the Change?¶

Problems with the old format:

Verbose: agoras publish --network twitter --action post is unnecessarily long
Poor discoverability: Hard to find which actions a platform supports
Mixed concerns: Feed automation mixed with direct platform operations
Redundant: publish command doesn’t add semantic value

Benefits of the new format:

Shorter commands: agoras x post instead of agoras publish --network twitter --action post
Better help: agoras x --help shows only X-supported actions
Clearer structure: Platform commands vs utils commands
Simplified parameters: --consumer-key instead of --twitter-consumer-key
Tab completion: Better shell completion support

Note

X Rebrand: In Agoras 2.0+, Twitter has been rebranded to X. Use agoras x instead of agoras twitter. The agoras twitter command still works but is deprecated.

Quick Reference¶

Platform Commands¶

Legacy Format	New Format
`agoras publish --network twitter --action post`	`agoras x post`
`agoras publish --network facebook --action video`	`agoras facebook video`
`agoras publish --network youtube --action video`	`agoras youtube video`
`agoras publish --network instagram --action post`	`agoras instagram post`

Automation Commands¶

Legacy Format	New Format
`agoras publish --network twitter --action last-from-feed`	`agoras utils feed-publish --network x --mode last`
`agoras publish --network facebook --action random-from-feed`	`agoras utils feed-publish --network facebook --mode random`
`agoras publish --action schedule`	`agoras utils schedule-run`

Parameter Changes¶

Authentication Parameters¶

Within platform commands, platform prefixes are removed:

Platform	Legacy Parameter	New Parameter
X (formerly Twitter)	`--twitter-consumer-key`	`--consumer-key`
X (formerly Twitter)	`--twitter-oauth-token`	`--oauth-token`
Facebook	`--facebook-access-token`	(Removed in v2.0 - use `agoras facebook authorize` first)
Instagram	`--instagram-object-id`	`--object-id`
Discord	`--discord-bot-token`	`--bot-token`
YouTube	`--youtube-client-id`	`--client-id`

Note: Utils commands use prefixed parameters. For X, use --x-consumer-key (--twitter-consumer-key is deprecated but still works).

Content Parameters¶

Legacy Parameter	New Parameter
`--status-text`	`--text`
`--status-link`	`--link`
`--status-image-url-1`	`--image-1`
`--status-image-url-2`	`--image-2`
`--tweet-id`	`--post-id` (standardized across platforms)

Platform-by-Platform Migration¶

X (formerly Twitter)¶

Note

X Rebrand: Twitter has been rebranded to X. Use agoras x instead of agoras twitter. The agoras twitter command still works but shows a deprecation warning.

Posting a Tweet

Legacy:

agoras publish --network twitter --action post \
  --twitter-consumer-key "$TWITTER_CONSUMER_KEY" \
  --twitter-consumer-secret "$TWITTER_CONSUMER_SECRET" \
  --twitter-oauth-token "$TWITTER_OAUTH_TOKEN" \
  --twitter-oauth-secret "$TWITTER_OAUTH_SECRET" \
  --status-text "Hello World!" \
  --status-image-url-1 "https://example.com/image.jpg"

New:

agoras x post \
  --consumer-key "$TWITTER_CONSUMER_KEY" \
  --consumer-secret "$TWITTER_CONSUMER_SECRET" \
  --oauth-token "$TWITTER_OAUTH_TOKEN" \
  --oauth-secret "$TWITTER_OAUTH_SECRET" \
  --text "Hello World!" \
  --image-1 "https://example.com/image.jpg"

Deprecated since version 2.0: The agoras twitter command is deprecated. Use agoras x instead.

Uploading a Video

Legacy:

agoras publish --network twitter --action video \
  --twitter-consumer-key "$KEY" \
  --twitter-video-url "video.mp4" \
  --twitter-video-title "My Video"

New:

agoras x video \
  --consumer-key "$KEY" \
  --consumer-secret "$SECRET" \
  --oauth-token "$TOKEN" \
  --oauth-secret "$OAUTH_SECRET" \
  --video-url "video.mp4" \
  --video-title "My Video"

Authorization Flow

Legacy:

agoras publish --network twitter --action authorize \
  --twitter-consumer-key "$KEY" \
  --twitter-consumer-secret "$SECRET"

New:

agoras x authorize \
  --consumer-key "$KEY" \
  --consumer-secret "$SECRET"

Facebook¶

Creating a Post

Changed in version 2.0: Facebook now requires OAuth 2.0 authorization first.

Legacy:

agoras publish --network facebook --action post \
  --facebook-access-token "$TOKEN" \
  --facebook-object-id "$PAGE_ID" \
  --status-text "Hello Facebook"

New (v2.0+):

# First, authorize (one-time setup)
agoras facebook authorize \
  --client-id "$CLIENT_ID" \
  --client-secret "$CLIENT_SECRET" \
  --app-id "$APP_ID" \
  --object-id "$PAGE_ID"

# Then post (no tokens needed)
agoras facebook post \
  --object-id "$PAGE_ID" \
  --text "Hello Facebook"

Uploading a Video

Legacy:

agoras publish --network facebook --action video \
  --facebook-access-token "$TOKEN" \
  --facebook-object-id "$PAGE_ID" \
  --facebook-video-url "video.mp4" \
  --facebook-video-title "My Video"

New (v2.0+):

# After authorization
agoras facebook video \
  --object-id "$PAGE_ID" \
  --video-url "video.mp4" \
  --video-title "My Video"

Instagram¶

Creating a Post

Changed in version 2.0: Instagram now requires OAuth 2.0 authorization first.

Legacy:

agoras publish --network instagram --action post \
  --instagram-access-token "$TOKEN" \
  --instagram-object-id "$ACCOUNT_ID" \
  --status-text "Hello Instagram"

New (v2.0+):

# First, authorize (one-time setup)
agoras instagram authorize \
  --client-id "$CLIENT_ID" \
  --client-secret "$CLIENT_SECRET" \
  --object-id "$ACCOUNT_ID"

# Then post (no tokens needed)
agoras instagram post \
  --object-id "$ACCOUNT_ID" \
  --text "Hello Instagram"

LinkedIn¶

Creating a Post

Changed in version 2.0: LinkedIn now requires OAuth 2.0 authorization first.

Legacy:

agoras publish --network linkedin --action post \
  --linkedin-access-token "$TOKEN" \
  --status-text "Hello LinkedIn"

New (v2.0+):

# First, authorize (one-time setup)
agoras linkedin authorize \
  --client-id "$CLIENT_ID" \
  --client-secret "$CLIENT_SECRET" \
  --object-id "$OBJECT_ID"

# Then post (no tokens needed)
agoras linkedin post \
  --text "Hello LinkedIn"

Discord¶

Sending a Message

Legacy:

agoras publish --network discord --action post \
  --discord-bot-token "$BOT_TOKEN" \
  --discord-server-name "MyServer" \
  --discord-channel-name "general" \
  --status-text "Hello Discord"

New:

agoras discord post \
  --bot-token "$BOT_TOKEN" \
  --server-name "MyServer" \
  --channel-name "general" \
  --text "Hello Discord"

YouTube¶

Uploading a Video (YouTube is video-only)

Changed in version 2.0: YouTube now requires OAuth 2.0 authorization first.

Legacy:

agoras publish --network youtube --action video \
  --youtube-client-id "$CLIENT_ID" \
  --youtube-client-secret "$CLIENT_SECRET" \
  --youtube-video-url "video.mp4" \
  --youtube-title "My Video" \
  --youtube-description "Description" \
  --youtube-privacy-status "public"

New (v2.0+):

# First, authorize (one-time setup)
agoras youtube authorize \
  --client-id "$CLIENT_ID" \
  --client-secret "$CLIENT_SECRET"

# Then upload (no tokens needed)
agoras youtube video \
  --video-url "video.mp4" \
  --title "My Video" \
  --description "Description" \
  --privacy "public"

TikTok¶

Uploading a Video (TikTok is video-only)

Changed in version 2.0: TikTok now requires OAuth 2.0 authorization first.

Legacy:

agoras publish --network tiktok --action video \
  --tiktok-client-key "$KEY" \
  --tiktok-client-secret "$SECRET" \
  --tiktok-access-token "$TOKEN" \
  --tiktok-video-url "video.mp4" \
  --tiktok-title "My TikTok" \
  --tiktok-privacy-status "PUBLIC_TO_EVERYONE"

New (v2.0+):

# First, authorize (one-time setup)
agoras tiktok authorize \
  --client-key "$KEY" \
  --client-secret "$SECRET" \
  --username "$USERNAME"

# Then upload (no tokens needed)
agoras tiktok video \
  --username "$USERNAME" \
  --video-url "video.mp4" \
  --title "My TikTok" \
  --privacy "PUBLIC_TO_EVERYONE"

Threads¶

Creating a Post (New platform in CLI)

Changed in version 2.0: Threads now requires OAuth 2.0 authorization first.

New command (v2.0+):

# First, authorize (one-time setup)
agoras threads authorize \
  --app-id "$APP_ID" \
  --app-secret "$APP_SECRET"

# Then post (no tokens needed)
agoras threads post \
  --text "Hello Threads!"

Sharing a Post

New command (v2.0+):

# After authorization
agoras threads share \
  --post-id "POST_123"

Automation Commands Migration¶

Feed Automation¶

Publishing Last Entry from Feed

Legacy:

agoras publish --network twitter --action last-from-feed \
  --feed-url "https://example.com/feed.xml" \
  --feed-max-count 1 \
  --twitter-consumer-key "$KEY" \
  --twitter-consumer-secret "$SECRET" \
  --twitter-oauth-token "$TOKEN" \
  --twitter-oauth-secret "$OAUTH_SECRET"

New:

agoras utils feed-publish \
  --network x \
  --mode last \
  --feed-url "https://example.com/feed.xml" \
  --max-count 1 \
  --x-consumer-key "$KEY" \
  --x-consumer-secret "$SECRET" \
  --x-oauth-token "$TOKEN" \
  --x-oauth-secret "$OAUTH_SECRET"

Note

The --network twitter and --twitter-* parameters are deprecated. Use --network x and --x-* parameters instead.

Publishing Random Entry from Feed

Legacy:

agoras publish --network facebook --action random-from-feed \
  --feed-url "https://example.com/feed.xml" \
  --facebook-access-token "$TOKEN"

New (v2.0+):

# After authorization
agoras utils feed-publish \
  --network facebook \
  --mode random \
  --feed-url "https://example.com/feed.xml"

Schedule Automation¶

Running Scheduled Posts

Legacy:

agoras publish --network twitter --action schedule \
  --google-sheets-id "$SHEET_ID" \
  --google-sheets-name "Schedule" \
  --google-sheets-client-email "$EMAIL" \
  --google-sheets-private-key "$KEY" \
  --twitter-consumer-key "$KEY"

New:

agoras utils schedule-run \
  --network x \
  --sheets-id "$SHEET_ID" \
  --sheets-name "Schedule" \
  --sheets-client-email "$EMAIL" \
  --sheets-private-key "$KEY" \
  --x-consumer-key "$KEY"

Note

The --network twitter and --twitter-* parameters are deprecated. Use --network x and --x-* parameters instead.

Common Migration Pitfalls¶

Forgetting to remove platform prefix

Wrong:

agoras x post --twitter-consumer-key "$KEY"

Correct:

agoras x post --consumer-key "$KEY"

Using old parameter names

Wrong:

agoras x post --status-text "Hello"

Correct:

agoras x post --text "Hello"

Using deprecated twitter command

Wrong:

agoras twitter post --consumer-key "$KEY"

Correct:

agoras x post --consumer-key "$KEY"

Using platform command for feed automation

Wrong:

agoras x last-from-feed --feed-url "feed.xml"

Correct:

agoras utils feed-publish --network x --mode last --feed-url "feed.xml"

Forgetting –network in utils commands

Wrong:

agoras utils feed-publish --mode last --feed-url "feed.xml"

Correct:

agoras utils feed-publish --network x --mode last --feed-url "feed.xml"

Using deprecated parameters in utils commands

Wrong:

agoras utils feed-publish --network twitter --twitter-consumer-key "$KEY"

Correct:

agoras utils feed-publish --network x --x-consumer-key "$KEY"

Testing Your Migration¶

Preview Mode¶

Use the --show-migration flag to preview the new command without executing:

agoras publish --network twitter --action post \
  --twitter-consumer-key "$KEY" \
  --status-text "Test" \
  --show-migration

This will show:

Migration Preview:
  Old: agoras publish --network twitter --action post [options]
  New: agoras x post --consumer-key "$KEY" --text "Test"

No action executed (preview mode)

Platform-Specific Help¶

Explore new commands using help:

# See all platforms
agoras --help

# See X actions
agoras x --help

# See X post options
agoras x post --help

# See utils commands
agoras utils --help

# See feed-publish options
agoras utils feed-publish --help

Gradual Migration Strategy¶

Week 1: Test migration using --show-migration flag
Week 2: Migrate non-critical scripts to new format
Week 3: Update CI/CD pipelines with new commands
Week 4: Migrate production scripts
Ongoing: Keep legacy as fallback until comfortable

Remember: The legacy agoras publish command will continue to work with deprecation warnings for 12 months.

Complete Parameter Reference¶

X (formerly Twitter) Parameters¶

Legacy	New (Platform)	New (Utils)
`--twitter-consumer-key`	`--consumer-key`	`--x-consumer-key` (`--twitter-consumer-key` deprecated)
`--twitter-consumer-secret`	`--consumer-secret`	`--x-consumer-secret` (`--twitter-consumer-secret` deprecated)
`--twitter-oauth-token`	`--oauth-token`	`--x-oauth-token` (`--twitter-oauth-token` deprecated)
`--twitter-oauth-secret`	`--oauth-secret`	`--x-oauth-secret` (`--twitter-oauth-secret` deprecated)
`--tweet-id`	`--post-id`	`--post-id`

Note

For utils commands, use --x-* parameters. The --twitter-* parameters are deprecated but still work with deprecation warnings.

Facebook Parameters¶

Legacy	New (Platform)	New (Utils)
`--facebook-access-token`	(Removed in v2.0 - use `agoras facebook authorize` first)	(Removed in v2.0)
`--facebook-object-id`	`--object-id`	`--facebook-object-id`
`--facebook-post-id`	`--post-id`	`--post-id`
`--facebook-app-id`	`--app-id`	`--facebook-app-id`

Content Parameters (All Platforms)¶

Legacy	New
`--status-text`	`--text`
`--status-link`	`--link`
`--status-image-url-1`	`--image-1`
`--status-image-url-2`	`--image-2`
`--status-image-url-3`	`--image-3`
`--status-image-url-4`	`--image-4`

Feed Parameters¶

Legacy	New
`--feed-url`	`--feed-url` (unchanged)
`--feed-max-count`	`--max-count`
`--feed-post-lookback`	`--post-lookback`
`--feed-max-post-age`	`--max-post-age`

Google Sheets Parameters¶

Legacy	New
`--google-sheets-id`	`--sheets-id`
`--google-sheets-name`	`--sheets-name`
`--google-sheets-client-email`	`--sheets-client-email`
`--google-sheets-private-key`	`--sheets-private-key`

Frequently Asked Questions¶

Installation & Packages¶

Q: Do I need to install all 5 packages separately?¶

A: No. Installing pip install agoras automatically installs all 5 packages as dependencies. You only need to install packages separately if you want to use Agoras as a Python library without the CLI.

Q: Can I install only specific packages?¶

A: Yes, for advanced use cases. See Installation for details. Most users should install the main agoras package.

Q: What’s the difference between `agoras` and `agoras-platforms`?¶

A: The agoras package includes the CLI tool and all dependencies. The agoras-platforms package includes all platform implementations but no CLI - use it if you’re building Python integrations without the command-line interface.

CLI Commands¶

Q: Why did the command format change?¶

A: The new format is more intuitive and discoverable. Instead of agoras publish --network twitter --action post, you now use agoras x post. This makes it easier to discover what actions each platform supports and reduces command length.

Q: Can I still use `agoras publish`?¶

A: Yes, the legacy agoras publish command still works but shows deprecation warnings. It will be supported for 12 months from the v2.0 release. We recommend migrating to the new format as soon as possible.

Q: What’s the difference between platform commands and utils commands?¶

A: Platform commands (e.g., agoras x post) are for direct platform operations and use simplified parameter names (--consumer-key instead of --x-consumer-key). Utils commands (e.g., agoras utils feed-publish) are for automation tasks and use prefixed parameters to support multiple platforms in one command.

Q: Why do utils commands use prefixed parameters?¶

A: Utils commands need to support multiple platforms, so they use prefixed parameters (e.g., --x-consumer-key, --facebook-object-id) to avoid conflicts when specifying credentials for different platforms in the same command.

OAuth 2.0 Authentication¶

Q: Why do I need to run `authorize` first for some platforms?¶

A: OAuth 2.0 platforms (Facebook, Instagram, LinkedIn, YouTube, TikTok, Threads) require a one-time authorization step. This is more secure than passing tokens directly and allows automatic token refresh. Bot-based platforms (Discord, Telegram) and API key platforms (X) don’t require this step.

Q: Do I need to re-authorize if I upgrade?¶

A: No. Once you’ve authorized, your tokens are stored securely and persist across upgrades. You only need to re-authorize if you revoke access or if your tokens expire.

Q: Where are tokens stored?¶

A: Tokens are stored in a secure location on your system. The exact location depends on your operating system. See agoras.core.api_base module for details on token storage. For more information, check the authentication documentation in the API reference.

Q: How do I revoke authorization?¶

A: You can revoke authorization through the platform’s developer console (Facebook Developer Portal, Google Cloud Console, etc.). Agoras will automatically detect revoked tokens and prompt you to re-authorize.

Parameter Names¶

Q: Why did parameter names change?¶

A: Parameter names were simplified for better usability. For example, --status-text became --text, and --twitter-consumer-key became --consumer-key in platform commands. This makes commands shorter and easier to remember.

Q: Can I still use old parameter names?¶

A: In platform commands, old parameter names are not supported. In utils commands, some deprecated parameter names (like --twitter-*) still work but show deprecation warnings. See Complete Parameter Reference for the complete parameter reference.

Q: Why are some parameters different in utils commands?¶

A: Utils commands support multiple platforms, so they use prefixed parameters (e.g., --x-consumer-key) to avoid conflicts. Platform commands only work with one platform, so they use simplified names (e.g., --consumer-key).

Import Paths (Python)¶

Q: Do I need to update my Python imports?¶

A: Yes, if you’re using Agoras as a Python library. All import paths have changed due to the package split. See the “Import Path Changes” section above for a complete mapping.

Q: Where can I find the import mapping?¶

A: See the “Import Path Changes” section in this migration guide. It provides comprehensive tables mapping old v1.x imports to new v2.0 imports.

Q: What if my imports don’t work?¶

A: First, ensure you’ve installed the correct packages. If you’re using agoras-platforms, make sure it’s installed. If you’re using agoras-core, ensure all dependencies are installed. Check the import mapping table and verify your import paths match the new structure. If issues persist, open an issue on GitHub.

Migration Timeline¶

Q: How long will legacy commands be supported?¶

A: The legacy agoras publish command will be supported with deprecation warnings for 12 months from the v2.0 release. After that, it will be removed. We recommend migrating as soon as possible.

Q: When should I migrate?¶

A: You can migrate at any time. The legacy commands still work, so you can migrate gradually. We recommend starting with non-critical scripts, then moving to production code once you’re comfortable with the new format.

Q: Can I migrate gradually?¶

A: Yes! You can use both old and new commands during the transition period. Start by migrating new scripts to the new format, then gradually update existing scripts. The --show-migration flag can help you preview the new command format.

Troubleshooting¶

Q: I get “command not found” errors¶

A: Ensure Agoras is installed correctly: pip install agoras. Verify the installation: agoras --version. If using a virtual environment, make sure it’s activated. Check that the agoras command is in your PATH.

Q: My old scripts don’t work¶

A: Old scripts using agoras publish should still work but may show deprecation warnings. If they fail completely, check: - Are you using the correct parameter names? - Have you updated to v2.0+? - Are all required parameters provided? - For OAuth platforms, have you run authorize first?

Q: I see deprecation warnings¶

A: Deprecation warnings indicate you’re using old commands or parameters that will be removed in the future. Update your commands to the new format. The warnings won’t break your scripts, but you should migrate to avoid issues when legacy support is removed.

Q: OAuth authorization fails¶

A: Check that: - Your app credentials (client ID, client secret) are correct - Your redirect URI matches what’s configured in the platform’s developer console - You have the necessary permissions/scopes enabled in your app - Your app is approved for production use (if required by the platform)

Q: Platform command says “not authorized”¶

A: For OAuth platforms, you must run agoras <platform> authorize first. After authorization, tokens are stored and you don’t need to authorize again unless you revoke access.

Q: Utils command fails with “network not specified”¶

A: Utils commands require the --network parameter to specify which platform to use. For example: agoras utils feed-publish --network x --mode last ...

Getting Help¶

Documentation: https://docs.agoras.io
Migration Issues: https://github.com/LuisAlejandro/agoras/issues
Community: https://github.com/LuisAlejandro/agoras/discussions

The legacy agoras publish command will be supported with deprecation warnings until Agoras 2.0 (12 months from the 2.0 release).

Migration Guide: Legacy to New CLI¶

Overview¶

Package Installation (v2.0+)¶

Import Path Changes (v2.0)¶

Common Utilities¶

Media Processing¶

Core Interfaces¶

Platform Implementations¶

Core Business Logic (Unchanged)¶

CLI Commands¶

Authentication¶

Understanding the Package Split¶

Why Split the Package?¶

Package Responsibilities¶

Migration Strategy¶

Why the Change?¶

Quick Reference¶

Platform Commands¶

Automation Commands¶

Parameter Changes¶

Authentication Parameters¶

Content Parameters¶

Platform-by-Platform Migration¶

X (formerly Twitter)¶

Facebook¶

Instagram¶

LinkedIn¶

Discord¶

YouTube¶

TikTok¶

Threads¶

Automation Commands Migration¶

Feed Automation¶

Schedule Automation¶

Common Migration Pitfalls¶

Testing Your Migration¶

Preview Mode¶

Platform-Specific Help¶

Gradual Migration Strategy¶

Complete Parameter Reference¶

X (formerly Twitter) Parameters¶

Facebook Parameters¶

Content Parameters (All Platforms)¶

Feed Parameters¶

Google Sheets Parameters¶

Frequently Asked Questions¶

Installation & Packages¶

Q: Do I need to install all 5 packages separately?¶

Q: Can I install only specific packages?¶

Q: What’s the difference between agoras and agoras-platforms?¶

CLI Commands¶

Q: Why did the command format change?¶

Q: Can I still use agoras publish?¶

Q: What’s the difference between platform commands and utils commands?¶

Q: Why do utils commands use prefixed parameters?¶

OAuth 2.0 Authentication¶

Q: Why do I need to run authorize first for some platforms?¶

Q: Do I need to re-authorize if I upgrade?¶

Q: Where are tokens stored?¶

Q: How do I revoke authorization?¶

Parameter Names¶

Q: Why did parameter names change?¶

Q: Can I still use old parameter names?¶

Q: Why are some parameters different in utils commands?¶

Import Paths (Python)¶

Q: Do I need to update my Python imports?¶

Q: Where can I find the import mapping?¶

Q: What if my imports don’t work?¶

Migration Timeline¶

Q: How long will legacy commands be supported?¶

Q: When should I migrate?¶

Q: Can I migrate gradually?¶

Troubleshooting¶

Q: I get “command not found” errors¶

Q: My old scripts don’t work¶

Q: I see deprecation warnings¶

Q: OAuth authorization fails¶

Q: Platform command says “not authorized”¶

Q: Utils command fails with “network not specified”¶

Getting Help¶

Q: What’s the difference between `agoras` and `agoras-platforms`?¶

Q: Can I still use `agoras publish`?¶

Q: Why do I need to run `authorize` first for some platforms?¶