nncli

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

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

Expand usage documentation (WIP)

Diffstat:
Mdocs/source/configuration.rst | 7+++++++
Mdocs/source/usage.rst | 236++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++---------------
2 files changed, 200 insertions(+), 43 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,50 +1,193 @@ 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 + +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`). + +In addition to this default behavior, there are several options +available when calling ``nncli`` without a subcommand. + +.. option:: --help, -h + +Displays a brief decription of the ``nncli`` options and subcommands. + +.. option:: --version, -V + +Displays the version information. + +Also available when calling ``nncli`` by itself is the ``--config`` +option, for which see: :ref:`general-options`. + +Subcommands +----------- + +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: + +- sync + +- list + +- export + +- dump + +- create + +- 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 + +Command format: ``nncli sync`` + +Performs a full, bi-directional sync between the local notes cache and +the NextCloud Notes server. There are no available options for this +subcommand. + +- Available options: None + +- 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. + +- Available options: + + - ``--regex, -r`` See :ref:`general-options` + +- Arguments: + + - ``search_string`` Optional. A search term used to refine the search. + +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: + + - ``--regex, -r`` See :ref:`general-options` + +- Arguments: + + - ``search_string`` Optional. A search term used to refine the search. + +nncli create +~~~~~~~~~~~~ + +nncli import +~~~~~~~~~~~~ + +nncli edit +~~~~~~~~~~ + +nncli delete +~~~~~~~~~~~~ + +nncli favorite +~~~~~~~~~~~~~~ + +nncli cat +~~~~~~~~~ + +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:: +insensitive. For example: + +.. code-block:: none /category:category1 category:category2 word1 "word2 word3" category:category3 @@ -58,9 +201,10 @@ flags. The following example will do a case-insensitive search for .. index:: single: command line; creating Creating from command line --------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: sh -:: # create a new note and open in editor nncli create @@ -70,10 +214,12 @@ Creating from command line .. index:: single: command line; importing Importing ---------- +~~~~~~~~~ nncli can import notes from raw json data (via stdin or editor). For -example:: +example: + +.. code-block:: none echo '{"category":"testing","content":"New note!"}' | nncli import - @@ -82,9 +228,11 @@ Allowed fields are ``content``, ``category``, ``favorite``, and ``modified`` .. index:: single: command line; exporting Exporting ---------- +~~~~~~~~~ -nncli can export notes as json data to stdout. Example:: +nncli can export notes as json data to stdout. Example: + +.. code-block:: sh # export a single note by id nncli -k somekeyid export @@ -102,9 +250,11 @@ easier/quicker to simply backup this entire directory. .. index:: single: command line; categories Categories ----------- +~~~~~~~~~~ + +Note category can be modified directly from the command line. Example: -Note category can be modified directly from the command line. Example:: +.. code-block:: sh # Retrieve note category (e.g. "category1") nncli -k somekeyid cat get @@ -121,7 +271,7 @@ Note category can be modified directly from the command line. Example:: .. index:: single: tricks Tricks ------- +~~~~~~ Advanced text editors usually tailor their behavior based on the file type being edited. For such editors, notes opened through nncli should