rentry: a markdown pastebin you can drive from the shell

Two shapes of the same client

This repository holds the official Python clients for the rentry API, and the project structure gives you a genuine choice about how to deploy them. rentry.py is a command-line tool in a single file with no dependencies, rentry_client is an installable library, and examples/ has one runnable script per API use case. The README tells you that if you would rather write your own client, you should skip to the API reference, which tells you how much of the service is a documented contract rather than an implementation detail of this code. The service itself is a markdown-powered paste and publishing service with preview, custom urls and editing, and the client covers the full surface of that, since the command set includes creating a new entry, editing an existing entry's text, getting the raw markdown text, fetching an entry's full details as JSON, deleting an entry, updating an entry's edit code, url or modify code, and a command whose only job is to keep a captcha code from expiring. The 2.0.0 release is titled Rework to importable client and pip install, which is the change that produced the split between the single file tool and the library.

Installing it three ways, none of them heavy

The installation section covers the normal path first, which gives you both the command line tool and the library.

pip install rentry

The second path is the one that makes the no-dependency claim concrete, since the CLI also works as a single self-contained file.

wget https://raw.githubusercontent.com/radude/rentry/master/rentry.py -O ./rentry && chmod +x ./rentry

The third is building from source.

git clone https://github.com/radude/rentry.git
cd rentry
pip install .

The scripts in examples/ additionally want pip install -r requirements.txt, which pulls in python-dotenv for reading a .env file. That is the only third party dependency anywhere in the project, and it is a development convenience for the examples rather than a requirement of the client, which is consistent with the pyproject file declaring an empty dependencies list. The package metadata says requires-python 3.9 or newer, the build backend is setuptools with version 61 or newer, and the console script entry point maps the rentry command to rentry:main. The packaging note in the pyproject file explains the layout, that the standalone CLI at the repo root ships as a top-level module so the console script can reuse it, while the library lives in src/rentry_client. The project is MIT licensed.

Reading the command surface

The help output is worth reading in full, because it shows a design decision that most paste clients do not make. The usage line lists seven commands, new, edit, raw, fetch, delete, update and extend, and the options are the ones you would expect plus one you would not. There is a url option that is random if not specified, an edit code option that is random if not specified, a field and value pair used only by the update command, an auth code used only by the raw command, and a captcha code that defaults to the CAPTCHA_CODE environment variable. The examples section shows the intended everyday usage.

  rentry new 'markdown text'               # new entry with random url and edit code
  rentry new -p pw -u example 'text'       # with custom edit code and url
  rentry edit -p pw -u example 'text'      # edit the example entry
  cat FILE | rentry new                    # read from FILE and paste it to rentry
  cat FILE | rentry edit -p pw -u example  # read from FILE and edit the example entry
  rentry raw -u example                    # get raw markdown text
  rentry raw -u example -a CODE            # with a rentry-auth access code
  rentry fetch -u example -p pw            # fetch full details as JSON

The pipe forms are the reason a terminal user would want this at all, since catting a file into a paste gives you a shareable link without opening an editor. The update command is the unusual one, and it is the reason edit codes and URLs can be rotated without recreating the entry.

  rentry update -p pw -u example -f 'edit_code' -v 'new-pw'   # Sets the edit code to something new
  rentry update -p pw -u example -f 'url' -v 'new_url'        # Sets the url to something new
  rentry update -p pw -u example -f 'modify_code' -v 'm:1'    # Sets the modify code to something new
  rentry update -p pw -u example -f 'modify_code' -v ''       # Unsets the modify code

The three fields it can change are edit_code, url and modify_code, and the modify code can be unset by passing an empty value.

The library hands you dicts, not exceptions

The library usage is compact and the error model is worth understanding before you build on it.

from rentry_client import RentryClient

client = RentryClient()  # or RentryClient('https://my-instance.example')

page = client.new(text='hello world', metadata={'PAGE_TITLE': 'Hello'})
print(page['url'], page['edit_code'])

client.edit(page['url_short'], page['edit_code'], text='updated!')

details = client.fetch(page['url_short'], page['edit_code'])
print(details)

