Configuration¶

Configuration File¶

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

Windows: %USERPROFILE%\AppData\Local\djmoch\nncli
macOS: $HOME/Library/Preferences/nncli
*nix: $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¶

Colors¶

nncli utilizes the Python Urwid module to implement the console user interface.

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 here.

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

Start nncli with no arguments which starts the console GUI mode. nncli 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 config to override the default setting.

See example configuration file below for more notes.

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

; as an alternate to cfg_nn_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_nn_password will be used
cfg_nn_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}