Commands

We detail here most of wwid’s commands and provide some usage examples. For an exhaustive list, including command aliases, please see the built-in help text with wwid --help.

Editing notes interactively

The most important subcommand is edit. Given a target, it’ll resolve the attached note and open that in your configured editor. Relative and absolute paths all work, as long as they resolve to a path inside the right project:

# note for the CWD
wwid edit .
# relative path
wwid edit ../Cargo.toml
# absolute path
wwid edit ~/foo/bar/src/main.rs

A common workflow may be to keep a general, project-wide task list attached to the root, while more granular reminders and implementation details may be linked to files. To make this use case more convenient, running wwid without any subcommand opens the root note for the current project. In other words, given a project located at /foo/bar, the following commands are equivalent:

# assuming $PWD = /foo/bar
wwid
wwid edit /foo/bar
wwid edit .

Editing notes non-interactively

Notes can be read and written to via the standard input & output streams.

Notes’ contents can be printed to standard output with the print command:

wwid print src/main.rs
# or omit target to print the root note
wwid print

The write command does what you expect. It takes some input and writes it to the given note (the root note if omitted). Much like the interactive edit, the note is created if it doesn’t yet exist; and overwritten otherwise.

Using standard input:

echo "TODO: learn to use wwid" | wwid write

Alternatively, the input can be given on the command line with an option. If it’s set, standard input will be ignored:

wwid write src/main.rs --content "TODO: clean this file up"

These two commands enable a number of workflows involving pipelines & filter commands, and also make text editor integrations/plugins easy to write. For example, let’s use sed to replace all occurrences of TODO with DONE in a note:

wwid print foo/bar | sed 's/TODO/DONE/g' | wwid write foo/bar

Deleting notes

There is a command to delete a note by its target:

wwid remove src/main.rs

The command will prompt you for confirmation. To do it non-interactively, set a flag:

wwid remove --force src/main.rs

Finally, using any method to edit a note’s body to be empty (only whitespace) automatically deletes it as well.

Querying the current project

We provide commands for querying some information with the current project. You can see information like the current project’s ID and hint, the locations of its data & config files, etc:

wwid status

You can also list the notes that exist inside this project. This will also show you which notes are orphaned or empty:

wwid list

Pruning

There is a command for pruning (or cleaning up) unneeded notes from the current project. An unneeded note is one whose body is empty, or an orphan (a note whose “owned” file/directory no longer exists.)

wwid prune

Like remove, the prune command prompts you for confirmation of each note before deleting it. To bypass it, pass the same flag as before:

wwid prune --force

Project commands

There is a small set of projects subcommands, which can operate on specific projects (not just the current one). You can list all available projects, including their metadata:

wwid projects list

Additionally, you can remove an entire project, including all of its notes. This is a highly destructive action, so it cannot be performed directly on the current project; the project ID must be specified. Like the other deletion commands, confirmation is prompted for, which can be bypassed with a flag.

wwid projects remove my-project-1
wwid projects remove --force another-proj-1