miku-discord/CLI_README.md

Miku CLI - Command Line Interface

A powerful command-line interface for controlling and monitoring the Miku Discord bot.

Installation

1. Make the script executable:

chmod +x miku-cli.py

2. Install dependencies:

pip install requests

3. (Optional) Create a symlink for easier access:

sudo ln -s $(pwd)/miku-cli.py /usr/local/bin/miku

Quick Start

# Check bot status
./miku-cli.py status

# Get current mood
./miku-cli.py mood --get

# Set mood to bubbly
./miku-cli.py mood --set bubbly

# List available moods
./miku-cli.py mood --list

# Trigger autonomous message
./miku-cli.py autonomous general

# List servers
./miku-cli.py servers

# View logs
./miku-cli.py logs

Configuration

By default, the CLI connects to http://localhost:3939. To use a different URL:

./miku-cli.py --url http://your-server:3939 status

Commands

Status & Information

# Get bot status
./miku-cli.py status

# View recent logs
./miku-cli.py logs

# Get last LLM prompt
./miku-cli.py prompt

Mood Management

# Get current DM mood
./miku-cli.py mood --get

# Get server mood
./miku-cli.py mood --get --server 123456789

# Set mood
./miku-cli.py mood --set bubbly
./miku-cli.py mood --set excited --server 123456789

# Reset mood to neutral
./miku-cli.py mood --reset
./miku-cli.py mood --reset --server 123456789

# List available moods
./miku-cli.py mood --list

Sleep Management

# Put Miku to sleep
./miku-cli.py sleep

# Wake Miku up
./miku-cli.py wake

# Send bedtime reminder
./miku-cli.py bedtime
./miku-cli.py bedtime --server 123456789

Autonomous Actions

# Trigger general autonomous message
./miku-cli.py autonomous general
./miku-cli.py autonomous general --server 123456789

# Trigger user engagement
./miku-cli.py autonomous engage
./miku-cli.py autonomous engage --server 123456789

# Share a tweet
./miku-cli.py autonomous tweet
./miku-cli.py autonomous tweet --server 123456789

# Trigger reaction
./miku-cli.py autonomous reaction
./miku-cli.py autonomous reaction --server 123456789

# Send custom autonomous message
./miku-cli.py autonomous custom --prompt "Tell a joke about programming"
./miku-cli.py autonomous custom --prompt "Say hello" --server 123456789

# Get autonomous stats
./miku-cli.py autonomous stats

Server Management

# List all configured servers
./miku-cli.py servers

DM Management

# List users with DM history
./miku-cli.py dm-users

# Send custom DM (LLM-generated)
./miku-cli.py dm-custom 123456789 "Ask them how their day was"

# Send manual DM (direct message)
./miku-cli.py dm-manual 123456789 "Hello! How are you?"

# Block a user
./miku-cli.py block 123456789

# Unblock a user
./miku-cli.py unblock 123456789

# List blocked users
./miku-cli.py blocked-users

Profile Picture

# Change profile picture (search Danbooru based on mood)
./miku-cli.py change-pfp

# Change to custom image
./miku-cli.py change-pfp --image /path/to/image.png

# Change for specific server mood
./miku-cli.py change-pfp --server 123456789

# Get current profile picture metadata
./miku-cli.py pfp-metadata

Conversation Management

# Reset conversation history for a user
./miku-cli.py reset-conversation 123456789

Manual Messaging

# Send message to channel
./miku-cli.py send 987654321 "Hello everyone!"

# Send message with file attachments
./miku-cli.py send 987654321 "Check this out!" --files image.png document.pdf

Available Moods

• 😊 neutral
• 🥰 bubbly
• 🤩 excited
• 😴 sleepy
• 😡 angry
• 🙄 irritated
• 😏 flirty
• 💕 romantic
• 🤔 curious
• 😳 shy
• 🤪 silly
• 😢 melancholy
• 😤 serious
• 💤 asleep

Examples

Morning Routine

# Wake up Miku
./miku-cli.py wake

# Set a bubbly mood
./miku-cli.py mood --set bubbly

# Send a general message to all servers
./miku-cli.py autonomous general

# Change profile picture to match mood
./miku-cli.py change-pfp

Server-Specific Control

# Get server list
./miku-cli.py servers

# Set mood for specific server
./miku-cli.py mood --set excited --server 123456789

# Trigger engagement on that server
./miku-cli.py autonomous engage --server 123456789

DM Interaction

# List users
./miku-cli.py dm-users

# Send custom message
./miku-cli.py dm-custom 123456789 "Ask them about their favorite anime"

# If user is spamming, block them
./miku-cli.py block 123456789

Monitoring

# Check status
./miku-cli.py status

# View logs
./miku-cli.py logs

# Get autonomous stats
./miku-cli.py autonomous stats

# Check last prompt
./miku-cli.py prompt

Output Format

The CLI uses emoji and colored output for better readability:

• ✅ Success messages
• ❌ Error messages
• 😊 Mood indicators
• 🌐 Server information
• 💬 DM information
• 📊 Statistics
• 🖼️ Media information

Scripting

The CLI is designed to be script-friendly:

#!/bin/bash

# Morning routine script
./miku-cli.py wake
./miku-cli.py mood --set bubbly
./miku-cli.py autonomous general

# Wait 5 minutes
sleep 300

# Engage users
./miku-cli.py autonomous engage

Error Handling

The CLI exits with status code 1 on errors and 0 on success, making it suitable for use in scripts:

if ./miku-cli.py mood --set bubbly; then
    echo "Mood set successfully"
else
    echo "Failed to set mood"
fi

API Reference

For complete API documentation, see API_REFERENCE.md.

Troubleshooting

Connection Refused

If you get "Connection refused" errors:

1. Check that the bot API is running on port 3939
2. Verify the URL with --url parameter
3. Check Docker container status: docker-compose ps

Permission Denied

Make the script executable:

chmod +x miku-cli.py

Import Errors

Install required dependencies:

pip install requests

Future Enhancements

Planned features:

• Configuration file support (~/.miku-cli.conf)
• Interactive mode
• Tab completion
• Color output control
• JSON output mode for scripting
• Batch operations
• Watch mode for real-time monitoring

Contributing

Feel free to extend the CLI with additional commands and features!