customrp-cli
Show a custom Discord Rich Presence ("Playing ...", with your own text, images, buttons and timer) from the command line, configured with a TOML file. It runs natively on Linux, macOS and Windows.
customrp-cli is a command-line alternative to CustomRP, the Windows app by maximmax42. It does what CustomRP does, minus the window. It's built on customrp-core, a library that does the heavy lifting.
Independent project. customrp-cli isn't made or maintained by CustomRP's developer, and isn't an official replacement. Please report problems here, not on the CustomRP repository.
$ customrp-cli init
Wrote /home/you/.config/customrp-cli/config.toml
$ nano ~/.config/customrp-cli/config.toml
$ customrp-cli run
2026-01-01 12:00:00 INFO Starting customrp-cli 0.1.0 with /home/you/.config/customrp-cli/config.toml
2026-01-01 12:00:00 INFO Connecting to Discord with application ID 896771305108553788
2026-01-01 12:00:00 INFO Connected to /run/user/1000/discord-ipc-0
2026-01-01 12:00:00 INFO Connected to Discord as you
2026-01-01 12:00:00 INFO Presence updated
Why
CustomRP is a Windows Forms application, so it only runs on Windows. Linux users have had to rely on Wine or RPC bridges. The GUI is convenient, but the useful part, telling Discord what to show, doesn't need a window. customrp-cli does that part natively, from a config file. That also makes it work on headless setups, under a service manager, and in dotfiles.
Features
- Everything CustomRP can show: activity type (Playing, Listening, Watching, Competing), name, details and state lines with optional links, party size, large and small images (asset names or URLs) with tooltips and links, two buttons, and which field appears in the member list
- All five CustomRP timestamp modes: since last connection, since startup, since last update, local time, and custom start/end (including countdowns)
- Live reload: save the config file and the presence updates within a second, without reconnecting
- Checks your config the way Discord will (length limits in bytes, one-character fields, broken URLs, image URLs that are too long) and names the exact option at fault
- Waits for Discord: if Discord isn't running yet, it retries every 10 seconds, and reconnects if Discord restarts
- Imports and exports CustomRP's
.crppresets, so you can move presets between this and the Windows app - Lists the art assets uploaded to your Discord application
- One instance per user, with
statusandstopcommands that work on every platform - Runs as a systemd user service, a launchd agent, or a Windows scheduled task; ready-made files are in
contrib/ - No GUI, no Wine, and nothing beyond Python (plus
tomlion Python 3.9 and 3.10)
How it differs from CustomRP
| CustomRP (Windows app) | customrp-cli |
|---|---|
| Window with text boxes and dropdowns | A TOML config file (reference) |
| Click "Update presence" | Save the file; it reloads automatically |
| Minimizes to the tray | Runs in a terminal or as a background service |
| "Run on startup" checkbox | systemd, launchd or Task Scheduler (guide) |
| Gives up after 30 attempts to reach Discord | Retries forever by default (max_retries) |
| Translated into many languages | English only for now |
| Built-in update checker | Update with pipx upgrade customrp-cli |
More in docs/migrating-from-customrp.md.
Supported systems
| System | Status |
|---|---|
| Linux | Tests run in CI on Ubuntu, and were run on Ubuntu 24.04 (WSL), against a fake Discord over a real Unix socket, including running as a separate process. Not yet tested against the real Discord client on Linux. |
| Windows 10/11 | Tests run in CI and on Windows 11 against a fake Discord over a named pipe, including background mode with pythonw. The underlying library has completed a handshake with the real Discord client. |
| macOS | Tests run in CI on macOS against a fake Discord over a real Unix socket, including running as a separate process. Not yet tested against the real Discord client on macOS, and the launchd setup is untested. |
You need:
- Python 3.9 or newer
- The Discord desktop app (or a client that provides Discord's IPC socket, like Vesktop) running on the same computer, as the same user. The browser version can't show Rich Presence from other programs.
Installation
The easiest way is pipx, which puts customrp-cli in its own environment and
on your PATH:
pipx install customrp-cli
Don't have pipx? It needs Python 3.11 or newer. The short version:
| System | Command |
|---|---|
| macOS | brew install pipx |
| Ubuntu, Debian | sudo apt install pipx |
| Fedora | sudo dnf install pipx |
| Arch | sudo pacman -S python-pipx |
| Windows | py -m pip install --user pipx |
Then run pipx ensurepath (on Windows: py -m pipx ensurepath) and open a new terminal. Step-by-step
instructions for every system are in docs/installation.md.
Or with a virtual environment and requirements.txt:
git clone https://github.com/KeiraOMG0/customrp-cli.git
cd customrp-cli
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt # Installs customrp-core from GitHub
pip install .
Plain pip install customrp-cli inside a virtual environment works too.
Details, including Windows notes and uninstalling, are in docs/installation.md.
Quick start
customrp-cli init # Writes a config file with every option, then prints its path
# Edit the file: set details, state, images, buttons...
customrp-cli check # Points out mistakes
customrp-cli preview # Shows exactly what will be sent to Discord
customrp-cli run # Shows the presence until you press Ctrl+C
To use your own application name and images, create an application in the
Discord Developer Portal and put its ID in
application_id. CustomRP's setup guide walks through it.
Configuration
A minimal config:
[presence]
application_id = "123456789012345678"
details = "Exploring the Linux desktop"
state = "Day 3"
timestamps = "since_startup"
[presence.large_image]
key = "penguin" # An asset name from your application, or an image URL
text = "Tux says hi"
[[presence.buttons]]
label = "My website"
url = "https://example.com"
Every option is optional. examples/config.toml is a complete, commented
example, and docs/configuration.md explains each option.
The config file is at:
| System | Default path |
|---|---|
| Linux | ~/.config/customrp-cli/config.toml (or $XDG_CONFIG_HOME/customrp-cli/) |
| macOS | ~/Library/Application Support/customrp-cli/config.toml |
| Windows | %APPDATA%\customrp-cli\config.toml |
Use another file with -c path/to/file.toml, or set CUSTOMRP_CLI_CONFIG.
Commands
| Command | Does |
|---|---|
customrp-cli init [--force] |
Create a config file listing every option |
customrp-cli check |
Check the config for mistakes (alias: validate) |
customrp-cli preview |
Print the activity that would be sent, as JSON |
customrp-cli run [--no-watch] |
Show the presence until stopped |
customrp-cli status |
Show whether it's running, its connection state and Discord user |
customrp-cli stop |
Stop the running instance |
customrp-cli import FILE.crp [--force] |
Replace the presence in the config with a CustomRP preset |
customrp-cli export FILE.crp [--force] |
Save the configured presence as a CustomRP preset |
customrp-cli assets [--application-id ID] |
List the images uploaded to your Discord application |
customrp-cli paths |
Show where the config and runtime files are |
Options for every command: -c/--config FILE, -v/--verbose (debug output), -q/--quiet (errors
only), -h/--help, plus -V/--version. Exit codes and more examples are in
docs/commands.md.
customrp-cli never asks questions or waits for input, so it's safe to use from scripts, cron and service managers.
Running in the background
# Linux (systemd), after installing with pipx:
mkdir -p ~/.config/systemd/user
curl -o ~/.config/systemd/user/customrp-cli.service \
https://raw.githubusercontent.com/KeiraOMG0/customrp-cli/main/contrib/systemd/customrp-cli.service
systemctl --user daemon-reload
systemctl --user enable --now customrp-cli
journalctl --user -u customrp-cli -f # Watch the log
macOS (launchd) and Windows (Task Scheduler) are covered in docs/running-in-the-background.md.
Logging and troubleshooting
run logs to the terminal (stderr). Add -v to see every message exchanged with Discord, or set
[logging] file to also log to a file (rotated at 1 MB).
| Problem | Try |
|---|---|
Couldn't find a running Discord client |
Start the Discord desktop app. With Flatpak or Snap, see troubleshooting. |
Discord returned an error (4000): Invalid Client ID |
application_id is wrong |
| Runs fine but nothing shows on your profile | In Discord: User Settings → Activity Privacy → turn on sharing your activity |
already running |
customrp-cli status, then customrp-cli stop |
More in docs/troubleshooting.md.
Known limitations
- English only.
- Only the presence settings are shared with CustomRP, through
.crppresets; CustomRP's own settings file isn't read. - One instance per user. Showing two presences at once isn't supported.
- Discord's socket locations for Flatpak, Snap and Vesktop come from other Rich Presence projects and haven't been verified here.
- Changes to
[connection]and[logging]need a restart;[presence]changes apply live.
Documentation
docs/: installation · configuration · commands · background · troubleshooting · migrating from CustomRP · design · development
Running the tests
pip install -e ".[test]"
pytest
The tests don't need Discord; they use a fake Discord server from customrp-core. See docs/development.md.
Contributing
Issues and pull requests are welcome. Please:
- open an issue first for anything big
- add tests for behaviour changes (
pytestmust pass) - keep it small: no new dependencies or abstractions without a concrete need
- put changes to how presences work in customrp-core, and changes to the command line, config and running in this repository
Credits
- CustomRP by maximmax42 (MIT). The features, rules and preset format come from it, and its developer was open to an independent alternative.
- CustomRP's default Discord application and its image proxy (
customrp.xyz/proxy, used for Discord-hosted images) belong to CustomRP's developer.
License
MIT. See LICENSE.
Metadata
Release files for customrp-cli 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| customrp_cli-0.1.1.tar.gz | 31.8 kB | With provenance | Details for customrp_cli-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| customrp_cli-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for customrp_cli-0.1.1-py3-none-any.whl |
Total release size: 56.1 kB
Release files / customrp_cli-0.1.1.tar.gz
| Download URL | customrp_cli-0.1.1.tar.gz |
|---|---|
| Size | 31.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
6a146a10171e2a2329c58c1edc0dc46f59da3c67268bfb62409e4d6eaf70ad96
|
|
BLAKE2b-256 checksum How to use checksums |
d9ee0b1bc9afe8652f3ab27a2b7d4653bce60cb725e347d8bfea3f499e848a7b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.
Transparency logRelease files / customrp_cli-0.1.1-py3-none-any.whl
| Download URL | customrp_cli-0.1.1-py3-none-any.whl |
|---|---|
| Size | 24.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c5c70ad1c834472f7b0c0e2f9decf92051408a2e44baa3d28c1c59941413b0c1
|
|
BLAKE2b-256 checksum How to use checksums |
cf6b6374b747d957df8675796d0155454e0b21e5798dc6fc1639b8f7dcae5df6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.
Transparency logSecurity for customrp-cli 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for customrp_cli-0.1.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.