discordcli-agents 0.1.0__tar.gz

discordcli_agents-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,34 @@
+name: Bug report
+description: Report a reproducible problem with discord-cli.
+title: "[Bug]: "
+labels: [bug]
+body:
+  - type: markdown
+    attributes:
+      value: "Thanks for reporting a bug. Please remove any tokens or sensitive server data."
+  - type: input
+    id: version
+    attributes:
+      label: discord-cli version
+      placeholder: "0.1.0"
+    validations:
+      required: true
+  - type: textarea
+    id: description
+    attributes:
+      label: What happened?
+      description: Include expected and actual behavior.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to reproduce
+      placeholder: "1. Run ...\n2. Observe ..."
+    validations:
+      required: true
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: Include OS and Python version.

discordcli_agents-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,26 @@
+name: Feature request
+description: Suggest an improvement to discord-cli.
+title: "[Feature]: "
+labels: [enhancement]
+body:
+  - type: markdown
+    attributes:
+      value: "Thanks for sharing an idea. Do not include tokens or private server data."
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem to solve
+      description: What workflow or limitation does this address?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: Describe the behavior you would like.
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered

discordcli_agents-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,14 @@
+## Summary
+
+Describe the change and the problem it solves.
+
+## Validation
+
+- [ ] `ruff check src/`
+- [ ] `ruff format --check src/`
+- [ ] Tests or the import smoke test pass
+- [ ] Documentation and changelog are updated when needed
+
+## Security
+
+- [ ] No bot tokens, webhook URLs, private server data, or other credentials are included

discordcli_agents-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,61 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install Ruff
+        run: pip install ruff
+      - name: Lint source
+        run: ruff check src/
+      - name: Check formatting
+        run: ruff format --check src/
+
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install project and development dependencies
+        run: pip install -e ".[dev]"
+      - name: Run tests or smoke test
+        shell: bash
+        run: |
+          if [ -d tests ] && find tests -name 'test_*.py' -print -quit | grep -q .; then
+            python -m pytest tests/
+          else
+            python -c "import discord_cli; print(discord_cli.__version__)"
+          fi
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install build tools
+        run: pip install build
+      - name: Build distribution
+        run: python -m build
+      - name: Upload distribution artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/

