Metadata-Version: 2.4
Name: cmdop-bot
Version: 0.1.1
Summary: CMDOP Bot - Multi-channel bot integrations for remote machine access
Project-URL: Homepage, https://github.com/cmdop/cmdop-bot
Project-URL: Documentation, https://cmdop.com/docs/
Project-URL: Repository, https://github.com/cmdop/cmdop-bot
Project-URL: Issues, https://github.com/cmdop/cmdop-bot/issues
Author-email: CMDOP Team <team@cmdop.com>
License-Expression: MIT
Keywords: ai-agent,automation,bot,cmdop,discord,remote-access,slack,telegram
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: cmdop>=0.1.30
Requires-Dist: httpx>=0.28.0
Requires-Dist: pydantic>=2.10.0
Provides-Extra: all
Requires-Dist: aiogram>=3.4.0; extra == 'all'
Requires-Dist: discord-py>=2.3.0; extra == 'all'
Requires-Dist: slack-bolt>=1.18.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: discord
Requires-Dist: discord-py>=2.5.0; extra == 'discord'
Provides-Extra: slack
Requires-Dist: slack-bolt>=1.23.0; extra == 'slack'
Provides-Extra: telegram
Requires-Dist: aiogram>=3.20.0; extra == 'telegram'
Description-Content-Type: text/markdown

# CMDOP Bots

**Multi-channel bot integrations for remote machine access.**

Control your servers via Telegram, Discord, or Slack. Simple, reliable, open-source.

## Install

```bash
pip install cmdop-bot

# With Telegram support
pip install cmdop-bot[telegram]

# With Discord support
pip install cmdop-bot[discord]

# With Slack support
pip install cmdop-bot[slack]

# With all channels
pip install cmdop-bot[all]
```

## Quick Start

### Telegram Bot

```python
from cmdop_bots.channels.telegram import TelegramBot

bot = TelegramBot(
    token="YOUR_TELEGRAM_BOT_TOKEN",
    cmdop_api_key="YOUR_CMDOP_API_KEY",
    allowed_users=[123456789],  # Your Telegram user ID
    machine="my-server",  # Optional: target machine
)

bot.run()
```

### Discord Bot

```python
from cmdop_bots.channels.discord import DiscordBot

bot = DiscordBot(
    token="YOUR_DISCORD_BOT_TOKEN",
    cmdop_api_key="YOUR_CMDOP_API_KEY",
    guild_ids=[123456789],  # Optional: for faster command sync
)

bot.run()
```

### Slack App

```python
from cmdop_bots.channels.slack import SlackApp

app = SlackApp(
    bot_token="xoxb-YOUR-BOT-TOKEN",
    app_token="xapp-YOUR-APP-TOKEN",
    cmdop_api_key="YOUR_CMDOP_API_KEY",
)

app.run()
```

## Commands

| Channel | Command | Description |
|---------|---------|-------------|
| Telegram | `/shell <cmd>` | Execute shell command |
| Telegram | `/exec <cmd>` | Alias for /shell |
| Telegram | `/agent <task>` | Run AI agent task |
| Telegram | `/ls [path]` | List directory |
| Telegram | `/cat <path>` | Read file |
| Telegram | `/machine <host>` | Set target machine |
| Discord | `/shell <cmd>` | Execute shell command |
| Discord | `/agent <task>` | Run AI agent task |
| Discord | `/ls [path]` | List directory |
| Discord | `/cat <path>` | Read file |
| Discord | `/machine <host>` | Set target machine |
| Discord | `/status` | Show connection status |
| Slack | `/cmdop shell <cmd>` | Execute shell command |
| Slack | `/cmdop agent <task>` | Run AI agent task |
| Slack | `/cmdop ls [path]` | List directory |
| Slack | `/cmdop cat <path>` | Read file |
| Slack | `/cmdop machine <host>` | Set target machine |
| Slack | `/cmdop status` | Show connection status |

## Features

### Telegram
- MarkdownV2 formatting
- Code block syntax highlighting
- Typing indicators
- User allowlist

### Discord
- Slash commands
- Rich embeds
- Ephemeral messages for sensitive data
- Deferred responses for slow operations
- Guild-specific command sync

### Slack
- Socket Mode (no public webhooks needed)
- Block Kit messages
- Interactive buttons
- Slash command handling

## Handlers

Use handlers directly in your own bot:

```python
from cmdop_bots.handlers import ShellHandler, AgentHandler, FilesHandler

# Create handlers
shell = ShellHandler(cmdop_api_key="cmd_xxx", machine="my-server")
agent = AgentHandler(cmdop_api_key="cmd_xxx")
files = FilesHandler(cmdop_api_key="cmd_xxx")

# Use in your handler
async def handle_command(command, send):
    await shell.handle(command, send)

# Clean up
await shell.close()
await agent.close()
await files.close()
```

## Permissions

Control who can use your bot:

```python
from cmdop_bots import PermissionManager, PermissionLevel

pm = PermissionManager()

# Add admin (full access)
pm.add_admin("telegram:123456789")

# Grant execute permission
pm.grant("discord:987654321", machine="prod-server", level=PermissionLevel.EXECUTE)

# Use with bot
bot = TelegramBot(
    token="...",
    cmdop_api_key="...",
    permissions=pm,
)
```

## Architecture

```
+--------------+
|  Telegram    |
|  Discord     |------> CMDOP SDK ------> Your Servers
|  Slack       |
+--------------+
```

- **Simple**: Each bot is < 200 lines of code
- **Reliable**: Proper error handling, reconnection
- **Secure**: Permission system, user allowlists

## Development

```bash
# Clone repository
git clone https://github.com/cmdop/cmdop-bot
cd cmdop-bot

# Install dev dependencies
pip install -e ".[dev,all]"

# Run tests
pytest

# Type check
mypy cmdop_bots

# Lint
ruff check cmdop_bots
```

## Environment Variables

| Variable | Description | Required |
|----------|-------------|----------|
| `TELEGRAM_BOT_TOKEN` | Telegram bot token | For Telegram |
| `DISCORD_BOT_TOKEN` | Discord bot token | For Discord |
| `SLACK_BOT_TOKEN` | Slack bot token (xoxb-...) | For Slack |
| `SLACK_APP_TOKEN` | Slack app token (xapp-...) | For Slack |
| `CMDOP_API_KEY` | CMDOP API key (cmd_xxx) | Yes |
| `CMDOP_MACHINE` | Default target machine | No |
| `ALLOWED_USERS` | Comma-separated user IDs | No |

## Examples

See the `examples/` directory:
- `telegram_bot.py` - Full Telegram bot example
- `discord_bot.py` - Full Discord bot example
- `slack_app.py` - Full Slack app example
- `multi_channel.py` - Multi-channel hub example

## License

MIT
