nncli

NextCloud Notes Command Line Interface
git clone git://git.danielmoch.com/nncli.git
Log | Files | Refs | LICENSE

commit 8924cf801fc6398c0fd8ba27c59b0754d5682628
parent d45698defc78ce00f16c1964a596c49104c559b1
Author: Daniel Moch <daniel@danielmoch.com>
Date:   Mon, 30 Jul 2018 21:01:40 -0400

Fix README

Diffstat:
MREADME.md | 190++++++++++++++++++++++++++++++++++++++++++++++---------------------------------
1 file changed, 111 insertions(+), 79 deletions(-)

diff --git a/README.md b/README.md @@ -5,7 +5,7 @@ NextCloud Notes Command Line Interface nncli is a Python application that gives you access to your NextCloud Notes account via the command line. It's a fork of -[sncli](https://github.com/insanum/sncli) You can access your notes via +[sncli](https://github.com/insanum/sncli). You can access your notes via a customizable console GUI that implements vi-like keybinds or via a simple command line interface that you can script. @@ -20,7 +20,6 @@ Check your OS distribution for installation packages. ### Requirements * [Python 3](http://python.org) -* [pip](https://pip.pypa.io/en/stable/) * [Urwid](http://urwid.org) Python 3 module * [Requests](https://requests.readthedocs.org/en/master/) Python 3 module @@ -32,7 +31,7 @@ Check your OS distribution for installation packages. - `pip3 install nncli` * Manually: - Clone this repository to your hard disk: `git clone - https://github.com/insanum/nncli.git` + https://github.com/djmoch/nncli.git` - Install the requirements `pip3 install -r requirements.txt` - Install _nncli_: `python3 setup.py install` @@ -71,30 +70,37 @@ Check your OS distribution for installation packages. ### HowTo -``` Usage: nncli [OPTIONS] [COMMAND] [COMMAND_ARGS] - - OPTIONS: -h, --help - usage help -v, --verbose - - verbose output -n, --nosync - don't perform a server - sync -r, --regex - search string is a regular - expression -k <key>, --key=<key> - note key -t <title>, - --title=<title> - title of note for create (cli mode) -c <file>, - --config=<file> - config file to read from (defaults to ~/.nnclirc) - - COMMANDS: <none> - console gui mode when no - command specified sync - perform a full sync - with the server list [search_string] - list notes (refined with - search string) export [search_string] - export notes in JSON - (refined with search string) dump [search_string] - dump notes - (refined with search string) create [-] - create a - note ('-' content from stdin) import [-] - import a - note in JSON format ('-' JSON from stdin) export - - export a note in JSON format (specified by <key>) dump - - dump a note (specified by <key>) edit - edit a - note (specified by <key>) delete - delete - a note (specified by <key>) < favorite | unfavorite > - favorite/unfavorite a - - retrieve the category from a note (specified by <key>) cat set <category> - - set the category for a note (specified by <key>) - cat rm - remove category from a note (specified by <key>) ``` +``` +Usage: + nncli [OPTIONS] [COMMAND] [COMMAND_ARGS] + + OPTIONS: + -h, --help - usage help + -v, --verbose - verbose output + -n, --nosync - don't perform a server sync + -r, --regex - search string is a regular expression + -k <key>, --key=<key> - note key + -t <title>, --title=<title> - title of note for create (cli mode) + -c <file>, --config=<file> - config file to read from (defaults to + ~/.config/nncli/config) + + COMMANDS: + <none> - console gui mode when no command specified + sync - perform a full sync with the server + list [search_string] - list notes (refined with search string) + export [search_string] - export notes in JSON (refined with search string) + dump [search_string] - dump notes (refined with search string) + create [-] - create a note ('-' content from stdin) + import [-] - import a note in JSON format ('-' JSON from stdin) + export - export a note in JSON format (specified by <key>) + dump - dump a note (specified by <key>) + edit - edit a note (specified by <key>) + delete - delete a note (specified by <key>) + < favorite | unfavorite > - favorite/unfavorite a note (specified by <key>) + cat get - retrieve the category from a note (specified by <key>) + cat set <category> - set the category for a note (specified by <key>) + cat rm - remove category from a note (specified by <key>) +``` #### Configuration @@ -102,50 +108,63 @@ The current NextCloud Notes API does not support oauth authentication so your NextCloud Notes account information must live in the configuration file. Please be sure to protect this file. -nncli pulls in configuration from the `.nnclirc` file located in your -$HOME directory. At the very least, the following example `.nnclirc` -will get you going (using your account information): +nncli pulls in configuration from the `config` file located in your +$XDG_CONFIG_HOME/nncli directory. (By default, +XDG_CONFIG_HOME=$HOME/.config.) At the very least, the following example +`config` will get you going (using your account information): -``` [nncli] cfg_sn_username = lebowski@thedude.com cfg_sn_password = -nihilist ``` +``` +[nncli] +cfg_nn_username = lebowski@thedude.com +cfg_nn_password = nihilist +cfg_nn_host = nextcloud.thedude.com +``` Start nncli with no arguments which starts the console GUI mode. nncli -with start sync'ing all your existing notes and you'll see log messages -at the bottom of the console. You can view these log messages at any -time by pressing the `l` key. +will begin to sync your existing notes and you'll see log messages at +the bottom of the console. You can view these log messages at any time +by pressing the `l` key. View the help by pressing `h`. Here you'll see all the keybinds and configuration items. The middle column shows the config name that can be -used in your `.nnclirc` to override the default setting. +used in your `config` to override the default setting. See example configuration file below for more notes. -``` [nncli] cfg_sn_username = lebowski@thedude.com cfg_sn_password = -nihilist +``` +[nncli] +cfg_sn_username = lebowski@thedude.com +cfg_sn_password = nihilist -# as an alternate to cfg_sn_password you could use the following config -item # any shell command can be used; its stdout is used for the -password # trailing newlines are stripped for ease of use # note: if -both password config are given, cfg_sn_password will be used -cfg_sn_password_eval = gpg --quiet --for-your-eyes-only --no-tty ---decrypt ~/.nncli-pass.gpg +# as an alternate to cfg_sn_password you could use the following config item +# any shell command can be used; its stdout is used for the password +# trailing newlines are stripped for ease of use +# note: if both password config are given, cfg_sn_password will be used +cfg_sn_password_eval = gpg --quiet --for-your-eyes-only --no-tty --decrypt ~/.nncli-pass.gpg # see http://urwid.org/manual/userinput.html for examples of more key -combinations kb_edit_note = space kb_page_down = ctrl f - -# note that values must not be quoted clr_note_focus_bg = light blue - -# if this editor config value is not provided, the $EDITOR env var will -be used instead # warning: if neither $EDITOR or cfg_editor is set, it -will be impossible to edit notes cfg_editor = nvim - -# alternatively, {fname} and/or {line} are substituted with the filename -and # current line number in nncli's pager. # If {fname} isn't -supplied, the filename is simply appended. # examples: cfg_editor = -nvim {fname} +{line} cfg_editor = nano +{line} - -# this is also supported for the pager: cfg_pager = less -c +{line} -N -{fname} ``` +# combinations +kb_edit_note = space kb_page_down = ctrl f + +# note that values must not be quoted +clr_note_focus_bg = light blue + +# if this editor config value is not provided, the $EDITOR env var will be +# used instead +# warning: if neither $EDITOR or cfg_editor is set, it will be impossible to +# edit notes +cfg_editor = nvim + +# alternatively, {fname} and/or {line} are substituted with the filename and +# current line number in nncli's pager. +# If {fname} isn't supplied, the filename is simply appended. +# examples: +cfg_editor = nvim {fname} +{line} +cfg_editor = nano +{line} + +# this is also supported for the pager: +cfg_pager = less -c +{line} -N {fname} +``` #### Note Title Format @@ -155,9 +174,14 @@ supported for dynamically building the title string. Each of these formatting tags supports a width specifier (decimal) and a left justification (-) like that supported by printf: -``` %F - flags (fixed 5 char width) X - needs sync - * - favorited m - tags %D - date - %N - title ``` +``` +%F - flags (fixed 5 char width) + X - needs sync + * - favorited +%T - category +%D - date +%N - title +``` The default note title format pushes the note category to the far right of the terminal and left justifies the note title after the date and flags: @@ -174,7 +198,7 @@ the console user interface. At this time, nncli does not yet support 256-color terminals and is limited to just 16-colors. Color names that can be specified in the -`.nnclirc` file are listed +`config` file are listed [here](http://urwid.org/manual/displayattributes.html#standard-foreground-colors). ### Searching @@ -186,18 +210,19 @@ A Google style search string is a group of tokens (separated by spaces) with an implied *AND* between each token. This style search is case insensitive. For example: -``` /category:category1 category:category2 word1 "word2 word3" category:category3 ``` +`/category:category1 category:category2 word1 "word2 word3" category:category3` Regular expression searching also supports the use of flags (currently only case-insensitive) by adding a final forward slash followed by the flags. The following example will do a case-insensitive search for `something`: -``` (regex) /something/i ``` +`(regex) /something/i` ### Creating from command line -``` # create a new note and open in editor nncli create +``` +# create a new note and open in editor nncli create # create a new note with contents of stdin echo 'hi' | nncli create - ``` @@ -207,7 +232,7 @@ flags. The following example will do a case-insensitive search for nncli can import notes from raw json data (via stdin or editor). For example: -``` echo '{"category":"testing","content":"New note!"}' | nncli import - ``` +`echo '{"category":"testing","content":"New note!"}' | nncli import - ` Allowed fields are `content`, `category`, `favorite`, and `modified` @@ -215,12 +240,16 @@ Allowed fields are `content`, `category`, `favorite`, and `modified` nncli can export notes as json data to stdout. Example: -``` # export a single note by id nncli -k somekeyid export +``` +# export a single note by id +nncli -k somekeyid export -# export all notes nncli export +# export all notes +nncli export -# export notes matching search string nncli [-r] export some search -keywords or regex ``` +# export notes matching search string +nncli [-r] export some search keywords or regex +``` Note that nncli still stores all the notes data in the directory specified by `cfg_db_path`, so for easy backups, it may be @@ -230,7 +259,8 @@ easier/quicker to simply backup this entire directory. Note category can be modified directly from the command line. Example: -``` # Retrieve note category (e.g. "category1") +``` +# Retrieve note category (e.g. "category1") nncli -k somekeyid cat get # Returns "category1" @@ -241,13 +271,14 @@ nncli -k somekeyid cat set "category3" # Remove a category from a note nncli -k somekeyid cat rm # Note now has no category - +``` ### Tricks -I personally store a lot of my notes in -[Votl/VimOutliner](https://github.com/insanum/votl) format. Specific to -Vim, I put a modeline at the end of these notes (note that Emacs also -supports modelines): +Advanced text editors usually tailor their behavior based on the file +type being edited. For such editors, notes opened through nncli should +be treated as Markdown by default. However, you can change this +on a per-note basis through the use of modelines. In Vim, for instance, +a modeline is a comment line conforming to the pattern below. ``` ; vim:ft=votl ``` @@ -256,10 +287,11 @@ Lots of possibilities here... ### Thanks -This application pulls in and uses the +nncli is a fork of [sncli](https://github.com/insanum/sncli) by +[insanum](https://github.com/insanum). This application further pulls in +and uses modified versions of the [simplenote.py](https://github.com/mrtazz/simplenote.py) module by [mrtazz](https://github.com/mrtazz) and the [notes_db.py](https://github.com/cpbotha/nvpy/blob/master/nvpy/notes_db.py) module from [nvpy](https://github.com/cpbotha/nvpy) by [cpbotha](https://github.com/cpbotha). -