# Commands Reference

This guide covers all available commands in PlayHours, their usage, permissions, and examples.

## 📋 Command Overview

All PlayHours commands use the `/hours` root command. Permission checks are applied automatically.

### Permission Requirements

| Permission | Level | Description |
|------------|-------|-------------|
| `playhours.view` | Ops ≥1 | Read-only access to status |
| `playhours.admin` | Ops ≥2 | Full administrative access |
| `playhours.exempt` | Ops ≥2 | Bypass all schedule restrictions |

## 🔍 Status Commands

### `/hours status`

Shows current server status and schedule information.

**Permission:** `playhours.view` (ops ≥1)

**Output Example:**
```
Mode: NORMAL. Server open. Next close: 10:00 PM. Next open: Monday at 9:00 AM.
Today's periods: 09:00 AM-06:00 PM, 11:00 PM-01:00 AM
```

**Information Displayed:**
- Current force mode
- Server open/closed status
- Next closing time (if open)
- Next opening time (if closed)
- Today's schedule periods

## 🔧 Force Mode Commands

### `/hours force normal`
### `/hours force open`
### `/hours force close`

Override the normal schedule enforcement.

**Permission:** `playhours.admin` (ops ≥2)

**Modes:**
- `normal` - Follow configured schedule
- `open` - Always allow access (24/7)
- `close` - Always deny access (maintenance mode)

**Examples:**
```
/hours force open          # Enable 24/7 access
/hours force close         # Maintenance mode
/hours force normal        # Return to normal schedule
```

**Notes:**
- Force modes override schedule but not blacklist
- Exempt players can still join in FORCE_CLOSED mode
- Changes take effect immediately

## 🔄 Configuration Commands

### `/hours reload`

Reloads configuration from `config/playhours.toml` without restarting the server.

**Permission:** `playhours.admin` (ops ≥2)

**Usage:**
```
/hours reload
```

**What it does:**
- Reloads all configuration settings
- Rebuilds schedule cache
- Reloads message translations
- Applies changes immediately

**When to use:**
- After editing `config/playhours.toml`
- After changing timezone settings
- After modifying schedule configuration

## ⚙️ Settings Commands

### `/hours set timezone <timezone>`

Change the server timezone.

**Permission:** `playhours.admin` (ops ≥2)

**Usage:**
```
/hours set timezone America/New_York
/hours set timezone Europe/London
/hours set timezone Asia/Tokyo
```

**Valid Timezones:**
- `America/New_York` (Eastern Time)
- `America/Chicago` (Central Time)
- `America/Denver` (Mountain Time)
- `America/Los_Angeles` (Pacific Time)
- `Europe/London` (GMT/BST)
- `Europe/Paris` (CET/CEST)
- `Asia/Tokyo` (JST)
- `Australia/Sydney` (AEST/AEDT)

### `/hours set threshold <minutes>`

Set the closing threshold in minutes.

**Permission:** `playhours.admin` (ops ≥2)

**Usage:**
```
/hours set threshold 20
```

**Effect:**
- Denies new logins X minutes before close
- Existing players can stay connected
- Exempt players can bypass if configured

### `/hours set warnings <minutes...>`

Configure warning broadcast times.

**Permission:** `playhours.admin` (ops ≥2)

**Usage:**
```
/hours set warnings 30 15 10 5 1
```

**Examples:**
- `15 10 5 1` - Warn at 15, 10, 5, and 1 minutes before close
- `30 15 5` - Warn at 30, 15, and 5 minutes before close
- `60 30 15 10 5 1` - Extended warning sequence

### `/hours set countdown <seconds>`

Set countdown duration before closing.

**Permission:** `playhours.admin` (ops ≥2)

**Usage:**
```
/hours set countdown 10
```

**Range:** 0-60 seconds (0 = disabled)

**Effect:**
- Sends "Closing in Xs" messages every second
- Only active during the last X seconds before close
- Provides final warning to players

### `/hours set exempt_bypass_schedule <true|false>`
### `/hours set exempt_bypass_threshold <true|false>`

Control exempt player behavior.

**Permission:** `playhours.admin` (ops ≥2)

**Usage:**
```
/hours set exempt_bypass_schedule true
/hours set exempt_bypass_threshold false
```

**Settings:**
- `exempt_bypass_schedule` - Allow exempt players to join when closed
- `exempt_bypass_threshold` - Allow exempt players during threshold

## 📅 Schedule Commands

### `/hours set default periods add "<time_range>"`
### `/hours set default periods clear`

Manage default schedule periods.

**Permission:** `playhours.admin` (ops ≥2)

**Usage:**
```
/hours set default periods add "09:00 AM-06:00 PM"
/hours set default periods add "11:00 PM-01:00 AM"
/hours set default periods clear
```

**Time Format:** 12-hour AM/PM format with quotes

**Examples:**
```
/hours set default periods add "09:00 AM-06:00 PM"
/hours set default periods add "10:00 PM-02:00 AM"  # Midnight span
/hours set default periods clear                     # Remove all periods
```

### `/hours set day <day> periods add "<time_range>"`
### `/hours set day <day> periods clear`

Manage per-day schedule periods.

**Permission:** `playhours.admin` (ops ≥2)

**Usage:**
```
/hours set day mon periods add "09:00 AM-06:00 PM"
/hours set day fri periods add "11:00 PM-01:00 AM"
/hours set day tue periods clear
```

**Day Names:** `mon`, `tue`, `wed`, `thu`, `fri`, `sat`, `sun`