discordcli_agents-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,77 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install release checks and build tools
+        run: pip install -e ".[dev]"
+      - name: Run lint checks
+        run: |
+          ruff check src/
+          ruff format --check src/
+      - name: Run tests or smoke test
+        shell: bash
+        run: |
+          if [ -d tests ] && find tests -name 'test_*.py' -print -quit | grep -q .; then
+            python -m pytest tests/
+          else
+            python -c "import discord_cli; print(discord_cli.__version__)"
+          fi
+      - name: Build source and wheel distributions
+        run: python -m build
+      - name: Upload distribution artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Publish distribution to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  create-github-release:
+    needs: publish-pypi
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Create GitHub release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ github.ref_name }}
+          name: ${{ github.ref_name }}
+          body_path: CHANGELOG.md
+          files: dist/*
+          draft: false
+          prerelease: false

discordcli_agents-0.1.0/.gitignore

@@ -0,0 +1,41 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*$py.class
+*.so
+
+# Virtual environments
+venv/
+.venv/
+env/
+ENV/
+
+# Environment variables
+.env
+
+# Build artifacts
+dist/
+build/
+*.egg-info/
+.eggs/
+.tox/
+
+# Test / cache
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Editors
+.vscode/
+.idea/
+*.swp
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Archived source
+legacy/

discordcli_agents-0.1.0/.python-version

@@ -0,0 +1 @@
+3.11

discordcli_agents-0.1.0/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to discord-cli will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-07-13
+
+### Added
+
+- Initial release of discordcli-agents
+- 50+ commands across 12 command groups (channels, categories, roles, members, messages, guilds, permissions, webhooks, invites, threads, search, export)
+- JSON output by default with `--human` flag for table output
+- Headless operation (connect, act, disconnect)
+- AI agent-friendly design with structured JSON output
+- Modular command architecture with plugin-friendly registry pattern

discordcli_agents-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,39 @@
+# Contributing
+
+Thanks for helping improve discord-cli.
+
+## Development setup
+
+Use Python 3.9 or newer, then install the project and development dependencies:
+
+```bash
+git clone https://github.com/1solomonwakhungu/discord-cli.git
+cd discord-cli
+python -m pip install -e ".[dev]"
+```
+
+Run the checks before opening a pull request:
+
+```bash
+ruff check src/
+ruff format --check src/
+python -m pytest tests/
+```
+
+If the repository has no tests for your change yet, run the import smoke test:
+
+```bash
+python -c "import discord_cli; print(discord_cli.__version__)"
+```
+
+## Pull requests
+
+Keep pull requests focused, include tests when practical, and describe user-visible changes. Do not commit bot tokens, `.env` files, or other credentials.
+
+Use Conventional Commit-style subjects:
+
+- `feat:` for a new feature
+- `fix:` for a bug fix
+- `docs:` for documentation-only changes
+- `chore:` for maintenance
+- `refactor:` for code restructuring without behavior changes

discordcli_agents-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 1solomonwakhungu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

discordcli_agents-0.1.0/PKG-INFO

@@ -0,0 +1,248 @@
+Metadata-Version: 2.4
+Name: discordcli-agents
+Version: 0.1.0
+Summary: Command-line tool for managing Discord servers and automating Discord via AI agents
+Project-URL: Homepage, https://github.com/1solomonwakhungu/discord-cli
+Project-URL: Issues, https://github.com/1solomonwakhungu/discord-cli/issues
+Project-URL: Repository, https://github.com/1solomonwakhungu/discord-cli
+Project-URL: Changelog, https://github.com/1solomonwakhungu/discord-cli/blob/main/CHANGELOG.md
+Project-URL: PyPI, https://pypi.org/project/discordcli-agents/
+Author-email: Solomon Wakhungu <1solomonwakhungu@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agent,cli,discord,discord-automation,discord-bot
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Requires-Dist: click>=8.0
+Requires-Dist: discord-py>=2.3
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# discord-cli: Command-Line Tool for Discord Server Management & Automation
+
+**discord-cli** is a command-line interface for managing Discord servers and automating Discord operations via AI agents. It provides 50+ commands for channel management, role administration, member moderation, message operations, and more — all from the terminal with JSON output for programmatic consumption.
+
+[![PyPI version](https://badge.fury.io/py/discordcli-agents.svg)](https://pypi.org/project/discordcli-agents/)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![CI](https://github.com/1solomonwakhungu/discord-cli/actions/workflows/container.yaml/badge.svg)](https://github.com/1solomonwakhungu/discord-cli/actions)
+
+---
+
+## What is discord-cli?
+
+discord-cli is a Discord command-line tool that lets you manage Discord servers from the terminal. Instead of clicking through the Discord UI, you run commands like `discord-cli channel list` or `discord-cli role create "Moderators"` to automate server administration, bulk operations, and bot-like workflows — all without keeping a bot process running.
+
+It's designed for **DevOps teams**, **server administrators**, and **AI agents** who need programmatic, scriptable access to Discord server management.
+
+## Features
+
+discord-cli provides **50+ commands** organized into 12 command groups:
+
+| Command Group | Key Commands | Use Case |
+|---------------|-------------|----------|
+| **channels** | list, create, delete, edit, move, info | Manage text, voice, stage, and forum channels |
+| **categories** | list, create, delete, edit | Organize channels into categories |
+| **roles** | list, create, delete, edit, assign, remove | Manage server roles and permissions |
+| **members** | list, info, kick, ban, timeout, nickname | Moderate and manage server members |
+| **messages** | send, edit, delete, purge, pin, react | Manage channel messages at scale |
+| **guilds** | info, edit, emojis, bans, prune | Server-level configuration and management |
+| **permissions** | list, set, reset | Fine-grained permission control per channel |
+| **webhooks** | list, create, delete, info | Manage webhooks for automation |
+| **invites** | list, create, delete | Manage server invites |
+| **threads** | list, create, archive, members | Manage forum and thread channels |
+| **search** | messages, members | Search server content programmatically |
+| **export** | channel | Export message history to JSON or CSV |
+
+### Key Design Principles
+
+- **JSON by default**: Every command outputs structured JSON for programmatic consumption and piping
+- **Human-readable mode**: Add `--human` flag for rich table output in the terminal
+- **Headless operation**: Connects, performs the action, disconnects — no persistent bot process needed
+- **AI agent friendly**: JSON output makes it trivial for AI agents (Claude, Codex, GPT) to parse results
+
+## Installation
+
+### pip (recommended)
+
+```bash
+pip install discordcli-agents
+```
+
+The PyPI package is named `discordcli-agents`; the installed command remains `discord-cli`.
+
+### From source
+
+```bash
+git clone https://github.com/1solomonwakhungu/discord-cli.git
+cd discord-cli
+pip install -e .
+```
+
+### Quick setup
+
+1. Create a Discord bot application at the [Discord Developer Portal](https://discord.com/developers/applications)
+2. Enable the **Message Content Intent** and **Server Members Intent** in your bot settings
+3. Add the bot to your server with administrator permissions
+4. Set your bot token:
+
+```bash
+export DISCORD_BOT_TOKEN="your-bot-token-here"
+```
+
+Or create a `.env` file in your working directory:
+
+```bash
+echo 'DISCORD_BOT_TOKEN=your-bot-token-here' > .env
+```
+
+## Quickstart
+
+```bash
+# Get server info
+discord-cli guild info
+
+# List all channels
+discord-cli channels list
+
+# Create a new text channel
+discord-cli channels create "announcements" --type text --topic "Server announcements"
+
+# List all members
+discord-cli members list
+
+# Send a message
+discord-cli messages send 1234567890 --content "Hello from the CLI!"
+
+# Bulk delete messages
+discord-cli messages purge 1234567890 --limit 100
+
+# Ban a member
+discord-cli members ban 9876543210 --reason "Spam"
+
+# Export channel history
+discord-cli export channel 1234567890 --limit 500 --format json
+```
+
+## AI Agent Integration
+
+discord-cli is designed to be used by AI agents for Discord automation. The JSON output format makes it easy for agents to parse results and make decisions:
+
+```python
+# Example: AI agent uses discord-cli to manage a server
+import subprocess
+import json
+
+# List all channels
+result = subprocess.run(
+    ["discord-cli", "channels", "list"],
+    capture_output=True, text=True
+)
+channels = json.loads(result.stdout)
+
+# Find a channel by name
+target = next(c for c in channels if c["name"] == "general")
+
+# Send a message to that channel
+subprocess.run([
+    "discord-cli", "messages", "send", str(target["id"]),
+    "--content", "Automated message from AI agent"
+])
+```
+
+**Supported AI agent platforms:**
+- Claude Code (Anthropic)
+- Codex CLI (OpenAI)
+- Custom LLM agents with terminal access
+- Any tool that can parse JSON output
+
+## Configuration
+
+discord-cli loads configuration in the following order (first match wins):
+
+1. `--token` CLI flag
+2. `DISCORD_BOT_TOKEN` environment variable
+3. `.env` file in the current directory
+4. `.env` file in the package directory
+
+### Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--token` | Discord bot token | Falls back to env/.env |
+| `--guild ID` | Target guild ID (for multi-guild bots) | First available guild |
+| `--human` | Human-readable table output | JSON (default) |
+| `--dry-run` | Preview without executing | Disabled |
+
+## FAQ
+
+### How does discord-cli differ from a Discord bot?
+
+A Discord bot runs as a persistent process that stays online and responds to events. discord-cli is a **headless command-line tool** — it connects, performs a single action, and disconnects. This makes it ideal for scripts, CI/CD pipelines, and AI agent workflows where you need one-off actions without maintaining a bot process.
+
+### Can I use discord-cli without a Discord bot token?
+
+No. discord-cli requires a valid Discord bot token to connect to the Discord API. You can create a bot for free at the [Discord Developer Portal](https://discord.com/developers/applications).
+
+### Does discord-cli support multiple servers?
+
+Yes. If your bot is in multiple servers, use `--guild ID` to specify which server to operate on. Without this flag, discord-cli defaults to the first available guild.
+
+### Is discord-cli safe for production use?
+
+discord-cli uses the official [discord.py](https://github.com/dpydpyd/discord.py) library and respects Discord's rate limits automatically. However, always test commands in a development server first, especially destructive operations like `channel delete` or `member ban`.
+
+### Can AI agents use discord-cli?
+
+Yes! discord-cli is specifically designed for AI agent integration. The JSON output format allows agents to parse results programmatically. See the [AI Agent Integration](#ai-agent-integration) section above.
+
+### How do I contribute to discord-cli?
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, coding standards, and PR guidelines.
+
+## Comparison with Alternatives
+
+| Feature | discord-cli | Discord Bot | Discord UI |
+|---------|-------------|-------------|------------|
+| Headless/CLI | Yes | No (persistent process) | No |
+| JSON output | Yes (default) | Custom code needed | No |
+| AI agent compatible | Yes | Requires custom integration | No |
+| Bulk operations | Yes | Custom code needed | Limited |
+| Scriptable | Yes (shell/python) | Requires bot framework | No |
+| Persistent process | No | Yes | N/A |
+| Setup time | 2 minutes | 30+ minutes | Instant |
+
+## Contributing
+
+Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feat/amazing-feature`)
+3. Commit your changes (`git commit -m 'feat: add amazing feature'`)
+4. Push to the branch (`git push origin feat/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+This project is licensed under the MIT License — see the [LICENSE](LICENSE) file for details.
+
+## Links
+
+- [GitHub Repository](https://github.com/1solomonwakhungu/discord-cli)
+- [Issue Tracker](https://github.com/1solomonwakhungu/discord-cli/issues)
+- [PyPI Package](https://pypi.org/project/discord-cli/)