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:
```bash
chmod +x miku-cli.py
```

2. Install dependencies:
```bash
pip install requests
```

3. (Optional) Create a symlink for easier access:
```bash
sudo ln -s $(pwd)/miku-cli.py /usr/local/bin/miku
```

## Quick Start

```bash
# 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:

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

## Commands

### Status & Information

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

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

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

### Mood Management

```bash
# 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

```bash
# 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

```bash
# 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

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

### DM Management

```bash
# 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

```bash
# 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

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

### Manual Messaging

```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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:

```bash
#!/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:

```bash
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](./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:
```bash
chmod +x miku-cli.py
```

### Import Errors
Install required dependencies:
```bash
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!