**Examples:**
```
/hours set day mon periods add "09:00 AM-06:00 PM"
/hours set day fri periods add "11:00 PM-01:00 AM"
/hours set day sat periods add "02:00 PM-11:59 PM"
/hours set day sun periods clear
```

## 📅 Exception Commands

### `/hours exceptions add-open "<date_time_range>"`
### `/hours exceptions add-closed "<date>"`
### `/hours exceptions clear`

Manage date exceptions.

**Permission:** `playhours.admin` (ops ≥2)

**Usage:**
```
/hours exceptions add-open "2025-12-31 08:00 PM-11:59 PM"
/hours exceptions add-closed "2025-12-25"
/hours exceptions clear
```

**Date Formats:**
- **Open dates:** `YYYY-MM-DD hh:mm AM-hh:mm PM`
- **Closed dates:** `YYYY-MM-DD`

**Examples:**
```
/hours exceptions add-open "2025-12-31 08:00 PM-11:59 PM"  # New Year's Eve
/hours exceptions add-closed "2025-12-25"                  # Christmas Day
/hours exceptions add-open "2025-07-04 12:00 PM-11:59 PM"  # Independence Day
/hours exceptions clear                                     # Remove all exceptions
```

## 👥 List Commands

### `/hours lists whitelist toggle <player>`
### `/hours lists blacklist toggle <player>`

Toggle players in/out of lists.

**Permission:** `playhours.admin` (ops ≥2)

**Usage:**
```
/hours lists whitelist toggle PlayerName
/hours lists blacklist toggle PlayerName
```

**Behavior:**
- Automatically enables the list if not already enabled
- Case-insensitive player name matching
- Toggle: Add if not present, remove if present

**Examples:**
```
/hours lists whitelist toggle Steve
/hours lists blacklist toggle Griefer123
```

### `/hours lists whitelist enable`
### `/hours lists whitelist disable`
### `/hours lists blacklist enable`
### `/hours lists blacklist disable`

Enable or disable lists.

**Permission:** `playhours.admin` (ops ≥2)

**Usage:**
```
/hours lists whitelist enable
/hours lists blacklist disable
```

## 📢 MOTD Commands

### `/hours motd toggle`

Enable or disable MOTD schedule display.

**Permission:** `playhours.admin` (ops ≥2)

**Usage:**
```
/hours motd toggle
```

**Effect:**
- Toggles MOTD feature on/off
- Changes take effect immediately
- Server list will show/hide schedule information

### `/hours motd status`

View current MOTD settings.

**Permission:** `playhours.admin` (ops ≥2)

**Usage:**
```
/hours motd status
```

**Output:**
- MOTD enabled/disabled status
- Current MOTD configuration
- Update frequency settings

## 💬 Message Commands

### `/hours messages reload`

Reload message translations.

**Permission:** `playhours.admin` (ops ≥2)

**Usage:**
```
/hours messages reload
```

**Effect:**
- Reloads message translations from language files
- Applies any config overrides
- Updates all player-facing messages

## 🔧 Advanced Commands

### Command Chaining

Some commands support chaining for efficiency:

```
/hours set day mon periods add "09:00 AM-06:00 PM"
/hours set day tue periods add "09:00 AM-06:00 PM"
/hours set day wed periods add "09:00 AM-06:00 PM"
```

### Batch Operations

Use multiple commands for complex setups:

```
/hours set default periods clear
/hours set day mon periods add "09:00 AM-06:00 PM"
/hours set day fri periods add "11:00 PM-01:00 AM"
/hours exceptions add-closed "2025-12-25"
```

## 🚨 Error Handling

### Common Errors

**Permission Denied:**
```
You do not have permission to use this command
```
**Solution:** Check your permission level or LuckPerms configuration

**Invalid Time Format:**
```
Invalid time range. Use: hh:mm AM-hh:mm PM
```
**Solution:** Use proper 12-hour AM/PM format with quotes

**Config Not Ready:**
```
PlayHours config not ready yet. Try again in a moment.
```
**Solution:** Wait for server startup to complete

### Troubleshooting

1. **Check permissions:** Ensure you have the required permission level
2. **Verify format:** Use correct time format and quotes
3. **Wait for startup:** Allow server to fully initialize
4. **Check logs:** Look for error messages in server logs

## 📚 Command Examples

### Basic Server Setup

```bash
# Set timezone
/hours set timezone America/New_York

# Configure default hours
/hours set default periods add "09:00 AM-06:00 PM"

# Set weekend hours
/hours set day sat periods add "02:00 PM-11:59 PM"
/hours set day sun periods add "02:00 PM-10:00 PM"

# Configure warnings
/hours set warnings 15 10 5 1
/hours set countdown 5
```

### Holiday Configuration

```bash
# Add holiday closures
/hours exceptions add-closed "2025-12-25"
/hours exceptions add-closed "2026-01-01"

# Add special event hours
/hours exceptions add-open "2025-12-31 08:00 PM-11:59 PM"
```

### Maintenance Mode

```bash
# Enter maintenance mode
/hours force close

# Exit maintenance mode
/hours force normal
```

### Player Management

```bash
# Add players to whitelist
/hours lists whitelist toggle PlayerName

# Add players to blacklist
/hours lists blacklist toggle Griefer123

# Enable whitelist
/hours lists whitelist enable
```

## 📚 Related Documentation

- **[Configuration Guide](CONFIGURATION.md)** - File-based configuration
- **[Features Overview](FEATURES.md)** - How features work
- **[Permissions System](PERMISSIONS.md)** - Permission details
- **[Usage Examples](EXAMPLES.md)** - Real-world scenarios

---

*For configuration file options, see the [Configuration Guide](CONFIGURATION.md).*