posce 1.0.0

A note-taking toolkit for your command line.

Posce

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.

• See changes.md for a complete changelog.
• See license.md for licensing information.

Table of Contents

• Installation
• Configuration
• Usage
• Commands
  • clip NAME
  • copy NAME DEST
  • drop NAME
  • dump FILE [-l]
  • edit NAME [-e]
  • find TERM [-r]
  • list [GLOB] [-rs]
  • make NAME [-f]
  • move NAME DEST
  • show NAME [-w]
  • wget NAME URL
• F.A.Q.
• Contribution

Installation

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

• Run pip install posce, or
• Download and install the latest release.

Configuration

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

Usage

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
alpha
bravo
charlie

$ posce show c
Charliiiiiiieeeeeee!

And you can abbreviate commands like this:

$ posce l
alpha
bravo
charlie

$ posce s c
Charliiiiiiieeeeeee!

I recommend aliasing posce to p for maximum brevity.

Commands

clip NAME

Copy the existing note NAME to the clipboard.

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

copy NAME DEST

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 notes.zip
# Create zip archive "notes.zip".

$ posce dump notes.zip --level 9
# Create "notes.zip" 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!"
charlie

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

list [GLOB] [-rs]

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

• -r --reverse: Reverse sorting order.
• -s --sort ATTR: Sort notes by one of these attributes:
  • name: Note name, alphabetically.
  • size: Note size in bytes.
  • time: Note file modification time.

$ posce list
alpha
bravo
charlie

$ posce list al*
alpha

$ posce list --reverse --sort name
charlie
bravo
alpha

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 NAME DEST

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.

wget NAME URL

Download a URL into the existing note NAME.

$ posce wget alpha example.com
# Download "https://example.com" and write contents to "alpha.txt".

F.A.Q.

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

Posce is one program using one codebase 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.

Contribution

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