nncli.config(5)¶

The current NextCloud Notes API does not support OAuth authentication so your NextCloud Notes account password must be stored someplace accessible to nncli.

Configuration File¶

nncli pulls in configuration from the config file located in the standard location for your platform:

macOS: $HOME/Library/Preferences/nncli

Linux/BSD: $XDG_CONFIG_HOME/nncli/config or $HOME/.config/nncli/config

The following directives are accepted within the config file:

General Options¶

cfg_nn_host

Sets the URL of the NextCloud instance to connect to.

Required.

cfg_nn_username

The user name to log in as.

Required.

cfg_nn_password

The password to use for log in.

Optional. Overrides cfg_nn_password_eval if both are specified.

Note

For security reasons, use of the cfg_nn_password_eval option is recommended

cfg_nn_password_eval

A command to run to retrieve the password. The command should return the password on stdout.

Optional. Required if cfg_nn_password is not specified.

cfg_db_path

Specifies the path of the local notes cache.

Optional. Default value:

Windows: %USERPROFILE%\AppData\Local\djmoch\nncli\Cache
macOS: ~/Library/Caches/nncli
*nix: $XDG_CACHE_HOME/nncli or $HOME/.cache/nncli

cfg_search_categories

Set to yes to include categories in searches. Otherwise set to no.

Optional. Default value: yes

cfg_sort_mode

Sets how notes are sorted in the console GUI. Set to date to have them sorted by date (newest on top). Set to alpha to have them sorted alphabetically.

Optional. Default value: date

cfg_favorite_ontop

Determines whether notes marked as favorite are sorted on top.

Optional. Default value: yes

cfg_tabstop

Sets the width of a tabstop character.

Optional. Default value: 4

cfg_format_strftime

Sets the format of the note timestamp (%D) in the note title. The format values are the specified in time.strftime().

Optional. Default value: %Y/%m/%d

cfg_format_note_title

Sets the format of each line in the console GUI note list. Various formatting tags are 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 2 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.

Optional. Default value: [%D] %F %-N %T

Note that the %D date format is further defined by the strftime format specified in cfg_format_strftime.

cfg_status_bar

Sets whether or not the status bar is visible at the top of the console GUI.

Optional. Default value: yes

cfg_editor

Sets the command to run when opening a note for editing. The special values {fname} and {line} can be used to specify respectively the file name and line number to pass to the command.

Optional. Default value: $VISUAL or $EDITOR if defined in the user’s environment (preferring $VISUAL), else vim {fname} +{line}.

cfg_pager

Sets the command to run when opening a note for viewing in an external pager.

Optional. Default value: $PAGER if defined in the user’s environment, else less -c.

cfg_max_logs

Sets the number of log events to display together in the consule GUI footer.

Optional. Default value: 5

cfg_log_timeout

Sets the rate to poll for log events. Unit is seconds.

Optional. Default value: 5

cfg_log_reversed

Sets whether or not the log is displayed in reverse-chronological order.

Optional. Default value: yes

cfg_tempdir

Sets a directory path to store temporary files in. nncli uses tempfile.mkstemp() under the hood, and the most nuanced description of how this value is used can be found in the discussion of the dir keyword argument there. Basically you should not specify this if you want to use the platform-standard temporary folder.

Optional. Default value: [blank]

Keybindings¶

Keybindings specify the behavior of the console GUI, and are never required in the config file. However, they all have default values, as outlined below. More information on specifying keybindings can be found in the Urwid documentation.

kb_help

Press to enter the help screen.

Default value: h

kb_quit

Press to exit the console GUI.

Default value: q

kb_sync

Press to force a full, bi-directional sync with the server.

Default value: S

kb_down

Press to move down one row.

Default value: j

kb_up

Press to move one row up.

Default value: k

kb_page_down

Press to move one page down.

Default value: space

kb_page_up

Press to move one page up.

Default value: b

kb_half_page_down

Press to move one half-page down.

Default value: ctrl d

kb_half_page_up

Press to move one half-page up.

Default value: ctrl u

kb_bottom

Press to move to the last line.

Default value: G

kb_top

Press to move to the first line.

Default value: g

kb_status

Press to toggle the visibility of the status bar.

Default value: s

kb_create_note

Press to create a new note and open in the configured editor (see cfg_editor).

Default value: C

kb_edit_note

Press to edit the highlighted note in the configured editor (see cfg_editor).

Default value: e

kb_view_note

Press to view the highlighted note in read-only mode.

Default value: enter

kb_view_note_ext

Press to view the highlighted note in the configured pager (see cfg_pager).

Default value: meta enter

kb_view_note_json

Press to view the raw JSON contents of the highlighted note in read-only mode.

Default value: O

kb_pipe_note

Press to send the contents of the highlighted note to stdin of another program. A small command window opens at the bottom of the screen to enter the desired program.

Default value: |

kb_view_next_note

Press to view the contents of the next note in read-only mode.

Default value: J

kb_view_prev_note

Press to view the contents of the previous note in read-only mode.

Default value: K

kb_view_log

Press to view the log.

Default value: l

kb_tabstop2

Press to set the tabstop for the internal pager to a width of two characters.

Default value: 2

kb_tabstop4

Press to set the tabstop for the internal pager to a width of four characters.

Default value: 4

