Getting Started¶

Installation¶

Requirements¶

GnuPG: The GNU Privacy Guard
[Linux] xclip or xsel: For copy to clipboard support

Stable¶

pip install passpie

Or if you are on a mac, install via Homebrew:

brew install passpie

Development versison¶

pip install -U https://github.com/marcwebbie/passpie/tarball/master

Fullnames queries¶

Passpie queried using fullname syntax. fullname syntax handles login and name for credentials in one go for faster adding and querying of credentials.

Structure of a fullname¶

Fullnames are composed of login@name. Login is optional. Fullnames have 3 possible formats:

login@name
@name
name

For example adding credentials using @name syntax:

passpie add @banks/mybank --password 1234
passpie add @banks/myotherbank --password 5678

Listing credentials:

$ passpie
╒═══════════════════╤═════════╤════════════╤═══════════╕
│ Name              │ Login   │ Password   │ Comment   │
╞═══════════════════╪═════════╪════════════╪═══════════╡
│ banks/mybank      │         │ *****      │           │
├───────────────────┼─────────┼────────────┼───────────┤
│ banks/myotherbank │         │ *****      │           │
╘═══════════════════╧═════════╧════════════╧═══════════╛

Since login is optional. You can query credentials using only name syntax, for example to update credential with name banks/mybank:

passpie update @banks/mybank --random

Or even better, without using the @ notation:

passpie update banks/mybank --random

Random Passwords¶

Random password pattern can be set via genpass_pattern config.

# Adding credential with random password using config pattern
passpie add john.doe@example.com

# Adding credential with random password overriding pattern
passpie add john.doe@example.com --pattern '[0-9]{5}[a-z]{5}'

# Updating credential with random password pattern
passpie update john.doe@example.com --pattern "[0-9\#\$\%\w\ ]{32}"

# Adding credential with random password and copy generated password to clipboard
passpie add john.doe@example.com --copy --pattern '[0-9]{5}[a-z]{5}'

Searching¶

# search credentials by string "exam"
passpie search exam

# search credentials using regular expressions
passpie search '[fF]oo|bar'

Clipboard¶

Copying passwords to clipboard¶

# Copying password to clipboard using ``login@name``
passpie copy foo@example.com

# Copying password using only ``name``
# only one credential with name ``example.com`` should exist
passpie copy example.com

Add or update and copy¶

# Adding credential with random password pattern
passpie add john.doe@example.com --random --pattern '[0-9]{5}[a-z]{5}'

# Updating credential with random password pattern
passpie update john.doe@example.com --random --pattern "[0-9\#\$\%\w\ ]{32}"

# Adding credential with random password and copy generated password to clipboard
passpie add john.doe@example.com --copy --random --pattern '[0-9]{5}[a-z]{5}'

Version Control¶

Initializing a database with git¶

By default all databases are initialized with a git repository if git is installed:

passpie init

Avoiding git initialization¶

passpie init --no-git

Or using configuration

Logging¶

To log changes to the database, use passpie command log

passpie log

outputs:

[13] Updated foo@bar
[12] Updated foo@bar
[11] Reset database
[10] Removed foozy@bar
[9] Updated hello@world
[8] Added hello@world
[7] Added foozy@bar
[6] Updated test@github
[5] Added foozy@bazzy
[4] Updated test@github
[3] Added foo@bar
[2] Added spam@egg
[1] Added test@github
[0] Initialized database

Resetting¶

If you want to go back to a previous version of the database history: passpie --reset-to N where N is the index of the change.

passpie log --reset-to 5

Attention: this is an operation that destroys data. Use it with caution. It is equivalent to do git reset --hard HEAD~N

Multiple Databases¶

Sometimes it is useful to have multiple databases with different passphrases for higher security. This can be done using -D or --database option.

Creating databases¶

passpie -D ~/credentials/personal init
passpie -D ~/credentials/work init
passpie -D ~/credentials/junk init

Adding passwords to specific database¶

passpie -D ~/credentials/personal add johnd@github.com --random
passpie -D ~/credentials/work add john.doe@example.com --random
passpie -D ~/credentials/junk add fake@example.com --random

Listing passwords from specific database¶

passpie -D ~/databases/junk

Remote databases with git¶

# Listing credentials from a remote database
passpie -D https://foo@example.com/user/repo.git

# Adding credentials to a remote database and autopushing changes
passpie -D https://foo@example.com/user/repo.git --autopush "origin/master" add foo+nouveau@example.com

# Exporting environment variables
export PASSPIE_DATABASE=https://foo@example.com/user/repo.git
export PASSPIE_AUTOPULL=origin/master
export PASSPIE_AUTOPUSH=origin/master

# List remote credentials
passpie

# Copy remote `foo@example.com` password
passpie copy foo@example.com

# Add credential with random password directly to remote
passpie add foo+nouveau@example.com --random --pattern "[0-9\#\$\%\w\ ]{32}"
passpie add foo+nouveau@example.com --random --pattern "[0-9\#\$\%\w\ ]{32}"

Note

There is an example database on: https://github.com/marcwebbie/passpiedb

Grouping Credentials¶

Adding credentials with the same name, groups them accordingly:

# add some credentials
passpie add jonh@example.com --comment "Jonh main mail" --random
passpie add doe@example.com --comment "No comment" --random

Listing credentials:

$ passpie
╒═════════════╤═════════╤════════════╤════════════════╕
│ Name        │ Login   │ Password   │ Comment        │
╞═════════════╪═════════╪════════════╪════════════════╡
│ example.com │ doe     │ *****      │ No comment     │
├─────────────┼─────────┼────────────┼────────────────┤
│ example.com │ jonh    │ *****      │ Jonh main mail │
╘═════════════╧═════════╧════════════╧════════════════╛

