Skip to main content

A note-taking toolkit for your command line.

Project description


Posce (pronounced posh·ee) is a note-taking toolkit for your command line. It takes a single directory of plaintext note files and lets you create, edit, manipulate, and organise them to your heart's content; all in a single unified interface.

Table of Contents


Posce required Python 3.8 or higher. To install, you can:


Posce only requires you to set two environment variables:

# The path to your notes directory.
POSCE_DIR = "~/notes"

# The extension your note files use (no dot).
POSCE_EXT = "txt"

On macOS and Linux, these variables can be set in your shell profile script, most likely $HOME/.profile. On Windows, you can set them in the "Environment Variables" subscreen in System Properties (search "environment" in your Start Menu).


Notes are always referred to by their pure name, no extension or filepath. In addition, notes and commands are disambiguated, which means you can write abbreviated versions and — if it's unambiguous — Posce will automatically expand them for you.

For example, if you have a directory that looks like this:

- ~/notes
    - alpha.txt
    - bravo.txt
    - charlie.txt

Then your notes will look like this:

$ posce list

$ posce show c

And you can abbreviate commands like this:

$ posce l

$ posce s c

I recommend aliasing posce to p for maximum brevity.


clip NAME

Copy the existing note NAME to the clipboard.

$ posce clip alpha
# Copy "alpha.txt" to clipboard.


Copy the existing note NAME to the new note DEST.

$ posce copy alpha delta
# Copy "alpha.txt" to new file "delta.txt".

drop NAME

Move the existing note NAME to the system trash/recycle bin.

$ posce drop alpha
# Move "alpha.txt" to trash/recycle bin.

dump FILE [-l]

Create a zip archive of the notes directory at FILE.

  • -l --level INT: Compression level from 0 to 9 (default 5).
$ posce dump
# Create zip archive "".

$ posce dump --level 9
# Create "" with maximum compression.

edit NAME [-e]

Edit the existing note NAME in your default editor.

  • e --editor PROG: Open the note in the program PROG instead.
$ posce edit alpha
# Open "alpha.txt" in default "txt" editor.

$ posce edit alpha --editor notepad
# Open "alpha.txt" in "notepad".

find TERM [-r]

List all notes containing the substring or regular expression TERM.

  • r --regex: Use search term as regex.
$ posce find "Charliiiiiiieeeeeee!"

$ posce find "Charli{7}e{7}!" --regex

list [GLOB] [-rs]

List all notes with names matching GLOB (default *).

  • -r --reverse: Reverse sorting order.
  • -s --sort (name|size): Sort notes by name or size.
$ posce list

$ posce list al*

$ posce list --reverse --sort name

make NAME [-f]

Create the new empty note NAME.

  • -f --file FILE: Copy the note's contents from a file.
$ posce make delta
# Create empty file "delta.txt" in notes directory.

$ posce make delta --file ~/temp.txt
# Create "delta.txt" with contents from "~/temp.txt".


Move the existing note NAME to the new note DEST.

$ posce move alpha delta
# Move "alpha.txt" to "delta.txt".

show NAME [-w]

Print the contents of the existing note NAME.

  • -w --wrap COLS: Wrap text to this width.
$ posce show alpha
This is the note Alpha!

$ posce show bravo --wrap 40
This is the much longer note Bravo, and
will be wrapped across two lines.


Download a URL into the existing note NAME.

$ posce wget alpha
# Download "" and write contents to "alpha.txt".


Why use this instead of ls/grep/wget/etc?

Posce is one app using one system on one directory. It's a very focused app, and that focus gives it a level of stability and uniformity I enjoy. Also, by using a single notes directory, you can use disambiguated names and get incredible brevity when entering commands.

Why environment variables? Why not a config file?

The last thing you or I need is another configuration file clogging up our home directories. Environment variables are simpler, lighter, and can be overriden much easier. Also, if Posce did use a config file, it would only have those two variables anyway!

Why do I have to make a new note before editing it?

It makes the code simpler and more robust, it allows for disambiguation of names, and I just prefer that kind of explicit operation.

Why can I only trash notes and not delete them?

I'm paranoid about data loss, which means Posce will never, ever, under any circumstances implement file deletion. If you want to delete your files, do it yourself.


Bugs, suggestions, and feature requests are welcome! Please add them to the issue tracker with an appropriate label.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

posce-0.4.0.tar.gz (13.1 kB view hashes)

Uploaded Source

Built Distribution

posce-0.4.0-py3-none-any.whl (16.7 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page