kb_tabstop8

Press to set the tabstop for the internal pager to a width of eight characters.

Default value: 8

kb_search_gstyle

Press to initiate a search of your notes against a Google-style search term. A command window will open at the bottom of the screen to enter your search term.

Default value: /

kb_search_regex

Press to initiate a search of your notes against a regular expression. A command window will open at the bottom of the screen to enter your search term.

Default value: meta /

kb_search_prev_gstyle

Press to initiate a reverse search of your notes against a Google-style search term. A command window will open at the bottom of the screen to enter your search term.

Default value: ?

kb_search_prev_regex

Press to initiate a reverse search of your notes against a regular expression. A command window will open at the bottom of the screen to enter your search term.

Default value: meta ?

kb_search_next

Press after a search has been initiated to move to the next match.

Default value: n

kb_search_prev

Press after a search has been initiated to move to the previous match.

Default value: N

kb_clear_search

Press to clear the current search.

Default value: A

kb_sort_date

Press to display notes sorted by date.

Default value: d

kb_sort_alpha

Press to display notes sorted alphabetically.

Default value: a

kb_sort_categories

Press to display notes sorted by category.

Default value: ctrl t

kb_note_delete

Press to delete a note. The note will be deleted locally and reflected on the server after the next full sync (see kb_sync).

Default value: D

kb_note_favorite

Press to toggle the favorite flag for a note.

Default value: p

kb_note_category

Press to set/edit the note category. A command window will appear at the bottom of the screen containing the current category (if it has one). Set to an empty string to clear the category.

Default value: t

kb_copy_note_text

Press to copy the note text to the system clipboard.

Default value: y

Colors¶

Note

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 config file are listed in the Urwid manual.

The following pairs of configuration values represent the foreground and background colors for different elements of the console GUI. In each case the configuration value corresponding to the foreground color ends in _fg, and the configuration value corresponding to the background color ends in _bg. The default color values are listed in foreground/background format.

clr_default_fg

clr_default_bg

The default foreground/background colors.

Default values: default/default

clr_status_bar_fg

clr_status_bar_bg

The foreground/background colors for the status bar.

Default values: dark gray/light gray

clr_log_fg

clr_log_bg

The foreground/background colors for the log.

Default values: dark gray/light gray

clr_user_input_bar_fg

clr_user_input_bar_bg

The foreground/background colors for the input bar.

Default values: white/light red

clr_note_focus_fg

clr_note_focus_bg

The foreground/background colors for the selected note.

Default values: white/light red

clr_note_title_day_fg

clr_note_title_day_bg

The foreground/background colors for notes edited within the past 24 hours.

Default values: light red/default

clr_note_title_week_fg

clr_note_title_week_bg

The foreground/background colors for notes edited within the past week,

Default values: light green/default

clr_note_title_month_fg

clr_note_title_month_bg

The foreground/background colors for notes edited within the past month.

Default values: brown/default

clr_note_title_year_fg

clr_note_title_year_bg

The foreground/background colors for notes edited within the past year.

Default values: light blue/default

clr_note_title_ancient_fg

clr_note_title_ancient_bg

The foreground/background colors for notes last edited more than one year ago.

Default values: light blue/default

clr_note_date_fg

clr_note_date_bg

The foreground/background colors for the note date (i.e. the %D portion of cfg_format_note_title).

Default values: dark blue/default

clr_note_flags_fg

clr_note_flags_bg

The foreground/background colors for the note flags (i.e., the %F portion of cfg_format_note_title).

Default values: dark magenta/default

clr_note_category_fg

clr_note_category_bg

The foreground/background colors for the note category (i.e., the %T portion of cfg_format_note_title).

Default values: dark red/default

clr_note_content_fg

clr_note_content_bg

The foreground/background colors for the note content as displayed in the internal pager.

Default values: default/default

clr_note_content_focus_fg

clr_note_content_focus_bg

The foreground/background colors for focused content within the internal pager.

Default values: white/light red

clr_note_content_old_fg

clr_note_content_old_bg

The foreground/background colors for old note content as displayed within the internal pager.

Default values: yellow/dark gray

clr_note_content_old_focus_fg

clr_note_content_old_focus_bg

The foreground/background colors for old note focused content as displayed within the internal pager.

Default values: white/light red

clr_help_focus_fg

clr_help_focus_bg

The foreground/background colors for focused content in the help screen.

Default values: white/light red

clr_help_header_fg

clr_help_header_bg

The foreground/background colors for header content in the help screen.

Default values: dark blue/default

clr_help_config_fg

clr_help_config_bg

The foreground/background colors for configuration option name (e.g., clr_help_focus_bg) in the help screen.

Default values: dark green/default

clr_help_value_fg

clr_help_value_bg

The foreground/background colors for the value of a configuration option as set in config.

Default values: dark red/default

clr_help_descr_fg

clr_help_descr_bg

The foreground/background colors for the configuration options description in the help screen.

Default values: default/default

Examples¶

At the very least, the following example config will get you going (using your account information):

[nncli]
cfg_nn_username = lebowski@thedude.com
cfg_nn_password = nihilist
cfg_nn_host     = nextcloud.thedude.com

nncli.config(5)¶

Configuration File¶

General Options¶

Keybindings¶

Colors¶

Examples¶

See Also¶