Skip to content

cli-usage.mdx

Latest commit

 

History

History
513 lines (377 loc) · 11.8 KB

cli-usage.mdx

File metadata and controls

513 lines (377 loc) · 11.8 KB
title CLI Usage
description Day-to-day Discord operations from your terminal

discli gives you full Discord control from the command line. Every command works in two modes: human-readable output by default, and structured JSON with --json for scripting and piping.

Identifier Resolution

Before diving into commands, understand how discli resolves Discord entities:

Prefix Resolves to Example
# Channel by name #general
@ User by name @alice
Raw number Any entity by ID 1234567890
Plain string Server by name "My Server"
Channel names with `#` and user names with `@` are matched case-insensitively across all servers your bot can see. When names collide, use the numeric ID instead.

Sending Messages

The most common operation. Send a message to any channel your bot has access to:

discli message send "#general" "Hello from the terminal!"
discli message send 1234567890 "Deploy complete. All systems green."
discli message send "#logs" "Here's today's report" --file ./report.csv
discli message send "#announcements" "New release!" \
  --embed-title "v2.1.0" \
  --embed-desc "Bug fixes and performance improvements"
discli message send "#announcements" "Check this out" \
  --embed-title "Status Update" \
  --embed-color 5865F2 \
  --embed-footer "Last updated today" \
  --embed-field "Service::Operational::true"

Reading Messages

Fetch recent messages, search by content, or grab a specific message by ID.

```bash # Last 10 messages (default) discli message list "#general"

Last 50 messages

discli message list "#general" --limit 50

Messages before a specific date

discli message list "#general" --before 2025-01-15

Messages after a specific date

discli message list "#general" --after 2025-01-01

</Tab>

<Tab title="Search">
```bash
# Search by content
discli message search "#support" "payment failed"

# Search by content + author
discli message search "#support" "refund" --author "alice#1234"

# Search with date range
discli message search "#general" "deploy" --after 2025-03-01 --limit 200
```bash # Get a specific message by ID discli message get "#general" 1234567890123456 ``` ```bash # Last 7 days of messages discli message history "#general" --days 7

Last 2 hours

discli message history "#general" --hours 2

Last 7 days, max 500 messages

discli message history "#general" --days 7 --limit 500

</Tab>
</Tabs>

## JSON Output and jq Piping

Add `--json` to any command to get structured JSON output. This is where discli becomes a scripting powerhouse.

```bash
# Get JSON output
discli --json message list "#general" --limit 5

[
  {
    "id": "1234567890",
    "author": "alice#1234",
    "content": "Hello everyone!",
    "timestamp": "2025-03-15T10:30:00",
    "attachments": [],
    "embeds": []
  }
]

Pipe to jq for filtering and transformation:

discli --json message list "#general" --limit 20 | jq '.[].content'
discli --json message list "#general" --limit 100 \
  | jq '[.[] | select(.attachments | length > 0)]'
discli --json message list "#general" --limit 100 \
  | jq '[.[].author] | unique'
discli --json message list "#general" --limit 100 \
  | jq 'group_by(.author) | map({author: .[0].author, count: length}) | sort_by(-.count)'
discli --json message list "#general" --limit 100 \
  | jq -r '.[] | [.timestamp, .author, .content] | @csv' > messages.csv

Replying and Editing

# Reply to a specific message
discli message reply "#general" 1234567890123456 "Thanks for the update!"

# Edit a message (must be your bot's message)
discli message edit "#general" 1234567890123456 "Updated content here"

# Delete a message (requires confirmation)
discli message delete "#general" 1234567890123456

# Bulk delete multiple messages by ID
discli -y message bulk-delete "#general" 111 222 333
Destructive commands like `message delete` prompt for confirmation. Pass `--yes` or `-y` to skip the prompt in scripts: `discli --yes message delete "#general" 1234567890`.

Channel Management

```bash # All channels across all servers discli channel list

Channels in a specific server

discli channel list --server "My Server"

JSON output for scripting

discli --json channel list --server "My Server" | jq '.[] | select(.type == "text")'

</Tab>

<Tab title="Create channels">
```bash
# Create a text channel
discli channel create "My Server" "new-channel"

# Create a voice channel
discli channel create "My Server" "voice-room" --type voice

# Create a category
discli channel create "My Server" "Project Alpha" --type category

# Create a forum channel
discli channel create "My Server" "feedback" --type forum --topic "Share your feedback"

# Create a forum post
discli channel forum-post "#feedback" "Feature Request" "Add dark mode support"
```bash # Edit a channel's topic and slowmode discli channel edit "#general" --topic "New topic" --slowmode 10 ``` ```bash # Set channel permissions for a role discli channel set-permissions "#general" "Members" \ --allow send_messages \ --deny manage_messages ``` ```bash # Get channel details discli channel info "#general"

JSON output

discli --json channel info "#general"


Output includes: ID, name, type, server, topic, and creation date.
</Tab>

<Tab title="Delete channels">
```bash
# Delete a channel (requires confirmation)
discli channel delete "#old-channel"

# Skip confirmation
discli --yes channel delete "#old-channel"

