Skip to main content

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 .crp presets, 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 status and stop commands 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 tomli on 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 .crp presets; 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 (pytest must 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)

Source distribution for customrp-cli 0.1.1
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)

Table of built distributions (wheels) for customrp-cli 0.1.1
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page