Usage¶

General Subcommand Options¶

When nncli is run without any options or arguments, an interactive console GUI will appear. The appearance and behavior of the GUI may be customized through a configuration file, described elsewhere.

In addition to this default behavior, there are several options available when calling nncli without a subcommand.

--help, -h¶: Displays a brief decription of the nncli options and subcommands.

--version, -V¶: Displays version information.

--config, -c¶: Specify the config file to read from. This option is only required to override the default location.

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.

Common Subcommand Options¶

In addition to the global options, several nncli options apply to multiple subcommands. They are:

--verbose, -v¶: Print verbose logging information to stdout.

--nosync, -n¶: Operate only on the local notes cache. Do not reach out to the server.

--regex, -r¶: For subcommands that accept a search string, treat the search string as a regular expression.

--key, -k¶: The ID of the note to operate on. This option is required for many subcommands.

nncli sync¶

Command format: nncli sync

nncli sync performs a full, bi-directional sync between the local notes cache and the NextCloud Notes server. The command accepts no options or arguments.

nncli list¶

Command format: nncli list [options] [search_string]

nncli list lists 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 (*). If search_string is provided, it is used to filter the list of notes.

Options are as follows:

--regex, -r¶: Treat the search_string as a regular expression.

nncli export¶

Command format: nncli export [options] [search_string]

nncli export 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. If search_string is specified, it is used to filter the notes prior to export.

Note

nncli already stores all notes locally in the cache directory, so for easy backups, it may be easier/quicker to simply backup this entire directory.

Options are as follows:

--regex, -r¶: Treat search_string as a regular expression. Mutually exclusive with –key.

--key, -k¶: The ID of the note to operate on.

Example:

# export a single note by id
$ nncli -k somekeyid export

# export all notes
$ nncli export

# export notes matching search string
$ nncli [-r] export "some search keywords or regex"

nncli dump¶

Command format: nncli dump [search_string]``

nncli dump dumps 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 (*). If search_string is specified, it is used to filter the notes prior to export.

Options are as follows:

--regex, -r¶: Treat search_string as a regular expression. Mutually exclusive with –key.

--key, -k¶: The ID of the note to operate on.

nncli create¶

Command format: program:nncli create [-]

Example:

# create a new note and open in editor
$ nncli create

# create a new note with contents of stdin
$ echo 'hi' | nncli create -

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. If - is specified, the note content is read from stdin. The note syncs to the server after the command completes.

Example:

$ echo '{"category":"testing","content":"New note!"}' \
     | nncli import -

nncli edit¶

Command format: nncli [–key|-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.

Options are as follows:

--key, -k¶: The ID of the note to operate on.

nncli delete¶

Command format: nncli [–key|-k] KEY delete

Delete the note specified by KEY.

Options are as follows:

--key, -k¶: The ID of the note to operate on.

nncli favorite¶

Command format: nncli –key|-k KEY favorite|unfavorite

Favorite (or unfavorite) the note specified by KEY.

Options are as follows:

--key, -k¶: The ID of the note to operate on.

nncli cat¶

Command format: nncli –key|-k KEY cat get|set|rm [category_name]

Modify a note category from the command line. With the get argument, the command returns the note category. With the set argument, the note category is set to the required category_name argument. With the rm argument, the note’s category is removed.

Options are as follows:

--key, -k¶: The ID of the note to operate on.

Example:

# Retrieve note category (e.g. "category1")
$ nncli -k 42 cat get
category1

# Add a category to a note, overwriting any existing one
nncli -k 42 cat set "category3"

# Remove a category from a note
nncli -k 42 cat rm

Console GUI Usage¶

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:

/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

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=rst

Now when you edit this note Vim will automatically load the rst plugin.