Docs & example

examples/feature_showcase/main.rs

@@ -19,6 +19,9 @@ mod subcommand_required;
 mod subcommands;
 mod track_edits;
 
+#[cfg(feature = "unstable")]
+mod user_apps;
+
 use poise::serenity_prelude as serenity;
 
 type Error = Box<dyn std::error::Error + Send + Sync>;
@@ -75,6 +78,16 @@ async fn main() {
                 subcommand_required::parent_subcommand_required(),
                 track_edits::test_reuse_response(),
                 track_edits::add(),
+                #[cfg(feature = "unstable")]
+                user_apps::everywhere(),
+                #[cfg(feature = "unstable")]
+                user_apps::everywhere_context(),
+                #[cfg(feature = "unstable")]
+                user_apps::user_install(),
+                #[cfg(feature = "unstable")]
+                user_apps::not_in_guilds(),
+                #[cfg(feature = "unstable")]
+                user_apps::user_install_guild(),
             ],
             prefix_options: poise::PrefixFrameworkOptions {
                 prefix: Some("~".into()),

examples/feature_showcase/user_apps.rs

@@ -0,0 +1,60 @@
+use crate::{Context, Error};
+use poise::serenity_prelude as serenity;
+
+// `install_context` determines how the bot has to be installed for a command to be available.
+// `interaction_context` determines where a command can be used.
+
+/// Available everywhere
+#[poise::command(
+    slash_command,
+    install_context = "Guild|User",
+    interaction_context = "Guild|BotDm|PrivateChannel"
+)]
+pub async fn everywhere(ctx: Context<'_>) -> Result<(), Error> {
+    ctx.say("This command is available everywhere!").await?;
+    Ok(())
+}
+
+// also works with `context_menu_command`
+/// Available everywhere
+#[poise::command(
+    context_menu_command = "Everywhere",
+    install_context = "Guild|User",
+    interaction_context = "Guild|BotDm|PrivateChannel"
+)]
+pub async fn everywhere_context(ctx: Context<'_>, msg: serenity::Message) -> Result<(), Error> {
+    msg.reply(ctx, "This context menu is available everywhere!")
+        .await?;
+    Ok(())
+}
+
+/// Available with a user install only
+#[poise::command(
+    slash_command,
+    install_context = "User",
+    interaction_context = "Guild|BotDm|PrivateChannel"
+)]
+pub async fn user_install(ctx: Context<'_>) -> Result<(), Error> {
+    ctx.say("This command is available only with a user install!")
+        .await?;
+    Ok(())
+}
+
+/// Not available in guilds
+#[poise::command(
+    slash_command,
+    install_context = "User",
+    interaction_context = "BotDm|PrivateChannel"
+)]
+pub async fn not_in_guilds(ctx: Context<'_>) -> Result<(), Error> {
+    ctx.say("This command is not available in guilds!").await?;
+    Ok(())
+}
+
+/// User install only in guilds
+#[poise::command(slash_command, install_context = "User", interaction_context = "Guild")]
+pub async fn user_install_guild(ctx: Context<'_>) -> Result<(), Error> {
+    ctx.say("This command is available in guilds only with a user install!")
+        .await?;
+    Ok(())
+}

macros/src/lib.rs

@@ -37,6 +37,8 @@ for example for command-specific help (i.e. `~help command_name`). Escape newlin
 - `category`: Category of this command which affects placement in the help command
 - `custom_data`: Arbitrary expression that will be boxed and stored in `Command::custom_data`
 - `identifying_name`: Optionally, a unique identifier for this command for your personal usage
+- `install_context`: Installation contexts where this command is available (slash-only) (`unstable` feature)
+- `interaction_context`: Interaction contexts where this command is available (slash-only) (`unstable` feature)
 
 ## Checks