Add comprehensive CLI tool with interactive shell mode
- Created miku-cli.py: Full-featured CLI for Miku bot API - Added interactive shell mode for continuous command execution - Implemented all API endpoints: status, mood, autonomous, DM, blocking, profile pictures - Consistent hyphenated command naming across shell and regular modes - Created API_REFERENCE.md: Complete API endpoint documentation - Created CLI_README.md: User guide with examples and usage instructions - Error handling and user-friendly output formatting
This commit is contained in:
460
API_REFERENCE.md
Normal file
460
API_REFERENCE.md
Normal file
@@ -0,0 +1,460 @@
|
||||
# Miku Discord Bot API Reference
|
||||
|
||||
The Miku bot exposes a FastAPI REST API on port 3939 for controlling and monitoring the bot.
|
||||
|
||||
## Base URL
|
||||
```
|
||||
http://localhost:3939
|
||||
```
|
||||
|
||||
## API Endpoints
|
||||
|
||||
### 📊 Status & Information
|
||||
|
||||
#### `GET /status`
|
||||
Get current bot status and overview.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"status": "online",
|
||||
"mood": "neutral",
|
||||
"servers": 2,
|
||||
"active_schedulers": 2,
|
||||
"server_moods": {
|
||||
"123456789": "bubbly",
|
||||
"987654321": "excited"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### `GET /logs`
|
||||
Get the last 100 lines of bot logs.
|
||||
|
||||
**Response:** Plain text log output
|
||||
|
||||
#### `GET /prompt`
|
||||
Get the last full prompt sent to the LLM.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"prompt": "Last prompt text..."
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 😊 Mood Management
|
||||
|
||||
#### `GET /mood`
|
||||
Get current DM mood.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"mood": "neutral",
|
||||
"description": "Mood description text..."
|
||||
}
|
||||
```
|
||||
|
||||
#### `POST /mood`
|
||||
Set DM mood.
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"mood": "bubbly"
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"new_mood": "bubbly"
|
||||
}
|
||||
```
|
||||
|
||||
#### `POST /mood/reset`
|
||||
Reset DM mood to neutral.
|
||||
|
||||
#### `POST /mood/calm`
|
||||
Calm Miku down (set to neutral).
|
||||
|
||||
#### `GET /servers/{guild_id}/mood`
|
||||
Get mood for specific server.
|
||||
|
||||
#### `POST /servers/{guild_id}/mood`
|
||||
Set mood for specific server.
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"mood": "excited"
|
||||
}
|
||||
```
|
||||
|
||||
#### `POST /servers/{guild_id}/mood/reset`
|
||||
Reset server mood to neutral.
|
||||
|
||||
#### `GET /servers/{guild_id}/mood/state`
|
||||
Get complete mood state for server.
|
||||
|
||||
#### `GET /moods/available`
|
||||
List all available moods.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"moods": {
|
||||
"neutral": "😊",
|
||||
"bubbly": "🥰",
|
||||
"excited": "🤩",
|
||||
"sleepy": "😴",
|
||||
...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 😴 Sleep Management
|
||||
|
||||
#### `POST /sleep`
|
||||
Force Miku to sleep.
|
||||
|
||||
#### `POST /wake`
|
||||
Wake Miku up.
|
||||
|
||||
#### `POST /bedtime?guild_id={guild_id}`
|
||||
Send bedtime reminder. If `guild_id` is provided, sends only to that server.
|
||||
|
||||
---
|
||||
|
||||
### 🤖 Autonomous Actions
|
||||
|
||||
#### `POST /autonomous/general?guild_id={guild_id}`
|
||||
Trigger autonomous general message.
|
||||
|
||||
#### `POST /autonomous/engage?guild_id={guild_id}`
|
||||
Trigger autonomous user engagement.
|
||||
|
||||
#### `POST /autonomous/tweet?guild_id={guild_id}`
|
||||
Trigger autonomous tweet sharing.
|
||||
|
||||
#### `POST /autonomous/reaction?guild_id={guild_id}`
|
||||
Trigger autonomous reaction to a message.
|
||||
|
||||
#### `POST /autonomous/custom?guild_id={guild_id}`
|
||||
Send custom autonomous message.
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"prompt": "Say something funny about cats"
|
||||
}
|
||||
```
|
||||
|
||||
#### `GET /autonomous/stats`
|
||||
Get autonomous engine statistics for all servers.
|
||||
|
||||
**Response:** Detailed stats including message counts, activity, mood profiles, etc.
|
||||
|
||||
#### `GET /autonomous/v2/stats/{guild_id}`
|
||||
Get autonomous V2 stats for specific server.
|
||||
|
||||
#### `GET /autonomous/v2/check/{guild_id}`
|
||||
Check if autonomous action should happen for server.
|
||||
|
||||
#### `GET /autonomous/v2/status`
|
||||
Get autonomous V2 status across all servers.
|
||||
|
||||
---
|
||||
|
||||
### 🌐 Server Management
|
||||
|
||||
#### `GET /servers`
|
||||
List all configured servers.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"servers": [
|
||||
{
|
||||
"guild_id": 123456789,
|
||||
"guild_name": "My Server",
|
||||
"autonomous_channel_id": 987654321,
|
||||
"autonomous_channel_name": "general",
|
||||
"bedtime_channel_ids": [111111111],
|
||||
"enabled_features": ["autonomous", "bedtime"]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### `POST /servers`
|
||||
Add a new server configuration.
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"guild_id": 123456789,
|
||||
"guild_name": "My Server",
|
||||
"autonomous_channel_id": 987654321,
|
||||
"autonomous_channel_name": "general",
|
||||
"bedtime_channel_ids": [111111111],
|
||||
"enabled_features": ["autonomous", "bedtime"]
|
||||
}
|
||||
```
|
||||
|
||||
#### `DELETE /servers/{guild_id}`
|
||||
Remove server configuration.
|
||||
|
||||
#### `PUT /servers/{guild_id}`
|
||||
Update server configuration.
|
||||
|
||||
#### `POST /servers/{guild_id}/bedtime-range`
|
||||
Set bedtime range for server.
|
||||
|
||||
#### `POST /servers/{guild_id}/memory`
|
||||
Update server memory/context.
|
||||
|
||||
#### `GET /servers/{guild_id}/memory`
|
||||
Get server memory/context.
|
||||
|
||||
#### `POST /servers/repair`
|
||||
Repair server configurations.
|
||||
|
||||
---
|
||||
|
||||
### 💬 DM Management
|
||||
|
||||
#### `GET /dms/users`
|
||||
List all users with DM history.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"users": [
|
||||
{
|
||||
"user_id": "123456789",
|
||||
"username": "User#1234",
|
||||
"total_messages": 42,
|
||||
"last_message_date": "2025-12-10T12:34:56",
|
||||
"is_blocked": false
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### `GET /dms/users/{user_id}`
|
||||
Get details for specific user.
|
||||
|
||||
#### `GET /dms/users/{user_id}/conversations`
|
||||
Get conversation history for user.
|
||||
|
||||
#### `GET /dms/users/{user_id}/search?query={query}`
|
||||
Search user's DM history.
|
||||
|
||||
#### `GET /dms/users/{user_id}/export`
|
||||
Export user's DM history.
|
||||
|
||||
#### `DELETE /dms/users/{user_id}`
|
||||
Delete user's DM data.
|
||||
|
||||
#### `POST /dm/{user_id}/custom`
|
||||
Send custom DM (LLM-generated).
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"prompt": "Ask about their day"
|
||||
}
|
||||
```
|
||||
|
||||
#### `POST /dm/{user_id}/manual`
|
||||
Send manual DM (direct message).
|
||||
|
||||
**Form Data:**
|
||||
- `message`: Message text
|
||||
|
||||
#### `GET /dms/blocked-users`
|
||||
List blocked users.
|
||||
|
||||
#### `POST /dms/users/{user_id}/block`
|
||||
Block a user.
|
||||
|
||||
#### `POST /dms/users/{user_id}/unblock`
|
||||
Unblock a user.
|
||||
|
||||
#### `POST /dms/users/{user_id}/conversations/{conversation_id}/delete`
|
||||
Delete specific conversation.
|
||||
|
||||
#### `POST /dms/users/{user_id}/conversations/delete-all`
|
||||
Delete all conversations for user.
|
||||
|
||||
#### `POST /dms/users/{user_id}/delete-completely`
|
||||
Completely delete user data.
|
||||
|
||||
---
|
||||
|
||||
### 📊 DM Analysis
|
||||
|
||||
#### `POST /dms/analysis/run`
|
||||
Run analysis on all DM conversations.
|
||||
|
||||
#### `POST /dms/users/{user_id}/analyze`
|
||||
Analyze specific user's DMs.
|
||||
|
||||
#### `GET /dms/analysis/reports`
|
||||
Get all analysis reports.
|
||||
|
||||
#### `GET /dms/analysis/reports/{user_id}`
|
||||
Get analysis report for specific user.
|
||||
|
||||
---
|
||||
|
||||
### 🖼️ Profile Picture Management
|
||||
|
||||
#### `POST /profile-picture/change?guild_id={guild_id}`
|
||||
Change profile picture. Optionally upload custom image.
|
||||
|
||||
**Form Data:**
|
||||
- `file`: Image file (optional)
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"message": "Profile picture changed successfully",
|
||||
"source": "danbooru",
|
||||
"metadata": {
|
||||
"url": "https://...",
|
||||
"tags": ["hatsune_miku", "...]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### `GET /profile-picture/metadata`
|
||||
Get current profile picture metadata.
|
||||
|
||||
#### `POST /profile-picture/restore-fallback`
|
||||
Restore original fallback profile picture.
|
||||
|
||||
---
|
||||
|
||||
### 🎨 Role Color Management
|
||||
|
||||
#### `POST /role-color/custom`
|
||||
Set custom role color.
|
||||
|
||||
**Form Data:**
|
||||
- `hex_color`: Hex color code (e.g., "#FF0000")
|
||||
|
||||
#### `POST /role-color/reset-fallback`
|
||||
Reset role color to fallback (#86cecb).
|
||||
|
||||
---
|
||||
|
||||
### 💬 Conversation Management
|
||||
|
||||
#### `GET /conversation/{user_id}`
|
||||
Get conversation history for user.
|
||||
|
||||
#### `POST /conversation/reset`
|
||||
Reset conversation history.
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"user_id": "123456789"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 📨 Manual Messaging
|
||||
|
||||
#### `POST /manual/send`
|
||||
Send manual message to channel.
|
||||
|
||||
**Form Data:**
|
||||
- `message`: Message text
|
||||
- `channel_id`: Channel ID
|
||||
- `files`: Files to attach (optional, multiple)
|
||||
|
||||
---
|
||||
|
||||
### 🎁 Figurine Notifications
|
||||
|
||||
#### `GET /figurines/subscribers`
|
||||
List figurine subscribers.
|
||||
|
||||
#### `POST /figurines/subscribers`
|
||||
Add figurine subscriber.
|
||||
|
||||
#### `DELETE /figurines/subscribers/{user_id}`
|
||||
Remove figurine subscriber.
|
||||
|
||||
#### `POST /figurines/send_now`
|
||||
Send figurine notification to all subscribers.
|
||||
|
||||
#### `POST /figurines/send_to_user`
|
||||
Send figurine notification to specific user.
|
||||
|
||||
---
|
||||
|
||||
### 🖼️ Image Generation
|
||||
|
||||
#### `POST /image/generate`
|
||||
Generate image using image generation service.
|
||||
|
||||
#### `GET /image/status`
|
||||
Get image generation service status.
|
||||
|
||||
#### `POST /image/test-detection`
|
||||
Test face detection on uploaded image.
|
||||
|
||||
---
|
||||
|
||||
### 😀 Message Reactions
|
||||
|
||||
#### `POST /messages/react`
|
||||
Add reaction to a message.
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"channel_id": "123456789",
|
||||
"message_id": "987654321",
|
||||
"emoji": "😊"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Responses
|
||||
|
||||
All endpoints return errors in the following format:
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "error",
|
||||
"message": "Error description"
|
||||
}
|
||||
```
|
||||
|
||||
HTTP status codes:
|
||||
- `200` - Success
|
||||
- `400` - Bad request
|
||||
- `404` - Not found
|
||||
- `500` - Internal server error
|
||||
|
||||
## Authentication
|
||||
|
||||
Currently, the API does not require authentication. It's designed to run on localhost within a Docker network.
|
||||
|
||||
## Rate Limiting
|
||||
|
||||
No rate limiting is currently implemented.
|
||||
Reference in New Issue
Block a user