'\" t
.\" Title: lpass
.\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets vsnapshot
.\" Date: 07/22/2020
.\" Manual: lpass
.\" Source: lpass
.\" Language: English
.\"
.TH "LPASS" "1" "07/22/2020" "lpass" "lpass"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
lpass \- command line interface for LastPass
.SH "SYNOPSIS"
.sp
.nf
\fBlpass\fR [ \-\-version, \-v | \-\-help, \-h ]
\fBlpass\fR []
.fi
.SH "DESCRIPTION"
.sp
\fIlpass\fR is a simple command line interface to LastPass\&. It is comprised of several subcommands:
.sp
.if n \{\
.RS 4
.\}
.nf
lpass \fBlogin\fR [\-\-trust] [\-\-plaintext\-key [\-\-force, \-f]] [\-\-color=auto|never|always] USERNAME
lpass \fBlogout\fR [\-\-force, \-f] [\-\-color=auto|never|always]
lpass \fBpasswd\fR
lpass \fBshow\fR [\-\-sync=auto|now|no] [\-\-clip, \-c] [\-\-quiet, \-q] [\-\-expand\-multi, \-x] [\-\-json, \-j] [\-\-all|\-\-username|\-\-password|\-\-url|\-\-notes|\-\-field=FIELD|\-\-id|\-\-name|\-\-attach=ATTACHID] [\-\-basic\-regexp, \-G|\-\-fixed\-strings, \-F] [\-\-color=auto|never|always] {NAME|UNIQUEID}*
lpass \fBls\fR [\-\-sync=auto|now|no] [\-\-long, \-l] [\-m] [\-u] [\-\-color=auto|never|always] [GROUP]
lpass \fBmv\fR [\-\-sync=auto|now|no] [\-\-color=auto|never|always] {UNIQUENAME|UNIQUEID} GROUP
lpass \fBadd\fR [\-\-sync=auto|now|no] [\-\-non\-interactive] {\-\-name|\-\-username, \-u|\-\-password, \-p|\-\-url|\-\-notes|\-\-field=FIELD|\-\-note\-type=NOTETYPE} [\-\-color=auto|never|always] {NAME|UNIQUEID}
lpass \fBedit\fR [\-\-sync=auto|now|no] [\-\-non\-interactive] {\-\-name|\-\-username, \-u|\-\-password, \-p|\-\-url|\-\-notes|\-\-field=FIELD} [\-\-color=auto|never|always] {NAME|UNIQUEID}
lpass \fBgenerate\fR [\-\-sync=auto|now|no] [\-\-clip, \-c] [\-\-username=USERNAME] [\-\-url=URL] [\-\-no\-symbols] [\-\-color=auto|never|always] {NAME|UNIQUEID} LENGTH
lpass \fBduplicate\fR [\-\-sync=auto|now|no] [\-\-color=auto|never|always] {UNIQUENAME|UNIQUEID}
lpass \fBrm\fR [\-\-sync=auto|now|no] [\-\-color=auto|never|always] {UNIQUENAME|UNIQUEID}
lpass \fBstatus\fR [\-\-quiet, \-q] [\-\-color=auto|never|always]
lpass \fBsync\fR [\-\-background, \-b] [\-\-color=auto|never|always]
lpass \fBimport\fR [\-\-sync=auto|now|no] [\-\-keep\-dupes] [FILENAME]
lpass \fBexport\fR [\-\-sync=auto|now|no] [\-\-color=auto|never|always] [\-\-fields=FIELDLIST]
lpass \fBshare\fR \fBuserls\fR SHARE
lpass \fBshare\fR \fBuseradd\fR [\-\-read\-only=[true|false]] [\-\-hidden=[true|false]] [\-\-admin=[true|false]] SHARE USERNAME
lpass \fBshare\fR \fBusermod\fR [\-\-read\-only=[true|false]] [\-\-hidden=[true|false]] [\-\-admin=[true|false]] SHARE USERNAME
lpass \fBshare\fR \fBuserdel\fR SHARE USERNAME
lpass \fBshare\fR \fBcreate\fR SHARE
lpass \fBshare\fR \fBrm\fR SHARE
lpass \fBshare\fR \fBlimit\fR [\-\-deny|\-\-allow] [\-\-add|\-\-rm|\-\-clear] SHARE USERNAME [sites]
.fi
.if n \{\
.RE
.\}
.SS "Synchronization"
.sp
The \fI\-\-sync\fR options control when the current operation involves a synchronization with the server\&. If \fInow\fR is set, and the command makes a change, the change is synchronized before the command exits\&. If \fInow\fR is set, and the command displays a value, the local cache is synchronized before the value is shown\&. If \fInow\fR is set, and the command is otherwise successful, but synchronization fails, the command will return an error\&. If \fIauto\fR is set, and the command makes a change, the change is synchronized to the server in the background\&. If \fIauto\fR is set, and the command displays a value, the local cache is synchronized before the value is shown only if the local cache is more than 5 seconds (or \fILPASS_AUTO_SYNC_TIME\fR seconds, if set) old\&. If \fIno\fR is set, the command will not interact with the server, unless there is a current upload queue being processed\&. Any local changes that are not synchronized with the server will exist in a queue of timestamped requests which will be synchronized on the next occurring synchronization\&.
.sp
The \fIsync\fR command forces a synchronization of the local cache with the LastPass servers, and does not exit until the local cache is synchronized or until an error occurs\&. Alternatively, if \fI\-\-background\fR is specified, the synchronization occurs in a daemonized process\&.
.SS "Agent"
.sp
An agent process will be spawned in the background on a first successful command, and all subsequent commands will use the agent for decryption, instead of asking a user for a password\&. The agent will quit after one hour, unless the \fILPASS_AGENT_TIMEOUT\fR environment variable is set to an alternative number of seconds in which to quit, or 0 to never quit\&. If the environment variable \fILPASS_AGENT_DISABLE\fR is set to 1, the agent will not be used\&.
.SS "Password Entry"
.sp
The \fBpinentry\fR program, part of \fBgpg2\fR(1), may be used for inputting passwords if it is installed\&. A custom path to the \fBpinentry\fR program can be provided by the \fILPASS_PINENTRY\fR environment variable\&.
.sp
If \fBpinentry\fR program is unavailable, or if the \fILPASS_DISABLE_PINENTRY\fR environment variable is set to 1, passwords will be read from standard input and a prompt will be displayed on standard error\&.
.sp
The program used for inputting passwords may also be configured by setting the \fILPASS_ASKPASS\fR environment variable\&. \fILPASS_ASKPASS\fR is expected to be a binary that produces a prompt using its first command\-line argument, and outputs the entered password to standard out\&. ssh\-askpass implements this protocol, as does the following shell script:
.sp
.if n \{\
.RS 4
.\}
.nf
#!/bin/bash
echo \-n "$*: " >/dev/stderr
stty \-echo
read answer
stty echo
echo $answer
.fi
.if n \{\
.RE
.\}
.SS "Entry Specification"
.sp
Commands that take a \fIUNIQUENAME\fR will fail if the provided name is used multiple times, and return an error\&. Commands may alternatively take a \fIUNIQUEID\fR, which will be the integer \fIID\fR provided by LastPass for identifying entries uniquely\&. Commands that take either a \fINAME\fR or a \fIUNIQUEID\fR will create a new entry if a \fINAME\fR is specified and otherwise overwrite an existing entry if \fIUNIQUEID\fR is specified\&.
.SS "Logging In"
.sp
The \fIlogin\fR subcommand will initialize a local cache and configuration folder, then attempt to authenticate itself with the LastPass servers, using the provided command line credentials or by interactively prompting (in the case of multifactor or an unprovided password)\&. The \fI\-\-trust\fR option will cause subsequent logins to not require multifactor authentication\&. If the \fI\-\-plaintext\-key\fR option is specified, the decryption key will be saved to the hard disk in plaintext\&. Please note that use of this option is discouraged except in limited situations, as it greatly decreases the security of data\&.
.sp
The \fIlogout\fR subcommand will remove the local cache and stored encryption keys\&. It will prompt the user to confirm, unless \fI\-\-force\fR is specified\&.
.sp
The \fIpasswd\fR subcommand may be used to change your LastPass password: it will prompt for the old and new password and then re\-encrypt all records with the newly derived key\&.
.SS "Viewing"
.sp
The \fIshow\fR subcommand will display a password or selected field\&.
.sp
By default, the site you specify with the \fIshow\fR subcommand must \fBexactly\fR match the name of the site\&. If the \fI\-\-fixed\-strings\fR or \fI\-F\fR option is set, then the \fIshow\fR subcommand will find a site containing that \fBexact\fR substring; if the \fI\-\-basic\-regexp\fR or \fI\-G\fR option is set, then the \fIshow\fR subcommand will find a site matching a case\-insensitive regular expression\&.
.sp
By default if your \fIshow\fR subcommand matches more than one site, then the \fIshow\fR subcommand will generate a warning and display the names of matching sites but no other information\&. The \fI\-\-expand\-multi\fR or \fI\-x\fR option will instead show the requested information from all of the matching sites\&.
.sp
The \fIls\fR subcommand will list names in groups in a tree structure\&. If the \fI\-\-long\fR or \fI\-l\fR option is set, then also list the last modification time\&. The \fI\-u\fR option may be passed to show the last use (last touch) time instead, if available\&. Both times are in GMT\&.
.sp
Passing \fI\-\-json\fR to \fIshow\fR will generate json output instead of human\-readable text\&.
.sp
In addition to using the built\-in formats, both \fIshow\fR and \fIls\fR subcommands support printf\-style format strings by using the \fI\-\-format\fR option with the following placeholders:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
%ai: account id
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
%an: account name
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
%aN: account name including path
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
%au: account user
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
%ap: account password
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
%am: account modification time
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
%aU: account last touch time
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
%as: account share name
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
%ag: account group name
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
%al: account URL
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
%fn: field name (for
\fIshow\fR)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
%fv: field value (for
\fIshow\fR)
.RE
.sp
A slash can be added between the \fI%\fR and the placeholder to indicate that a slash should be appended, only if the printed value is expanded to a non\-empty string\&. For example, this command will properly show the full path to an account: lpass ls \-\-format="%/as%/ag%an"\&.
.SS "Modifying"
.sp
The \fIedit\fR subcommand will edit the selected field\&. If \fI\-\-non\-interactive\fR is not set, the selected field will be edited using \fIEDITOR\fR; otherwise the command will accept data until EOF or, unless the notes field is being edited, the first new line\&. Please note that when editing interactively, the contents of the field may be saved on disk in tmp files or in editor swap files, depending on your system configuration\&.
.sp
The \fIgenerate\fR subcommand will create a randomly generated password for the chosen key name, and optionally add a url and username while inserting the generated password\&.
.sp
The \fIrm\fR command will remove the specified entry, and the \fIduplicate\fR command will create a duplicate entry of the one specified, but with a different \fIID\fR\&.
.SS "Backup"
.sp
The \fIexport\fR subcommand will dump all account information including passwords to stdout (unencrypted) in CSV format\&. The optional \fI\-\-fields=FIELDLIST\fR argument may contain a comma\-separated subset of the following fields:
.sp
.if n \{\
.RS 4
.\}
.nf
id, url, username, password, extra, name, fav, id, grouping, group,
fullname, last_touch, last_modified_gmt, attachpresent
.fi
.if n \{\
.RE
.\}
.sp
The \fIimport\fR subcommand does the reverse: accounts from an unencrypted CSV file are uploaded to the server\&.
.sp
It is recommended that such backups be encrypted at rest, for example by piping to and from gpg\&.
.SS "Shared Folder Commands"
.sp
The \fIshare\fR command and its accompanying subcommands can be used to manipulate shared folders, if available to the (enterprise or premium) user\&. The \fIuserls\fR, \fIuseradd\fR, \fIusermod\fR, and \fIuserdel\fR subcommands may be used to query and modify membership of the shared folder, while the \fIcreate\fR and \fIrm\fR share subcommands may be used to add new, or delete existing shared folders\&. The normal \fIgenerate\fR and \fIedit\fR commands may be used to edit accounts within the shared folder\&.
.sp
The \fIshare limit\fR command may be used to manipulate account access lists on the share for a specific user\&. Running with no arguments will display the current access levels for a user\&. The \fI\-\-add\fR, \fI\-\-rm\fR, and \fI\-\-clear\fR options may be used to add to, remove from, or reset the list\&. Passing \fI\-\-allow\fR or \fI\-\-deny\fR will make the list a whitelist or blacklist, respectively\&.
.SS "Clipboard"
.sp
Commands that take a \fI\-c\fR or \fI\-\-clip\fR option will copy the output to the clipboard, using \fBxclip\fR(1) or \fBxsel\fR(1) on X11\-based systems, \fBpbcopy\fR(1) on OSX, or \fBputclip\fR on Cygwin\&. The command to be used can be overridden by specifying the LPASS_CLIPBOARD_COMMAND environment variable\&.
.SS "Color Output"
.sp
The \fI\-\-color\fR option controls colored output to the terminal\&. By default, commands will use \fI\-\-color=auto\fR, in which color output is used unless the output is not a tty (for example, when passed to a pipe or file)\&. If \fIalways\fR is used, colors are produced regardless of the output detection\&. If \fInever\fR is used, no color escape sequences are emitted\&.
.SS "Configuration"
.sp
\fIlpass\fR stores configuration in the following locations, in descending order of precedence:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
The directory
\fI$LPASS_HOME\fR, if set
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fI$XDG_CONFIG_HOME/lpass\fR,
\fI$XDG_DATA_HOME/lpass\fR, and
\fI$XDG_RUNTIME_DIR/lpass\fR
(or equivalent defaults), if at least
\fI$XDG_RUNTIME_DIR\fR
is set
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fI$HOME/\&.lpass\fR
.RE
.sp
All configuration may be specified via environment variables\&. Alternatively, a set of environment variable overrides may be specified in \fI$LPASS_HOME/env\fR in the form of:
.sp
.if n \{\
.RS 4
.\}
.nf
VARIABLE1=VALUE1
VARIABLE2=VALUE2
\&...
.fi
.if n \{\
.RE
.\}
.SS "Aliases"
.sp
Default options can be specified for any command by creating command aliases\&. Command aliases are stored in the configuration directory (see previous section) with files named \fIalias\&.\fR\fI\fBcommand\fR\fR\&. For example, to force the \fIls\fR subcommand to never use color, make an \fIalias\&.ls\fR file with the appropriate option:
.sp
.if n \{\
.RS 4
.\}
.nf
echo \*(Aqls \-\-color=never\*(Aq > ~/\&.config/lpass/alias\&.ls
.fi
.if n \{\
.RE
.\}
.sp
Similarly, new subcommands can be created based on built\-in subcommands with options\&. Thus,
.sp
.if n \{\
.RS 4
.\}
.nf
echo \*(Aqshow \-\-password \-c\*(Aq > ~/\&.config/lpass/alias\&.passclip
.fi
.if n \{\
.RE
.\}
.sp
would create a \fIpassclip\fR subcommand that copies your password onto the clipboard\&.
.SH "ENVIRONMENT VARIABLES"
.sp
The following environment variables may be used for configuration as described in the section above:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fILPASS_HOME\fR
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fILPASS_AUTO_SYNC_TIME\fR
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fILPASS_AGENT_TIMEOUT\fR
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fILPASS_AGENT_DISABLE\fR
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fILPASS_PINENTRY\fR
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fILPASS_DISABLE_PINENTRY\fR
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fILPASS_ASKPASS\fR
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fILPASS_CLIPBOARD_COMMAND\fR
.RE
.SH "EXAMPLES"
.sp
In the following examples, "$" indicates a shell prompt while "#" indicates a comment\&.
.sp
.if n \{\
.RS 4
.\}
.nf
# login, generate and retrieve a new password
$ lpass login user@example\&.com
$ lpass generate work/email 20
G