Skip to main content

notefeed

Post and read markdown notes on a notefeed server from Python or the command line. Python 3.11 or newer.

pip install notefeed
export NOTEFEED_URL=https://notes.example.com NOTEFEED_FEED=homelab-7f3k2q9x4m8wz
notefeed post "# Backup finished"
backup.sh 2>&1 | notefeed post -
notefeed notes --limit 5
notefeed edit Vq3xH8mTn2KfLw0aZr9bYe "# Backup finished, verified"
notefeed delete Vq3xH8mTn2KfLw0aZr9bYe
from notefeed import Client

client = Client("https://notes.example.com", feed="homelab-7f3k2q9x4m8wz")  # password="..." if the instance has one
created = client.post("# Deploy done\nversion 1.4.2")
print(created.url, created.read_url)
for note in client.notes():  # newest first, page by page
    print(note.date, note.title)

read_url is None for a feed without a read link (rare; see the operations docs).

Every note has a date, now unless you give one: client.post(text, date="2025-03-01T09:30:00Z") (a timezone-aware datetime, a date for midnight UTC, or an ISO 8601 string; any time from 1970 to 9999), or notefeed post "…" --date 2025-03-01. The note takes its place in the feed by that date. A date in the future schedules the note: readers see it from then on. client.update(id, date=...) (notefeed update <id> --date …) moves a note.

Client.from_env() reads NOTEFEED_URL / NOTEFEED_FEED / NOTEFEED_PASSWORD; so does the notefeed command, unless given --url / --feed / --password.

A feed can have its own password, which gates reading, listing and posting to it. Pass feed_password="..." to Client(...) (or per call, e.g. client.post(text, feed_password=...)), or set NOTEFEED_FEED_PASSWORD, which from_env() and the notefeed command both read (there is deliberately no flag, so it stays out of shell history). It is sent as X-Feed-Password; Authorization stays the instance password. A feed password is 1 to 256 printable ASCII characters with no space at the start or end; an empty one is the same as none.

A posted note can be changed or removed: client.edit(id, content) replaces its content and returns the note (its id and URLs stay), and client.delete(id) removes it. Both take the same feed and feed_password arguments as post, and a missing note is a NotFoundError. notefeed edit <id> <text | - | --file PATH> prints the note URL; notefeed delete <id> prints nothing. Anyone who can post to a feed can edit and delete its notes, and deleting is permanent.

A feed can have a title and a description, and can be deleted: client.feed_info() returns the feed (name, title, description, protected, read_url), client.update_feed(title, description) replaces both (an empty string clears one) and returns the feed, and client.delete_feed() removes the feed with all its notes for good. All three take the same feed and feed_password arguments as post, and a feed that doesn't exist is a NotFoundError. Anyone who can post to a feed can do this, and deleting is permanent; there are no notefeed commands for it.

A picture is a note of its own: client.post(data, type="image/png", alt="…") takes bytes (PNG, JPEG, GIF or WebP) and returns what a markdown post returns, with the picture's file and file_url added. Write ![](file) in a markdown note to show it; the feed is created by its first note, a picture that is too large is a NoteTooLargeError, and an instance that takes no pictures (NOTEFEED_IMAGE_UPLOADS=0) answers every picture with an ImagesOffError. The server checks the bytes against the declared type. client.update(id, title=..., alt=..., tags=[...], date=...) changes a note's title, a picture's alt text, a note's tags (the whole list; notefeed update <id> --tags a,b) or its date, and client.edit(id, content) replaces its content. client.update_feed(title, description, image=file) makes a picture the feed's title image (image="" removes it; leaving image out keeps it). notefeed post --file photo.png posts a file (the type comes from the extension, or --type). To post a note with its pictures in one call, client.post(text, attachments=[Attachment("chart.png", data, "image/png")]) posts them with the text in one request, and the server swaps ![](chart.png) for each file name (None content posts only the pictures) (notefeed post "…" --attach chart.png does the same); nothing is posted when one is refused. Send pictures full size (up to 10 MiB by default): the server stores each one turned upright, at most 2560 px on its long side and without metadata such as EXIF or GPS position, and a busy server answers a RateLimitedError with retry_after. Pictures are public to anyone with the feed's read link.

Full documentation: https://docs.notefeed.me/integrations/clients/

Metadata

Release files for notefeed 0.31.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for notefeed 0.31.0
File Size Uploaded Provenance Actions
notefeed-0.31.0.tar.gz 53.8 kB With provenance Details for notefeed-0.31.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for notefeed 0.31.0
File Interpreter ABI Platform Actions
notefeed-0.31.0-py3-none-any.whl Python 3 none any Details for notefeed-0.31.0-py3-none-any.whl

Total release size: 129.1 kB

Release files / notefeed-0.31.0.tar.gz

Download URL notefeed-0.31.0.tar.gz
Size 53.8 kB
Tags Source
SHA-256 checksum
How to use checksums
6953020cb61ec23f31730f243a13713bcc0f1122a832af961a19771854a07a22
BLAKE2b-256 checksum
How to use checksums
08d3be503a7785a974282119f256e72ce3cdc66c2d8f81f85e8326417e15042f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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 28, 2026.

Transparency log

Release files / notefeed-0.31.0-py3-none-any.whl

Download URL notefeed-0.31.0-py3-none-any.whl
Size 75.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
06f2dfea5efe9c81f7edecf98a9275ed409f99cd3447f368d8fbd5454145f7a4
BLAKE2b-256 checksum
How to use checksums
ba8876527e33e12f97bc96a10ea39c113f2d854ce3717b00bed2d0b8f77ca858
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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 28, 2026.

Transparency log

Security for notefeed 0.31.0

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 notefeed-0.31.0.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 28, 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.31.0 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