Member Operations

# List members in a server
discli member list "My Server"
discli member list "My Server" --limit 100

# Get member details (roles, join date, etc.)
discli member info "My Server" "@alice"
discli member info "My Server" 1234567890

# Kick a member (confirmation required)
discli member kick "My Server" "@spammer" --reason "Spam"

# Ban a member
discli member ban "My Server" "@troll" --reason "Repeated violations"

# Unban
discli member unban "My Server" "@reformed"

# Timeout a member for 1 hour (3600 seconds)
discli -y member timeout "My Server" "@spammer" 3600 --reason "Spam"

# Remove a timeout (set duration to 0)
discli -y member timeout "My Server" "@spammer" 0

The --triggered-by Flag

When your bot acts on behalf of a Discord user, pass their ID to verify they have the required Discord permissions:

discli member kick "My Server" "@spammer" \
  --reason "Spam" \
  --triggered-by 9876543210

This checks that user 9876543210 has kick_members permission in the server before executing. The check is logged to the audit trail.

Reactions

# Add a reaction
discli reaction add "#general" 1234567890123456 "👍"

# Remove your bot's reaction
discli reaction remove "#general" 1234567890123456 "👍"

# List reactions on a message
discli reaction list "#general" 1234567890123456

# List users who reacted with a specific emoji
discli reaction users "#general" 1234567890123456 "👍"
Unicode emoji work directly. For custom server emoji, use the format `<:name:id>` or just the emoji name if your bot is in the server.

Direct Messages

# Send a DM to a user
discli dm send "@alice" "Your report is ready!"
discli dm send 1234567890 "Your report is ready!"

# List recent DMs with a user
discli dm list "@alice"
discli dm list "@alice" --limit 20

Threads

# Create a thread from a message
discli thread create "#general" 1234567890123456 "Discussion Thread"

# List active threads in a channel
discli thread list "#general"

# Send a message to a thread
discli thread send 9876543210 "Replying in the thread"

# Send with file attachment
discli thread send 9876543210 "Here's the file" --file ./data.json

# Archive / unarchive a thread
discli thread archive 9876543210
discli thread unarchive 9876543210

# Rename a thread
discli thread rename 9876543210 "New Thread Name"

# Add or remove a member from a thread
discli thread add-member 9876543210 "@alice"
discli thread remove-member 9876543210 "@alice"

Roles

# List roles in a server
discli role list "My Server"

# Create a role
discli role create "My Server" "Contributor" --color "00ff00"

# Assign a role to a member
discli role assign "My Server" "@alice" "Contributor"

# Remove a role
discli role remove "My Server" "@alice" "Contributor"

# Edit a role
discli role edit "My Server" "Contributor" \
  --name "Core Contributor" \
  --color 00ff00 \
  --hoist \
  --mentionable

# Delete a role (confirmation required)
discli role delete "My Server" "OldRole"

Server Operations

# List all servers your bot is in
discli server list

# Get server details
discli server info "My Server"

# JSON for scripting
discli --json server list | jq '.[] | {name, member_count}'

Polls

# Create a poll (via serve mode action)
# See the Serve Mode guide for poll_send details

# View poll results
discli poll results "#general" 1234567890123456

# End a poll early
discli poll end "#general" 1234567890123456

Webhooks

# List webhooks in a channel
discli webhook list "#general"

# Create a webhook
discli webhook create "#general" "Deploy Notifier"

# Delete a webhook (requires confirmation)
discli -y webhook delete "#general" 9876543210

Scheduled Events

# List scheduled events in a server
discli event list "My Server"

# Create a scheduled event
discli event create "My Server" "Game Night" \
  --start "2026-04-01T20:00:00" \
  --end "2026-04-01T23:00:00" \
  --description "Weekly game night"

# Delete a scheduled event (requires confirmation)
discli -y event delete "My Server" 9876543210

Permission Profiles

Control what commands your bot can execute:

# Show current profile
discli permission show

# List available profiles
discli permission profiles

# Switch to a restricted profile
discli permission set readonly

# Override per-invocation
discli --profile chat message send "#general" "Hello"

See the Security & Permissions guide for full details.

Audit Log

Review what destructive actions have been taken:

# Show recent audit entries
discli audit show
discli audit show --limit 50

# JSON output
discli --json audit show --limit 10

# Clear the audit log
discli audit clear

Common Patterns

Quick Status Check

# How active is a channel?
discli --json message list "#general" --limit 100 \
  | jq 'length'

Find a User's Messages

discli --json message search "#general" "" --author "alice#1234" --limit 100 \
  | jq 'length'

Broadcast to Multiple Channels

for channel in "#announcements" "#general" "#dev"; do
  discli message send "$channel" "Server maintenance at 2 AM UTC tonight."
done

Export Channel History

discli --json message history "#general" --days 30 \
  | jq -r '.[] | [.timestamp, .author, .content] | @csv' \
  > general-export.csv

Global Flags Reference

Flag Short Description
--token Bot token (overrides env and config)
--json Output as structured JSON
--yes -y Skip destructive action confirmations
--profile Override permission profile (full, chat, readonly, moderation)