nncli

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

commit 033fc475c36603d5e35054020d43709c40e9c58f
parent 595ac1fa07b34ccebaef5b443fef684378150caa
Author: Daniel Moch <daniel@danielmoch.com>
Date:   Fri, 31 Aug 2018 07:06:14 -0400

Expand usage documentation

Diffstat:
Mdocs/source/configuration.rst | 7+++++++
Mdocs/source/usage.rst | 372+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++----------------
2 files changed, 304 insertions(+), 75 deletions(-)

diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst @@ -1,3 +1,5 @@ +.. _configuration: + Configuration ============= @@ -6,6 +8,11 @@ your NextCloud Notes account password must be stored someplace accessible to nncli. Use of the ``cfg_nn_password_eval`` option is recommended (see below). +.. _config-file: + +Configuration File +------------------ + nncli pulls in configuration from the ``config`` file located in the standard location for your platform. At the very least, the following example ``config`` will get you going (using your account information): diff --git a/docs/source/usage.rst b/docs/source/usage.rst @@ -1,90 +1,149 @@ Usage ===== -.. index:: single: 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 - --version - version information - - 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>) +.. program:: nncli -.. index:: single: searching +When ``nncli`` is run without any options or arguments an interactive +console GUI will appear. The behavior of this interface is highly +configurable (see: :ref:`configuration`). -Searching ---------- +In addition to this default behavior, there are several options +available when calling ``nncli`` without a subcommand. -nncli supports two styles of search strings. First is a Google style -search string and second is a Regular Expression. +.. option:: --help, -h -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:: +Displays a brief decription of the ``nncli`` options and subcommands. - /category:category1 category:category2 word1 "word2 word3" category:category3 +.. option:: --version, -V -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``:: +Displays the version information. - (regex) /something/i +Also available when calling ``nncli`` by itself is the ``--config`` +option, for which see: :ref:`general-options`. -.. index:: single: command line; creating +Subcommands +----------- -Creating from command line --------------------------- +There are a variety of subcommands available from the command line when +using ``nncli``. The intent is for these subcommands to enable +scripting against your NextCloud Notes database. The subcommands are: -:: - # create a new note and open in editor - nncli create +- sync - # create a new note with contents of stdin - echo 'hi' | nncli create - +- list -.. index:: single: command line; importing +- export -Importing ---------- +- dump -nncli can import notes from raw json data (via stdin or editor). For -example:: +- create - echo '{"category":"testing","content":"New note!"}' | nncli import - +- import + +- edit + +- delete + +- (un)favorite + +- cat {get,set,rm} + +These subcommands and the options available to them are described below. + +.. _general-options: + +General Subcommand Options +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Several ``nncli`` options apply to multiple subcommands. They are: + +.. option:: --verbose, -v + +Print verbose logging information to ``stdout`` + +.. option:: --nosync, -n + +Operate only on the local notes cache. Do not reach out to the server. + +.. option:: --regex, -r + +For subcommands that accept a search string, treat the search string as +a regular expression. + +.. option:: --key, -k + +The ID of the note to operate on. This option is required for many of +the subcommands. + +.. option:: --config, -c + +Specify the config file to read from. This option is only required to +override the default location (see: :ref:`config-file`). + +nncli sync +~~~~~~~~~~ + +.. program:: nncli sync -Allowed fields are ``content``, ``category``, ``favorite``, and ``modified`` +Command format: ``nncli sync`` -.. index:: single: command line; exporting +Performs a full, bi-directional sync between the local notes cache and +the NextCloud Notes server. There are no available options for this +subcommand. -Exporting ---------- +- Available options: None -nncli can export notes as json data to stdout. Example:: +- Arguments: None + +nncli list +~~~~~~~~~~ + +.. program:: nncli list + +Command format: ``nncli list [search_string]`` + +List notes by ID, flags, and title. Flags indicate whether the note has +been modified locally (``X``), and/or if it is marked as a favorite +(``*``). + +- Available options: + + - ``--regex, -r`` See :ref:`general-options` + +- Arguments: + + - ``search_string`` Optional. A search term used to refine the search. + +nncli export +~~~~~~~~~~~~ + +.. program:: nncli export + +Command format: ``nncli export [search_string]`` + +Exports notes in raw, JSON format. The JSON format is a superset of the +format outlined in the NextCloud Notes API specification with +information added for managing the local notes cache. Note that nncli +still stores all the notes data in the directory specified by +``cfg_db_path``, so for easy backups, it may be easier/quicker to simply +backup this entire directory. + +- Available options: + + - :ref:`general-options` + + - ``--regex, -r`` Mutually exclusive with ``--key`` + + - ``--key, -k`` + +- Arguments: + + - ``search_string`` Required if ``--regex`` is specified. A search + term used to refine the search. + +Example: + +.. code-block:: sh # export a single note by id nncli -k somekeyid export @@ -95,16 +154,151 @@ nncli can export notes as json data to stdout. Example:: # 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 -easier/quicker to simply backup this entire directory. +nncli dump +~~~~~~~~~~ + +.. program:: nncli dump + +Command format: ``nncli dump [search_string]`` + +Prints notes to ``stdout``. The printed format is the text of the note +preceeded by a header displaying information about the note title, key, +modified date, category, and flags. Flags indicate whether the note has +been modified locally (``X``), and/or if it is marked as a favorite +(``*``). + +- Available options: + + - :ref:`general-options` + + - ``--regex, -r`` Mutually exclusive with ``--key`` + + - ``--key, -k`` + +- Arguments: + + - ``search_string`` Required if ``--regex`` is specified. A search + term used to refine the search. + +nncli create +~~~~~~~~~~~~ + +.. program:: nncli create + +Command format: ``nncli create [-]`` + +Create a note. Without arguments, this command will open your configured +editor. The note syncs to the server after the editor is closed. + +- Available options: None + +- Arguments: -.. index:: single: command line; categories + - `-` Optional. If specified, the note content is read from ``stdin``. -Categories ----------- +Example: -Note category can be modified directly from the command line. Example:: +.. code-block:: sh + + # create a new note and open in editor + nncli create + + # create a new note with contents of stdin + echo 'hi' | nncli create - + +nncli import +~~~~~~~~~~~~ + +.. program:: nncli import + +Command format: ``nncli import [-]`` + +Import a JSON-formatted note. nncli can import notes from raw json data +(via stdin or editor). Allowed fields are ``content``, ``category``, +``favorite``, and ``modified``. + +- Available options: None + +- Arguments: + + - ``-`` Optional. If specified, the note content is read from ``stdin``. + +Example: + +.. code-block:: none + + echo '{"category":"testing","content":"New note!"}' | nncli import - + +nncli edit +~~~~~~~~~~ + +.. program:: nncli edit + +Command format: ``nncli -k <key> edit`` + +Open the note specified by ``<key>`` in the configured editor. The note +syncs to the server after the editor is saved and closed. + +- Available options: + + - ``--key, -k`` Required. See :ref:`general-options` + +- Arguments: None + +nncli delete +~~~~~~~~~~~~ + +.. program:: nncli delete + +Command format: ``nncli -k <key> delete`` + +Delete the note specified by ``<key>``. + +- Available options: + + - ``--key, -k`` Required. See :ref:`general-options` + +- Arguments: None + +nncli favorite +~~~~~~~~~~~~~~ + +.. program:: nncli favorite + +Command format: ``nncli -k <key> favorite|unfavorite`` + +Favorite (or unfavorite) the note specified by ``<key>``. + +- Available options: + + - ``--key, -k`` Required. See :ref:`general-options` + +- Arguments: None + +nncli cat +~~~~~~~~~ + +.. program:: nncli cat + +Command format: ``nncli -k <key> cat get|set|rm`` + +Read or modify a note category from the command line. + +- Available options: + + - ``--key, -k`` Required. See :ref:`general-options` + +- Arguments: + + - ``get`` Get the note category + + - ``set`` Set the note category + + - ``rm`` Remove the note category + +Example: + +.. code-block:: sh # Retrieve note category (e.g. "category1") nncli -k somekeyid cat get @@ -118,10 +312,38 @@ Note category can be modified directly from the command line. Example:: nncli -k somekeyid cat rm # Note now has no category -.. index:: single: tricks +Console GUI Usage +----------------- + +.. index:: single: searching + +Searching +~~~~~~~~~ + +nncli supports two styles of search strings. First is a Google style +search string and second is a Regular Expression. + +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: + +.. code-block:: none + + /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``: + +.. code-block:: none + + (regex) /something/i + +.. index:: single: modelines -Tricks ------- +Modelines +~~~~~~~~~ Advanced text editors usually tailor their behavior based on the file type being edited. For such editors, notes opened through nncli should