CLI Usage | discli

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"`

Tip

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.

# 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

# 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

# Get a specific message by ID
discli message get "#general" 1234567890123456

# 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

JSON Output and jq Piping

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

# 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

Warning

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

# 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")'

# 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"

# Edit a channel's topic and slowmode
discli channel edit "#general" --topic "New topic" --slowmode 10

# Set channel permissions for a role
discli channel set-permissions "#general" "Members" \
  --allow send_messages \
  --deny manage_messages

# Get channel details
discli channel info "#general"

# JSON output
discli --json channel info "#general"

Output includes: ID, name, type, server, topic, and creation date.

# 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 "👍"

Note

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`)

Last updated: March 22, 2026

6 min read

Edit this page

Identifier Resolution

Sending Messages

Reading Messages

JSON Output and jq Piping

Replying and Editing

Channel Management

Member Operations

The --triggered-by Flag

Reactions

Direct Messages

Threads

Roles

Server Operations

Polls

Webhooks

Scheduled Events

Permission Profiles

Audit Log

Common Patterns

Quick Status Check

Find a User’s Messages

Broadcast to Multiple Channels

Export Channel History

Global Flags Reference

The `--triggered-by` Flag