discordcli-agents 0.1.0__py3-none-any.whl

discord_cli/__init__.py

@@ -0,0 +1,3 @@
+"""discord-cli: command-line tool for managing Discord servers and AI-driven automation."""
+
+__version__ = "0.1.0"

discord_cli/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running the package as `python -m discord_cli`."""
+
+from discord_cli.cli import main
+
+if __name__ == "__main__":
+    main()

discord_cli/cli.py

@@ -0,0 +1,48 @@
+"""Command-line entry point for discord-cli."""
+
+from __future__ import annotations
+
+import click
+
+from discord_cli import __version__
+
+# Import all command modules to register them
+from discord_cli.commands import (
+    categories,
+    channels,
+    export,
+    guilds,
+    invites,
+    members,
+    messages,
+    permissions,
+    roles,
+    search,
+    threads,
+    webhooks,
+)
+
+
+@click.group()
+@click.version_option(version=__version__, prog_name="discord-cli")
+def main() -> None:
+    """Command-line tool for managing Discord servers and automating Discord via AI agents."""
+
+
+# Register all command groups
+main.add_command(channels.channel)
+main.add_command(categories.category)
+main.add_command(roles.role)
+main.add_command(members.member)
+main.add_command(messages.message)
+main.add_command(guilds.guild)
+main.add_command(permissions.permissions)
+main.add_command(webhooks.webhook)
+main.add_command(invites.invites)
+main.add_command(threads.threads)
+main.add_command(search.search)
+main.add_command(export.export)
+
+
+if __name__ == "__main__":
+    main()

discord_cli/client.py

@@ -0,0 +1,102 @@
+"""Discord bot lifecycle: connect, run a single action, print the result, exit."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncIterator, Awaitable
+from contextlib import asynccontextmanager
+from typing import Any, Callable
+
+import discord
+
+from discord_cli.config import load_config
+from discord_cli.errors import DiscordCliError
+from discord_cli.output import make_payload, print_output
+
+Action = Callable[..., Awaitable[Any]]
+
+
+class ManagementClient(discord.Client):
+    """A discord.Client that runs a single action on_ready and then closes."""
+
+    def __init__(self, action: Action, kwargs: dict[str, Any], intents: discord.Intents):
+        super().__init__(intents=intents)
+        self.action = action
+        self.kwargs = kwargs
+        self.result: Any = None
+        self.error: dict[str, Any] | None = None
+
+    async def on_ready(self) -> None:
+        try:
+            self.result = await self.action(self, **self.kwargs)
+        except Exception as exc:  # noqa: BLE001 - user-facing CLI boundary
+            self.error = {"type": exc.__class__.__name__, "message": str(exc)}
+            if isinstance(exc, discord.HTTPException):
+                self.error.update({"status": exc.status, "code": exc.code})
+        finally:
+            await self.close()
+
+
+@asynccontextmanager
+async def bot_session(client: ManagementClient, token: str) -> AsyncIterator[ManagementClient]:
+    """Connect the client, let it run its action to completion, and guarantee it closes."""
+    try:
+        await client.start(token)
+        yield client
+    finally:
+        if not client.is_closed():
+            await client.close()
+
+
+def fallback_intents() -> discord.Intents:
+    intents = discord.Intents.default()
+    intents.guilds = True
+    intents.reactions = True
+    return intents
+
+
+async def _run_async(
+    action: Action, kwargs: dict[str, Any], token: str
+) -> tuple[Any, dict[str, Any] | None]:
+    last_error: dict[str, Any] | None = None
+    for intents in (discord.Intents.all(), fallback_intents()):
+        client = ManagementClient(action, kwargs, intents)
+        try:
+            async with bot_session(client, token) as session:
+                result, error = session.result, session.error
+        except discord.PrivilegedIntentsRequired as exc:
+            last_error = {"type": exc.__class__.__name__, "message": str(exc)}
+            continue
+        except Exception as exc:  # noqa: BLE001 - user-facing CLI boundary
+            return None, {"type": exc.__class__.__name__, "message": str(exc)}
+        if last_error and error is None and isinstance(result, dict):
+            result.setdefault(
+                "warning",
+                "Retried with non-privileged intents because privileged intents are not enabled for this bot.",
+            )
+        return result, error
+    return None, last_error
+
+
+def run_bot(
+    action: Action, kwargs: dict[str, Any], token: str
+) -> tuple[Any, dict[str, Any] | None]:
+    """Run `action` against a freshly connected bot and return (result, error)."""
+    return asyncio.run(_run_async(action, kwargs, token))
+
+
+def run_action(
+    action: Action, kwargs: dict[str, Any], human: bool, token: str | None = None
+) -> None:
+    """Load config, run the action against the bot, print the payload, and exit with its status."""
+    try:
+        bot_token = load_config(token).bot_token
+    except DiscordCliError as exc:
+        payload = make_payload(error={"type": exc.__class__.__name__, "message": str(exc)})
+        print_output(payload, human)
+        raise SystemExit(1) from None
+
+    result, error = run_bot(action, kwargs, bot_token)
+    payload = make_payload(result, error)
+    print_output(payload, human)
+    raise SystemExit(0 if payload["ok"] else 1)

