Preview of the Discord v10 HTTP API specification. See https://discord.com/developers/docs for more details.
Learn more at Discord.
Created by @mvanhorn (Hunter Veltri).
Quick Start
1. Install
See Install above.
2. Set Up Credentials
Set the endpoint variables for the tenant, workspace, or API version you want this CLI to use:
export DISCORD_APPLICATION_ID="<application_id>"
export DISCORD_CHANNEL_ID="<channel_id>"
export DISCORD_GUILD_ID="<guild_id>"
export DISCORD_GUILD_SCHEDULED_EVENT_ID="<guild_scheduled_event_id>"
export DISCORD_SKU_ID="<sku_id>"
Get your API key from your API provider's developer portal. The key typically looks like a long alphanumeric string.
export DISCORD_BOT_TOKEN="<paste-your-key>"
To persist credentials, use discord-pp-cli auth set-token <token>. Stored secrets live in credentials.toml under the data directory, not in config.toml.
3. Verify Setup
discord-pp-cli doctor
This checks your configuration and credentials.
4. Try Your First Command
discord-pp-cli applications get mock-value
Usage
Run discord-pp-cli --help for the full command reference and flag list.
Paths & environment variables
This CLI separates local files into four path kinds:
| Kind | Contents |
|---|
config | User-editable settings such as config.toml and saved profiles |
data | Durable local data: credentials.toml, data.db, cookies, browser-session proof files, and other auth sidecars |
state | Runtime state such as persisted queries, jobs, and teach.log |
cache | Regenerable HTTP/cache files |
Each kind resolves independently. The ladder is:
- Per-kind env var:
DISCORD_CONFIG_DIR, DISCORD_DATA_DIR, DISCORD_STATE_DIR, or DISCORD_CACHE_DIR
--home <dir> for this invocationDISCORD_HOME for a flat relocated root- XDG env vars:
XDG_CONFIG_HOME, XDG_DATA_HOME, XDG_STATE_HOME, XDG_CACHE_HOME
- Platform defaults matching existing installs
For containers and agent sandboxes, prefer a single relocated root:
export DISCORD_HOME=/srv/discord
discord-pp-cli doctor
Under DISCORD_HOME=/srv/discord, the four dirs resolve to /srv/discord/config, /srv/discord/data, /srv/discord/state, and /srv/discord/cache.
MCP servers do not receive CLI flags from the host. Put relocation in the host env block:
{
"mcpServers": {
"discord": {
"command": "discord-pp-mcp",
"env": {
"DISCORD_HOME": "/srv/discord"
}
}
}
}
Precedence matters in fleets: an ambient per-kind variable such as DISCORD_DATA_DIR overrides an explicit --home for that kind. Use DISCORD_HOME or the per-kind variables for durable fleet relocation; treat --home as the weaker per-invocation lever.
Relocation is one-way. Unsetting DISCORD_HOME does not move files back to platform defaults, and doctor cannot find credentials left under a former root. Move the files manually before unsetting relocation variables.
Existing installs keep working because the platform-default rung matches the legacy layout. On the first auth write, stored secrets leave config.toml and are consolidated into credentials.toml under the data directory. Run discord-pp-cli doctor --fail-on warn to check path and credential-location warnings in automation.
Commands
applications
Manage applications
discord-pp-cli applications get - Getdiscord-pp-cli applications get-my - Get mydiscord-pp-cli applications update - Updatediscord-pp-cli applications update-my - Update my
channels
Manage channels
discord-pp-cli channels delete - Deletediscord-pp-cli channels get - Getdiscord-pp-cli channels update - Update
gateway
Manage gateway
discord-pp-cli gateway get - Getdiscord-pp-cli gateway get-bot - Get bot
guilds
Manage guilds
discord-pp-cli guilds get - Getdiscord-pp-cli guilds get-template - Get templatediscord-pp-cli guilds update - Update
interactions
Manage interactions
invites
Manage invites
discord-pp-cli invites resolve - Resolvediscord-pp-cli invites revoke - Revoke
lobbies
Manage lobbies
discord-pp-cli lobbies create-lobby - Create lobbydiscord-pp-cli lobbies create-or-join-lobby - Create or join lobbydiscord-pp-cli lobbies delete-lobby - Deletes the specified lobby if it exists. It is safe to call even if the lobby is already deleted.discord-pp-cli lobbies edit-lobby - Edit lobbydiscord-pp-cli lobbies get-lobby - Get lobby
oauth2
Manage oauth2
discord-pp-cli oauth2 get-my-application - Get my applicationdiscord-pp-cli oauth2 get-my-authorization - Get my authorizationdiscord-pp-cli oauth2 get-openid-connect-userinfo - Get openid connect userinfodiscord-pp-cli oauth2 get-public-keys - Get public keys
partner-sdk
Manage partner sdk
discord-pp-cli partner-sdk bot-token - Bot tokendiscord-pp-cli partner-sdk bot-unmerge-provisional-account - Bot unmerge provisional accountdiscord-pp-cli partner-sdk token - Tokendiscord-pp-cli partner-sdk unmerge-provisional-account - Unmerge provisional accountdiscord-pp-cli partner-sdk update-user-message-external-moderation-metadata - Update the external moderation metadata for a user message (DM).
skus
Manage skus
soundboard-default-sounds
Manage soundboard default sounds
discord-pp-cli soundboard-default-sounds - Get
stage-instances
Manage stage instances
discord-pp-cli stage-instances create - Creatediscord-pp-cli stage-instances delete - Deletediscord-pp-cli stage-instances get - Getdiscord-pp-cli stage-instances update - Update
sticker-packs
Manage sticker packs
discord-pp-cli sticker-packs get - Getdiscord-pp-cli sticker-packs list - List
stickers
Manage stickers
discord-pp-cli stickers <sticker_id> - Get
users
Manage users
discord-pp-cli users create-dm - Create dmdiscord-pp-cli users delete-application-role-connection - Delete application role connectiondiscord-pp-cli users get - Getdiscord-pp-cli users get-application-role-connection - Get application role connectiondiscord-pp-cli users get-current-application-entitlements - Get current application entitlementsdiscord-pp-cli users get-my - Get mydiscord-pp-cli users get-my-guild-member - Get my guild memberdiscord-pp-cli users leave-guild - Leave guilddiscord-pp-cli users list-my-connections - List my connectionsdiscord-pp-cli users list-my-guilds - List my guildsdiscord-pp-cli users update-application-role-connection - Update application role connectiondiscord-pp-cli users update-my - Update my
voice
Manage voice
discord-pp-cli voice - List regions
webhooks
Manage webhooks
discord-pp-cli webhooks delete - Deletediscord-pp-cli webhooks delete-by-token - Delete by tokendiscord-pp-cli webhooks execute - Executediscord-pp-cli webhooks get - Getdiscord-pp-cli webhooks get-by-token - Get by tokendiscord-pp-cli webhooks update - Updatediscord-pp-cli webhooks update-by-token - Update by token
Self-learning loop
This CLI caches per-question discovery so repeat queries skip the walk and structurally similar queries get answered via entity substitution. The loop also self-captures: every invocation is journaled locally, and failed-flag corrections plus fresh teaches surface as candidates on the next recall for confirm/reject judgment. Agents call recall before discovery and fire teach & after answering. See the ## Automatic learning section in SKILL.md for the full protocol.
discord-pp-cli recall <query> - Look up cached resources for a query before running discoverydiscord-pp-cli teach - Record a query -> resource mapping (silent on success, safe to background with &)discord-pp-cli learnings list - Inspect taught rowsdiscord-pp-cli learnings forget <query> - Undo a teachdiscord-pp-cli learnings candidates - List auto-captured candidates awaiting confirm/rejectdiscord-pp-cli learnings stats - Local loop metrics: recall hit rate, teach-to-reuse, playbook resolution, candidate countsdiscord-pp-cli teach-pattern - Install a query/resource template up frontdiscord-pp-cli teach-lookup - Add an entity mapping (e.g. country code, team alias) for pattern substitution
Pass --no-learn or set DISCORD_NO_LEARN=true to disable the loop for deterministic flows.
The local store's schema version stamp is one-way: once this version of discord-pp-cli opens the database, older binaries refuse it with a version error — upgrade the binary rather than downgrading.
Output Formats
# Human-readable table (default in terminal, JSON when piped)
discord-pp-cli applications get mock-value
# JSON for scripting and agents
discord-pp-cli applications get mock-value --json
# Filter to specific fields
discord-pp-cli applications get mock-value --json --select id,name,status
# Dry run — show the request without sending
discord-pp-cli applications get mock-value --dry-run
# Agent mode — JSON + compact + no prompts in one flag
discord-pp-cli applications get mock-value --agent
Agent Usage
This CLI is designed for AI agent consumption:
- Non-interactive - never prompts, every input is a flag
- Pipeable -
--json output to stdout, errors to stderr
- Filterable -
--select id,name returns only fields you need
- Previewable -
--dry-run shows the request without sending
- Explicit retries - add
--idempotent to create retries and add --ignore-missing to delete retries when a no-op success is acceptable
- Confirmable -
--yes for explicit confirmation of destructive actions
- Piped input - write commands can accept structured input when their help lists
--stdin
- Offline-friendly - sync/search commands can use the local SQLite store when available
- Agent-safe by default - no colors or formatting unless
--human-friendly is set
Exit codes: 0 success, 2 usage error, 3 not found, 4 auth error, 5 API error, 7 rate limited, 10 config error.
Runtime Endpoint
This CLI resolves endpoint placeholders at runtime, so one installed binary can target different tenants or API versions without regeneration.
Endpoint environment variables:
DISCORD_APPLICATION_ID resolves {application_id}DISCORD_CHANNEL_ID resolves {channel_id}DISCORD_GUILD_ID resolves {guild_id}DISCORD_GUILD_SCHEDULED_EVENT_ID resolves {guild_scheduled_event_id}DISCORD_SKU_ID resolves {sku_id}
Base URL: https://discord.com/api/v10
Health Check
discord-pp-cli doctor
Verifies configuration, credentials, and connectivity to the API.
Configuration
Run discord-pp-cli doctor to see the resolved config, data, state, and cache directories. The platform-default config path is ~/.config/discord-pp-cli/config.toml; --home, DISCORD_HOME, and per-kind env vars can relocate it.
Static request headers can be configured under headers; per-command header overrides take precedence.
Environment variables:
| Name | Kind | Required | Description |
|---|
DISCORD_APPLICATION_ID | endpoint | Yes | |
DISCORD_CHANNEL_ID | endpoint | Yes | |
DISCORD_GUILD_ID | endpoint | Yes | |
DISCORD_GUILD_SCHEDULED_EVENT_ID | endpoint | Yes | |
DISCORD_SKU_ID | endpoint | Yes | |
DISCORD_BOT_TOKEN | per_call | Yes | Set to your API credential. |
agentcookie (optional)
If you use agentcookie to sync secrets across machines, this CLI auto-adopts agentcookie-managed credentials with no extra setup. When the daemon writes to this CLI's config, discord-pp-cli doctor reports agentcookie: detected and auth-status labels the source as agentcookie. Skip this section if you don't use agentcookie - the CLI works the same as any other.
Troubleshooting
Authentication errors (exit code 4)
- Run
discord-pp-cli doctor to check credentials
- Verify the environment variable is set:
echo $DISCORD_BOT_TOKEN
Not found errors (exit code 3)
- Check the resource ID is correct
- Run the
list command to see available items
Generated by CLI Printing Press