Skip to content

usage.md

Latest commit

 

History

History
148 lines (118 loc) · 6.98 KB

usage.md

File metadata and controls

148 lines (118 loc) · 6.98 KB
Raw

Keepmenu Usage

Installation - Configuration

Basic

  • Configure config.ini as desired.
  • Run keepmenu or bind to keystroke combination.
  • Enter database/keyfile paths on first run if not already configured in config.ini.
  • Start typing to match entries, Enter to type with default autotype sequence {USERNAME}{TAB}{PASSWORD}{ENTER}.

CLI Options

keepmenu [-h] [-a AUTOTYPE] [-c CONF_FILE] [-C] [-d DATABASE] [-k KEY_FILE] [-l] [-n] [-s SEARCH] [-f FIELD] [-V]

--help, -h Output a usage message and exit.

-a AUTOTYPE, --autotype AUTOTYPE Override autotype sequence in config.ini

-c CONF_FILE, --config CONF_FILE File path to a config file

-C --clipboard, type to clipboard

-d DATABASE, --database DATABASE File path to a database to open, skipping the database selection menu

-k KEY_FILE, --keyfile KEY_FILE File path of the keyfile needed to open the database specified by --database/-d

-l, --lock Lock all open databases and stop the keepmenu daemon.

-n, --no-prompt Do not prompt for database password

-s SEARCH, --show Output the password of the matching SEARCH entry to stdout (or to clipboard with -C)

-f FIELD, --field FIELD Field to output with --show. Repeat for multiple fields, which are output one per line in the order given. Defaults to the password

-V, --version Show version and exit

CLI-only usage

Keepmenu can be used as a CLI-only password manager with nothing but Pykeepass installed. Install it without the autotype extra (see installation) and use --show.

--show SEARCH finds the single entry matching SEARCH in its title, username, URL or group path, and outputs its password. If more than one entry matches, the matches are listed on stderr and keepmenu exits non-zero, so narrow the search (a group path such as Backups/Backblaze B2 is often enough).

Add --field to choose what gets output. Field names are the standard Keepass 2.x references names, without the braces and in any case - braces are accepted too, if you quote them:

$ keepmenu -d ~/passwords.kdbx -s 'ssh github' -f username -f password
gituser
hunter2

Valid field names are title, username, password, url, notes, totp, and S:<attribute> for a custom attribute. Values are output bare, one per line, in the order requested, which makes them easy to read in a script:

$ { read -r user; read -r pass; } < <(keepmenu -d ~/passwords.kdbx \
    -s 'ssh github' -f username -f password)

-f all outputs every field that has a value, labeled name: value.

$ keepmenu -d ~/passwords.kdbx -s 'ssh github' -f all
title: ssh github
username: gituser
password: hunter2
url: https://github.com
totp: 123456
S:API Key: sk-abc123

With -C, the output is copied to the clipboard instead of stdout (and cleared after 30 seconds). This needs xsel/xclip or wl-clipboard installed.

The database password is prompted for on the terminal unless it's already available from password_1/password_cmd_1 in config.ini, or the database is already unlocked by a running keepmenu daemon. Use -n to never prompt.

Features

  • General features
    • Open or create .kdbx databases, not .kdb.
    • Switch databases on the fly.
    • Alternate keyboard languages and layouts supported via xdotool or ydotool (for Wayland)
    • Display of expiring/expired passwords (expiring within 3 days) and shows the expiration time where set.
    • Add, edit and type TOTP codes. RFC 6238, Steam and custom settings are supported. Supports TOTP attributes generated by KeePass2, as well as KeeOtp and TrayTOTP plugins' formats.
  • Type entries
    • Auto-type username and/or password on selection.
    • Select to clipboard if desired (clears clipboard after 30s). If view/type individual entries isn't selected first, it will copy the password field to the clipboard if it exists, otherwise will raise an error.
    • Use a custom Keepass 2.x style auto-type sequence if you have one defined (except for character repetition and the 'special commands'). Set it per entry or set a global default. Disable autotype for an entry, if desired. {DELAY x} (in milliseconds) pauses for a one-time delay, and {DELAY=x} sets the inter-keystroke delay for the remainder of the sequence.
    • Auto-type custom attributes by hitting Enter on the desired attribute or by using the {S:<ATTR_NAME>} action code in your auto-type sequence.
    • Select any single field and have it typed into the active window. Notes fields can be viewed line-by-line and the selected line will be typed when selected.
    • Enter to open the URL in the default web browser from the View/Type menu. If you want to type the URL instead of opening, set type_url = True in config.ini.
  • Run Once (--show)
    • Search and output the password for a single entry to stdout. Pass -d to use a specific database. Pass -n to supress password prompting if desired. With -n, passwords/keyfiles must be provided either through already open databases (daemon running), command line options or config file options (e.g. password_cmd_1).
    • Pass -f to output other fields, or several fields in a chosen order. See CLI-only usage.
    • Works with no launcher, pynput or clipboard tool installed, so keepmenu can be used as a CLI-only password manager on a headless machine.
  • Edit
    • Edit entry title, username, URL, attributes, and password (manually typed or auto-generate)
    • Edit notes using terminal or gui editor (set in config.ini, or uses $EDITOR)
    • Add and Delete entries
    • Rename, move, delete and add groups
  • Configure (docs)
    • Prompts for and saves initial database and keyfile locations if config file isn't setup before first run.
    • Set multiple databases and keyfiles in the config file.
    • Hide selected groups from the default and 'View/Type Individual entries' views.
    • Keepmenu runs in the background after initial startup and will retain the entered passphrase for pw_cache_period_min minutes after the last activity.
    • Configure the characters and groups of characters used during password generation in the config file (see config.ini.example for instructions). Multiple character sets can be selected on the fly when using Rofi if the -multi-select option is passed via dmenu_command.
    • Optional Pinentry support for secure passphrase entry.
    • Keepass field references are supported.