discord_cli/commands/__init__.py

@@ -0,0 +1 @@
+"""Command implementations for discord-cli, grouped by resource (channel, role, member, ...)."""

discord_cli/commands/categories.py

@@ -0,0 +1,93 @@
+"""Category commands: list, create, delete, edit."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import click
+import discord
+
+from discord_cli.errors import CliError
+from discord_cli.models import channel_to_dict, get_category, get_guild
+from discord_cli.registry import invoke, registry
+
+
+@registry.group("category")
+def category_group() -> None:
+    """Manage channel categories."""
+
+
+@category_group.command("list")
+@click.pass_context
+def category_list(ctx: click.Context) -> None:
+    invoke(ctx, action_category_list)
+
+
+@category_group.command("create")
+@click.argument("name")
+@click.option("--position", type=int, default=None)
+@click.pass_context
+def category_create(ctx: click.Context, name: str, position: int | None) -> None:
+    invoke(ctx, action_category_create, name=name, position=position)
+
+
+@category_group.command("delete")
+@click.argument("category_id", type=int)
+@click.pass_context
+def category_delete(ctx: click.Context, category_id: int) -> None:
+    invoke(ctx, action_category_delete, category_id=category_id)
+
+
+@category_group.command("edit")
+@click.argument("category_id", type=int)
+@click.option("--name", default=None)
+@click.option("--position", type=int, default=None)
+@click.pass_context
+def category_edit(
+    ctx: click.Context, category_id: int, name: str | None, position: int | None
+) -> None:
+    invoke(ctx, action_category_edit, category_id=category_id, name=name, position=position)
+
+
+async def action_category_list(client: discord.Client, guild_id: int | None, **_: Any) -> Any:
+    guild = await get_guild(client, guild_id)
+    return {
+        "guild_id": guild.id,
+        "categories": [channel_to_dict(c, detailed=True) for c in guild.categories],
+    }
+
+
+async def action_category_create(
+    client: discord.Client, guild_id: int | None, name: str, position: int | None, **_: Any
+) -> Any:
+    guild = await get_guild(client, guild_id)
+    category = await guild.create_category(
+        name, position=position, reason="discord_cli category create"
+    )
+    return {"created": channel_to_dict(category, detailed=True)}
+
+
+async def action_category_delete(
+    client: discord.Client, guild_id: int | None, category_id: int, **_: Any
+) -> Any:
+    guild = await get_guild(client, guild_id)
+    category = get_category(guild, category_id)
+    data = channel_to_dict(category)
+    await category.delete(reason="discord_cli category delete")
+    return {"deleted": data}
+
+
+async def action_category_edit(
+    client: discord.Client, guild_id: int | None, category_id: int, **kwargs: Any
+) -> Any:
+    guild = await get_guild(client, guild_id)
+    category = get_category(guild, category_id)
+    edits = {
+        k: v
+        for k, v in {"name": kwargs.get("name"), "position": kwargs.get("position")}.items()
+        if v is not None
+    }
+    if not edits:
+        raise CliError("No edits provided")
+    await category.edit(**edits, reason="discord_cli category edit")
+    return {"updated": channel_to_dict(category, detailed=True)}

discord_cli/commands/channels.py

@@ -0,0 +1,198 @@
+"""Channel commands: list, create, delete, edit, move, info."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import click
+import discord
+
+from discord_cli.errors import CliError
+from discord_cli.models import channel_to_dict, get_category, get_channel, get_guild
+from discord_cli.registry import TRI_STATE_BOOL, invoke, registry
+
+
+@registry.group("channel")
+def channel_group() -> None:
+    """Manage guild channels."""
+
+
+@channel_group.command("list")
+@click.pass_context
+def channel_list(ctx: click.Context) -> None:
+    invoke(ctx, action_channel_list)
+
+
+@channel_group.command("create")
+@click.argument("name")
+@click.option(
+    "--type", "channel_type", type=click.Choice(["text", "voice", "stage", "forum"]), default="text"
+)
+@click.option("--category", type=int, default=None)
+@click.option("--topic", default=None)
+@click.option("--position", type=int, default=None)
+@click.option("--nsfw", is_flag=True, default=False)
+@click.option("--slowmode", type=int, default=None)
+@click.pass_context
+def channel_create(
+    ctx: click.Context,
+    name: str,
+    channel_type: str,
+    category: int | None,
+    topic: str | None,
+    position: int | None,
+    nsfw: bool,
+    slowmode: int | None,
+) -> None:
+    invoke(
+        ctx,
+        action_channel_create,
+        name=name,
+        type=channel_type,
+        category=category,
+        topic=topic,
+        position=position,
+        nsfw=nsfw,
+        slowmode=slowmode,
+    )
+
+
+@channel_group.command("delete")
+@click.argument("channel_id", type=int)
+@click.pass_context
+def channel_delete(ctx: click.Context, channel_id: int) -> None:
+    invoke(ctx, action_channel_delete, channel_id=channel_id)
+
+
+@channel_group.command("edit")
+@click.argument("channel_id", type=int)
+@click.option("--name", default=None)
+@click.option("--topic", default=None)
+@click.option("--position", type=int, default=None)
+@click.option("--slowmode", type=int, default=None)
+@click.option("--nsfw", type=TRI_STATE_BOOL, default=None)
+@click.pass_context
+def channel_edit(
+    ctx: click.Context,
+    channel_id: int,
+    name: str | None,
+    topic: str | None,
+    position: int | None,
+    slowmode: int | None,
+    nsfw: bool | None,
+) -> None:
+    invoke(
+        ctx,
+        action_channel_edit,
+        channel_id=channel_id,
+        name=name,
+        topic=topic,
+        position=position,
+        slowmode=slowmode,
+        nsfw=nsfw,
+    )
+
+
+@channel_group.command("move")
+@click.argument("channel_id", type=int)
+@click.option("--category", type=int, required=True)
+@click.pass_context
+def channel_move(ctx: click.Context, channel_id: int, category: int) -> None:
+    invoke(ctx, action_channel_move, channel_id=channel_id, category=category)
+
+
+@channel_group.command("info")
+@click.argument("channel_id", type=int)
+@click.pass_context
+def channel_info(ctx: click.Context, channel_id: int) -> None:
+    invoke(ctx, action_channel_info, channel_id=channel_id)
+
+
+async def action_channel_list(client: discord.Client, guild_id: int | None, **_: Any) -> Any:
+    guild = await get_guild(client, guild_id)
+    return {"guild_id": guild.id, "channels": [channel_to_dict(c) for c in guild.channels]}
+
+
+async def action_channel_create(client: discord.Client, guild_id: int | None, **kwargs: Any) -> Any:
+    guild = await get_guild(client, guild_id)
+    category = get_category(guild, kwargs.get("category"))
+    common = {
+        "category": category,
+        "position": kwargs.get("position"),
+        "reason": "discord_cli channel create",
+    }
+    common = {k: v for k, v in common.items() if v is not None}
+    ctype = kwargs.get("type") or "text"
+    name = kwargs["name"]
+    if ctype == "text":
+        channel = await guild.create_text_channel(
+            name,
+            topic=kwargs.get("topic"),
+            nsfw=kwargs.get("nsfw", False),
+            slowmode_delay=kwargs.get("slowmode") or 0,
+            **common,
+        )
+    elif ctype == "voice":
+        channel = await guild.create_voice_channel(name, **common)
+    elif ctype == "stage":
+        channel = await guild.create_stage_channel(name, **common)
+    elif ctype == "forum":
+        channel = await guild.create_forum_channel(
+            name,
+            topic=kwargs.get("topic"),
+            nsfw=kwargs.get("nsfw", False),
+            slowmode_delay=kwargs.get("slowmode") or 0,
+            **common,
+        )
+    else:
+        raise CliError(f"Unsupported channel type: {ctype}")
+    return {"created": channel_to_dict(channel, detailed=True)}
+
+
+async def action_channel_delete(
+    client: discord.Client, guild_id: int | None, channel_id: int, **_: Any
+) -> Any:
+    guild = await get_guild(client, guild_id)
+    channel = get_channel(guild, channel_id)
+    data = channel_to_dict(channel)
+    await channel.delete(reason="discord_cli channel delete")
+    return {"deleted": data}
+
+
+async def action_channel_edit(
+    client: discord.Client, guild_id: int | None, channel_id: int, **kwargs: Any
+) -> Any:
+    guild = await get_guild(client, guild_id)
+    channel = get_channel(guild, channel_id)
+    edits: dict[str, Any] = {}
+    if kwargs.get("name") is not None:
+        edits["name"] = kwargs["name"]
+    if kwargs.get("topic") is not None and hasattr(channel, "topic"):
+        edits["topic"] = kwargs["topic"]
+    if kwargs.get("position") is not None:
+        edits["position"] = kwargs["position"]
+    if kwargs.get("slowmode") is not None and hasattr(channel, "slowmode_delay"):
+        edits["slowmode_delay"] = kwargs["slowmode"]
+    if kwargs.get("nsfw") is not None and hasattr(channel, "nsfw"):
+        edits["nsfw"] = kwargs["nsfw"]
+    if not edits:
+        raise CliError("No edits provided")
+    edited = await channel.edit(**edits, reason="discord_cli channel edit")
+    return {"updated": channel_to_dict(edited or channel, detailed=True)}
+
+
+async def action_channel_move(
+    client: discord.Client, guild_id: int | None, channel_id: int, category: int, **_: Any
+) -> Any:
+    guild = await get_guild(client, guild_id)
+    channel = get_channel(guild, channel_id)
+    new_category = get_category(guild, category)
+    await channel.edit(category=new_category, reason="discord_cli channel move")
+    return {"updated": channel_to_dict(channel, detailed=True)}
+
+
+async def action_channel_info(
+    client: discord.Client, guild_id: int | None, channel_id: int, **_: Any
+) -> Any:
+    guild = await get_guild(client, guild_id)
+    return channel_to_dict(get_channel(guild, channel_id), detailed=True)