Every method hands back the parsed API response as a dict. On success, response['status'] is '200'. When something goes wrong, the details are in response['content'] and response['errors']. So the library does not raise on an API error, it returns a structure you inspect, which means a caller that forgets to check the status will silently treat a failure as a success. That is a deliberate style and a common one in API clients, but it puts the responsibility on the caller, and it is worth being explicit about in your own wrapper. The client can also be pointed at another instance by passing a URL to the constructor, and the README notes that the CLI and the examples both default to https://rentry.co, with a .env file read to override the base protocol and base URL for pointing at a local dev server.

Captcha codes are the operational rough edge

The most interesting part of the documentation is the captcha handling, because it describes a real constraint on unattended use. A page can be temporarily locked after too many wrong edit codes, and when that happens the CLI prints a link for you to open in a browser, complete the captcha, and use the code it gives you. That code is what the -c option takes, or what you can keep in the CAPTCHA_CODE environment variable or a .env file so every run uses it. The library has the same mechanism, and the code shows how to handle it.

client = RentryClient(captcha_code='YOUR_CODE')  # sent with every edit, fetch and delete

result = client.edit('example', 'pw', text='updated!')
if result['status'] == '429' and 'captcha_url' in result:
    print('Locked, and the code does not work. Get a new one at', result['captcha_url'])

print(client.extend_captcha_code())  # {'status': '200', 'content': 'OK', 'expires': '2026-12-15'}

Two details are worth naming. The 429 status with a captcha_url in the response is the machine readable form of the lock, so an unattended script can detect it and report where to go. And the library never extends a code by itself, so you have to call extend_captcha_code() from time to time, for example once per run, which means a long lived service has to schedule that. The rentry extend command does the same thing from the shell. The design is defensible, since a captcha is a human gate, but it does mean the client is not something you can point at a locked page and forget about.

The examples directory is the reference

The examples are described as one runnable script per API use case, each running as-is, and the file list in the repository matches that. There is new.py, which creates a page with metadata, edit.py, which updates a page's text with its edit code, edit_upsert.py, which changes some metadata options without replacing the rest, edit_modify_code.py, which sets a modify code and then edits with it, edit_secret_metadata.py for secret metadata, edit_change_url.py, fetch.py, raw.py, delete.py and captcha_code.py. Two of them stand out as the interesting cases rather than the routine ones. The upsert script is the one that shows the distinction between editing text and editing metadata in place, which matters if you are storing structured information alongside a document. The modify code script is the one that shows the third credential, and the README describes the modify code separately from the edit code, so a page can have an edit code for its owner and a modify code that grants a narrower right, which is the mechanism for sharing an editable page without handing over full control. The captured portion of the example table is truncated in the README, so the full set of metadata options is in the files themselves rather than in the documentation.

Where rentry fits against other paste services

The comparison with other pastebins is mostly about trade-offs you already know, and the client makes some of them concrete. A terminal-first service with custom URLs and an edit code is closer to a lightweight publishing tool than to a throwaway paste, because the entry survives and can be revised, and the preview and editing on the service side mean a reader gets something better than a wall of plain text. Against a general note-taking application, the difference is that there is no local copy and no sync, so a paste is a link and the content lives on the server. Against a hosted API with a full SDK, this client is much smaller, with no dependencies, and it does exactly the seven operations the service offers rather than a broad platform surface. The limits are the same ones the service imposes rather than the client's. Access control is a set of codes, so losing the edit code means losing the ability to edit, and the README is explicit that a generated edit code is shown to you only once, so remember it or save it, and that you can share it with anyone so a group of people can edit the same entry. There is also a rentry-auth access code for the raw command, which is the mechanism for reading a page whose raw content is otherwise restricted. And the whole thing depends on a third party staying up, which for a personal pastebin is a trade most people make and for a document pipeline is one worth thinking about.

Editorial conclusion

Adopt rentry if you publish markdown often from a terminal or a script and want an editable, previewable paste with custom URLs and no dependencies to install. Skip it if you need a long-lived unattended editor, since the service locks pages after repeated wrong edit codes and the captcha flow is meant to be driven by a person. Verify first which base URL your client is pointed at, that you have stored the edit code for any entry you intend to change later, and that a background job keeps the captcha code alive with rentry extend.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. radude/rentry on GitHub
4. README
5. Releases