Subgroups¶

Write names separated by slashes and passpie will form subgroups of credentials by name:

passpie add foo@opensource/github.com --random
passpie add foo@opensource/python.org --random
passpie add foo@opensource/bitbucket.org --random
passpie add foo@opensource/npm.org --random

# More nesting
passpie add @cards/credit/mastercard --password "1111 2222 3333 4444"
passpie add @cards/credit/mastercard/cvv --password "123"
passpie add @cards/credit/visa --password "1111 2222 3333 4444"
passpie add @cards/credit/visa/cvv --password "456"
passpie add @cards/credit/amex --password "1111 2222 3333 4444"
passpie add @cards/credit/amex/cvv --password "789"

Listing credentials:

$ passpie
╒═════════════════════════════╤═════════╤════════════╤═══════════╕
│ Name                        │ Login   │ Password   │ Comment   │
╞═════════════════════════════╪═════════╪════════════╪═══════════╡
│ cards/credit/amex           │         │ *****      │           │
├─────────────────────────────┼─────────┼────────────┼───────────┤
│ cards/credit/amex/cvv       │         │ *****      │           │
├─────────────────────────────┼─────────┼────────────┼───────────┤
│ cards/credit/mastercard     │         │ *****      │           │
├─────────────────────────────┼─────────┼────────────┼───────────┤
│ cards/credit/mastercard/cvv │         │ *****      │           │
├─────────────────────────────┼─────────┼────────────┼───────────┤
│ cards/credit/visa           │         │ *****      │           │
├─────────────────────────────┼─────────┼────────────┼───────────┤
│ cards/credit/visa/cvv       │         │ *****      │           │
├─────────────────────────────┼─────────┼────────────┼───────────┤
│ opensource/bitbucket.org    │ foo     │ *****      │           │
├─────────────────────────────┼─────────┼────────────┼───────────┤
│ opensource/github.com       │ foo     │ *****      │           │
├─────────────────────────────┼─────────┼────────────┼───────────┤
│ opensource/npm.org          │ foo     │ *****      │           │
├─────────────────────────────┼─────────┼────────────┼───────────┤
│ opensource/python.org       │ foo     │ *****      │           │
╘═════════════════════════════╧═════════╧════════════╧═══════════╛

Shell Completion¶

You can activate passpie completion for bash, zsh or fish shells

> Check the generated script with passpie complete {shell_name}.

`bash`¶

Add this line to your .bash_profile or .bashrc

if which passpie > /dev/null; then eval "$(passpie complete bash)"; fi

`zsh`¶

Add this line to your .zshrc or .zpreztorc

if which passpie > /dev/null; then eval "$(passpie complete zsh)"; fi

`fish`¶

Add this line to your ~/.config/fish/config.fish

if which passpie > /dev/null; passpie complete fish | source ; end

Importing and Exporting¶

Exporting credentials¶

passpie export passwords.db

Warning

Passpie exports databases credentials in plain text

Importing credentials¶

Passpie importers use a list of importers to to try and handle the paswords file passed.

Available importers:

★ Keepass (CSV)
★ Pysswords
★ Passpie
★ CSV configurable importer

passpie import passwords.txt

CSV configurable importer¶

Importing from a CSV file. Specify --cols option to map columns to credential attributes.

Keepass exported credentials as keepass.csv:

"Group","Title","Username","Password","URL","Notes"
"Root","Some Title","john.doe","secret","example.com","Some comments"
"Root","Another title","foo.bar","p4ssword","example.org",""

Import credentials with:

passpie import --cols ",,login,password,name,comment" keepass.csv

Lastpass exported credentials as lastpass.csv:

"Group","Title","Username","Password","URL","Notes"
"Root","Some Title","john.doe","secret","example.com","Some comments"
"Root","Another title","foo.bar","p4ssword","example.org",""

Import with:

passpie import --cols "name,login,password,,comment" lastpass.csv

Database status¶

To have a status report on the database run:

passpie status

Available checkers are:

repeated passwords
old passwords

GnuPG keys¶

By default Passpie creates a GnuPG keyring for each initialized database. This keyring will be used to encryt/decrypt credentials from database.

To prevent this behavior, set the a recipient when initializing the database:

passpie init --recipient foo@example.com

Or for an already initialized database, set the recipient to the config file:

recipient: foo@example.com

Reseting and Purging Databases¶

# Delete all credentials from database
passpie purge

# Redefine passphrase and reencrypt all credentials from database
passpie reset

Debugging¶

# get help on commands
passpie --help

# activating verbose output
passpie -v

# activating even more verbose output
passpie -vv

Getting Started¶

Installation¶

Requirements¶

Stable¶

Development versison¶

Fullnames queries¶

Structure of a fullname¶

Random Passwords¶

Searching¶

Clipboard¶

Copying passwords to clipboard¶

Add or update and copy¶

Version Control¶

Initializing a database with git¶

Avoiding git initialization¶

Logging¶

Resetting¶

Multiple Databases¶

Creating databases¶

Adding passwords to specific database¶

Listing passwords from specific database¶

Remote databases with git¶

Grouping Credentials¶

Subgroups¶

Shell Completion¶

bash¶

zsh¶

fish¶

Importing and Exporting¶

Exporting credentials¶

Importing credentials¶

CSV configurable importer¶

Database status¶

GnuPG keys¶

Reseting and Purging Databases¶

Debugging¶

`bash`¶

`zsh`¶

`fish`¶