discord_cli/commands/export.py

@@ -0,0 +1,66 @@
+"""Export commands."""
+
+from __future__ import annotations
+
+import csv
+import io
+
+import click
+
+from ..client import run_bot
+from ..output import output
+
+
+@click.group()
+def export() -> None:
+    """Export channel data."""
+
+
+@export.command("channel")
+@click.argument("channel_id", type=int)
+@click.option("--limit", type=int, default=100, help="Number of messages to export")
+@click.option("--format", type=click.Choice(["json", "csv"]), default="json")
+@click.pass_context
+def export_channel(ctx: click.Context, channel_id: int, limit: int, fmt: str) -> None:
+    """Export messages from a channel."""
+
+    async def _action(client, **kwargs):
+        guild = client.guilds[0]
+        channel = guild.get_channel(channel_id)
+        if not channel:
+            raise ValueError(f"Channel {channel_id} not found")
+
+        messages = []
+        async for msg in channel.history(limit=limit):
+            messages.append(
+                {
+                    "id": msg.id,
+                    "author_id": msg.author.id,
+                    "author_name": msg.author.name,
+                    "content": msg.content,
+                    "created_at": msg.created_at.isoformat(),
+                    "edited_at": msg.edited_at.isoformat() if msg.edited_at else None,
+                    "attachments": [
+                        {"url": a.url, "filename": a.filename, "content_type": a.content_type}
+                        for a in msg.attachments
+                    ],
+                    "embeds": len(msg.embeds),
+                    "pinned": msg.pinned,
+                }
+            )
+
+        if fmt == "csv":
+            output_buf = io.StringIO()
+            writer = csv.DictWriter(
+                output_buf,
+                fieldnames=["id", "author_id", "author_name", "content", "created_at", "pinned"],
+            )
+            writer.writeheader()
+            for m in messages:
+                writer.writerow({k: m.get(k, "") for k in writer.fieldnames})
+            return {"format": "csv", "count": len(messages), "data": output_buf.getvalue()}
+        else:
+            return {"format": "json", "count": len(messages), "messages": messages}
+
+    result, error = run_bot(_action, ctx=ctx)
+    output(result, error, ctx)