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 migration/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 is supported through all Agoras 2.x releases and will be removed in Agoras 3.0. 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 migration/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 migration/imports section for a complete mapping.

Q: Where can I find the import mapping?

A: See the migration/imports section. 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 is supported with deprecation warnings through all Agoras 2.x releases and will be removed in Agoras 3.0. 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.

Common Migration Pitfalls

  1. Forgetting to remove platform prefix

    Wrong:

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

    Correct:

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

  2. Using old parameter names

    Wrong:

    agoras x post --status-text "Hello"

    Correct:

    agoras x post --text "Hello"

  3. Using deprecated twitter command

    Wrong:

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

    Correct:

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

  4. 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"

  5. 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"

  6. 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"

Troubleshooting

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.

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?

A: Deprecation warnings indicate you’re using old commands or parameters that will be removed in Agoras 3.0 (legacy agoras publish is supported through all 2.x releases). Update your commands to the new format. The warnings won’t break your scripts, but you should migrate before upgrading to 3.0.

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)

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.

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