zorg

The zettel note manager of the future.

project status badges:

CI Workflow Coverage Documentation Status Package Health

version badges:

Project Version Python Versions Cookiecutter: cc-python Docker: pythonboltons/main

Installation 🗹

Using pipx to Install (preferred)

This package could be installed using pip like any other Python package (in fact, see the section below this one for instructions on how to do just that). Given that we only need this package’s entry points, however, we recommend that pipx be used instead:

# install and setup pipx
python3 -m pip install --user pipx
python3 -m pipx ensurepath

# install zorg
pipx install zettel-org

Using pip to Install

To install zorg using pip, run the following commands in your terminal:

python3 -m pip install --user zettel-org  # install zorg

If you don’t have pip installed, this Python installation guide can guide you through the process.

Command-Line Interface (CLI)

The following subsections have been auto-generated using cog:

zorg --help

``` usage: zorg [-h] [-c CONFIG_FILE] [-L [FILE[:LEVEL][@FORMAT]]] [-v] [--version] [-d ZETTEL_DIR] {action,compile,db,edit,file,note,query,template} ... The zettel note manager of the future. options: -c CONFIG_FILE, --config CONFIG_FILE Absolute or relative path to a YAML file that contains this application's configuration. -d ZETTEL_DIR, --dir ZETTEL_DIR The directory where all of your notes are stored. -h, --help show this help message and exit -L [FILE[:LEVEL][@FORMAT]], --log [FILE[:LEVEL][@FORMAT]] This option can be used to enable a new logging handler. FILE should be either a path to a logfile or one of the following special file types: [1] 'stderr' to log to standard error (enabled by default), [2] 'stdout' to log to standard out, [3] 'null' to disable all console (e.g. stderr) handlers, or [4] '+[NAME]' to choose a default logfile path (where NAME is an optional basename for the logfile). LEVEL can be any valid log level (i.e. one of ['CRITICAL', 'DEBUG', 'ERROR', 'INFO', 'TRACE', 'WARNING']) and FORMAT can be any valid log format (i.e. one of ['color', 'json', 'nocolor']). NOTE: This option can be specified multiple times and has a default argument of '+'. -v, --verbose How verbose should the output be? This option can be specified multiple times (e.g. -v, -vv, -vvv, ...). --version show program's version number and exit subcommands: {action,compile,db,edit,file,note,query,template} action Used to interface with vim via an action protocol. compile Compiles zorg (*.zo) files into zorc (*.zoc) files. db Commands for managing Zorg's SQL database. edit Generate new day logs from templates and open the main day log in your system's editor. This is the default subcommand. file Commands for managing files. note Commands for managing individual notes. query Run a zorg query against your zettel directory. template Commands for managing .zot templates. ``` ### `zorg action --help` ``` usage: zorg action [-h] {open} ... Used to interface with vim via an action protocol. options: -h, --help show this help message and exit subcommands: {open} open Open a zettel link if one exists on the provided zorg file line. ``` ### `zorg action open --help` ``` usage: zorg action open [-h] zo_path line_number [option_idx] Open a zettel link if one exists on the provided zorg file line. positional arguments: line_number The line number that your editor cursor is currently located on. option_idx Used on a second 'action open' run to indicate which option was selected. zo_path The file that your editor currently has open. options: -h, --help show this help message and exit ``` ### `zorg compile --help` ``` usage: zorg compile [-h] zo_path Compiles zorg (*.zo) files into zorc (*.zoc) files. positional arguments: zo_path Path to the zorg file you want to compile. options: -h, --help show this help message and exit ``` ### `zorg db --help` ``` usage: zorg db [-h] {create,reindex} ... Commands for managing Zorg's SQL database. options: -h, --help show this help message and exit subcommands: {create,reindex} create Create zorg's backend database from scratch. reindex Reindex any changed files by adding them to the database. ``` ### `zorg db create --help` ``` usage: zorg db create [-h] [-f] Create zorg's backend database from scratch. options: -h, --help show this help message and exit -f, --update-error-file-whitelist If this option is NOT provided, any errors in Zorg files that are NOT already in the error file whitelist will cause Zorg to abort database creation. ``` ### `zorg db reindex --help` ``` usage: zorg db reindex [-h] [paths ...] Reindex any changed files by adding them to the database. positional arguments: paths Reindex these specific paths. If this argument is not provided, we use a hashing approach to check which files have changed. options: -h, --help show this help message and exit ``` ### `zorg edit --help` ``` usage: zorg edit [-h] [zo_paths ...] Generate new day logs from templates and open the main day log in your system's editor. This is the default subcommand. positional arguments: zo_paths The .zo files we want to open in an editor. options: -h, --help show this help message and exit ``` ### `zorg file --help` ``` usage: zorg file [-h] {rename} ... Commands for managing files. options: -h, --help show this help message and exit subcommands: {rename} rename Rename a file. ``` ### `zorg file rename --help` ``` usage: zorg file rename [-h] src_name dest_name Rename a file. positional arguments: dest_name The destination filename. src_name The source filename. options: -h, --help show this help message and exit ``` ### `zorg note --help` ``` usage: zorg note [-h] {move} ... Commands for managing individual notes. options: -h, --help show this help message and exit subcommands: {move} move Move a note to a different page. ``` ### `zorg note move --help` ``` usage: zorg note move [-h] zid new_page [note_type] Move a note to a different page. positional arguments: new_page Path to the destination page (i.e. where our note will be moved to). note_type If provided, this argument specifies a new note type for the moved note. This can be used, for example, to mark an OPEN todo as DONE before moving it to a file dedicated to done todos. Valid values: ['x', '~'] zid ZID of the note we want to move. options: -h, --help show this help message and exit ``` ### `zorg query --help` ``` usage: zorg query [-h] [-e] [-s] query Run a zorg query against your zettel directory. positional arguments: query The zorg query we will run. options: -h, --help show this help message and exit -e, --open-in-editor Store query results in a temporary Zorg query page and then open this page in an editor. -s, --store-in-file Store query results in temporary Zorg query page and then print that page's file path to STDOUT. ``` ### `zorg template --help` ``` usage: zorg template [-h] {init,list,render} ... Commands for managing .zot templates. options: -h, --help show this help message and exit subcommands: {init,list,render} init Initialize a new file using a zorg template. list List all zorg template files. render Render a new .zo file using a .zot template. ``` ### `zorg template init --help` ``` usage: zorg template init [-h] [-f] [-t TEMPLATE] new_path [variables ...] Initialize a new file using a zorg template. positional arguments: new_path Path to the new file you would like to create. variables A list of variable specs of the form of key=value. options: -f, --force Overwrite target file if the file already exists. -h, --help show this help message and exit -t TEMPLATE, --template TEMPLATE Optional path to the .zot template. If a template is not provided, we will infer what template to use based off of the new file's name. ``` ### `zorg template list --help` ``` usage: zorg template list [-h] List all zorg template files. options: -h, --help show this help message and exit ``` ### `zorg template render --help` ``` usage: zorg template render [-h] template [variables ...] Render a new .zo file using a .zot template. positional arguments: template Path to the .zot template. variables A list of variable specs of the form of key=value. options: -h, --help show this help message and exit ```