Sesame

Sesame is a simple password manager for the command-line. See the full documentation.

Creating a Cave

Your passwords are stored in a secure cave, guarded by a Jinn that will only grant access if the correct magic words are uttered. These words also known as a passphrase, or a sesame seed 😩

To get started, install Sesame and create a new cave. Note that the --echo argument is used to display sensitive information such as the generated passphrase; omit --echo to have this copied to the clipboard instead.

$ gem install sesame-cli
$ sesame --echo --interactive
╔═════════════════════════════════════╗
║ ┏━━━┓ ┏━━━┓ ┏━━━┓  ┏━┓  ┏┓ ┏┓ ┏━━━┓ ║
║ ┗━╋━┓ ┣━━┫  ┗━╋━┓ ┏┻━┻┓ ┃┗┳┛┃ ┣━━┫  ║
║ ┗━━━┛ ┗━━━┛ ┗━━━┛ ┗   ┛ ┗   ┛ ┗━━━┛ ║
╚═════════════════════════════════════╝

🧞 - "Your new cave is ready, master. Please commit these magic words to memory..."
mammal glue wage paper store detail weave date

🧞 - "What is your command?"
1. list
2. add
3. get
4. next
5. delete
6. exit
7. help

> exit
🧞 - "I have secured your treasure with this key..."
tea old ant ice

You will notice that Sesame enters interactive mode when the --interactive argument is given, allowing you to issue multiple commands in a single session. When you exit from interactive mode, the cave will be locked with a short code.

Remembering the Passphrase

By default, Sesame generates an eight-word passphrase that is used to secure your cave. Try to remember it in groups of two or three consecutive words, and associate those words with something you know well (such as walking through your home, from the front door to the bathroom).

I enter the front door. On the side table a mammal is glueing their wages together.
Turning left into the kitchen, I see the drawer where I store my paper.
Looking down the corridor, I notice a detailed weaving of a date on the bathroom door.

Lame perhaps, but easier to remember than 58qWT6jHpA566MX (and just as secure).

If you must write the passphrase down, please make sure to store the paper that you write it on securely (ideally in a safe).

Unlocking the Cave

Upon exiting interactive mode for the first time, Sesame will lock your cave with a short code. In the example above, that code is sky tea ant ice. The next time you run Sesame, you will be prompted to enter the short code instead of your eight-word passphrase.

Instead of entering the full code, you may also enter just the first letter of each word. For the example above, entering stai as the unlock code will also work.

Keeping your cave locked this way is convenient, but anyone with access to your computer would be able to crack the lock with a small amount of effort. It is therefore recommended to expunge the lock when you don't need it. You can do this with the --expunge argument.

Adding a Service

You can add, list, retrieve and delete passwords for different services.

> add twitter kranzky
🧞 - "Your new magic words are..."
nylon sand slice party

Listing Services

> list
🧞 - "Behold! Tremble in awe at the greatness of these heroes!"
facebook ([email protected])
google (2)
twitter (kranzky)

If several user accounts exist for the same service, a number will be displayed in brackets. View all accounts by listing the service.

> list google
🧞 - "Behold! Tremble in awe at the greatness of these heroes!"
[email protected]
[email protected]

Retrieving a Password

You can retrieve a password for an existing service. You only need to specify the name of the user account if more than one exists for the service.

> get google [email protected]
🧞 - "Master, the magic words for [email protected] of google are..."
rainy area rough feather

Updating a Password

From time-to-time you may wish to update the password that you use for a particular service. The next command allows you to do that.

> next google [email protected]
🧞 - "I have recast the magic words for [email protected] of google..."
chore proud barrel docile

You can also update the lock code in a similar way.

> next sesame
🧞 - "I shall forge you a new key for locking your cave."

The new code will be used when you next exit from interactive mode.

Removing a Service

You can delete services from your cave.

> delete google [email protected]
🧞 - "These magic words for [email protected] of google are no more..."
lazy cape green badge

Recovering a Lost Cave

Sesame stores your cave in an encrypted file named sesame.cave. You should keep this file in Dropbox or iCloud or a similar service to ensure that you don't lose it. However, if the worst happens and you do lose that file, you may recover it by specifying the --reconstruct argument when creating a new cave.

You will be prompted to enter the passphrase that you wish to use. As long as you use the same passphrase as the one you used for your lost cave, the passwords generated for the services you add to the cave will be the same.

Command-line Options

Run with the --help argument to view all options.

$ sesame --help
usage: ./bin/sesame [options]
    -p, --path         the path to the sesame cave; overrides $SESAME_PATH and .sesamerc
    -q, --quiet        silence the welcome banner and the jinn
    -e, --echo         display passwords in plain text instead of adding to the clipboard
    -r, --reconstruct  reconstruct a sesame cave from an existing passphrase
    -k, --lock         create a temporary lock; no passphrase required on next run
    -x, --expunge      remove the temporary lock; full passphrase required on next run
    -i, --interactive  launch an interactive cli, allowing commands to be issued
    -c, --command      the command to execute; one of: list, get, add, next, delete
    -l, --list         show all services and usernames
    -a, --add          add a new service and username
    -g, --get          get the password for a service and username
    -n, --next         generate a new password for a service and username
    -d, --delete       remove an existing service and username
    -s, --service      the name of the service (e.g. Facebook)
    -u, --user         the username for the service (e.g. [email protected])
    -o, --offset       the password offset to use (overrides current)
    -v, --version      print the version and exit
    -h, --help         all of that up there ^

You can issue commands directly, rather than running in interactive mode.

$ sesame -qegs twitter
Enter unlock code.
🔑  ****
Opened ./sesame.cave
Password for twitter / kranzky:
nylon sand slice party

Configuration

Rather than specifying the --path argument, you may set the $SESAME_PATH environment variable to the location where the sesame.cave file should be stored.

Sesame will also look for a file named .sesamerc or sesame.cfg in the current directory and in your home directory. This file should be in the JSON format, and can specify the path, echo, interactive and quiet options. For example:

  {
    "path": "~/Dropbox",
    "interactive": false,
    "quiet": true
  }

Contributing

Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
Fork the project.
Start a feature/bugfix branch.
Commit and push until you are happy with your contribution.
Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.