Grailbox Home


Safe is a command line password management program. It securely stores all your
user IDs and passwords using a single password as the master key. It stores the
master key as a hash (SHA2), and uses it to encrypt the rest of the data using

A Note About Moving from 0.3 to 0.4

The format of the file changed slightly. Specifically, the salt and hash values
were changed to be attributes of the root safe element. You must edit your
.safe.xml file accordingly.

0.3 version:

0.4 version:
<safe salt="foo" hash="bar">

This is a one-time operation.


Safe is licensed under the Eclipse Public License. Copyright (c) 2007, 2010 Rob Warner
All rights reserved. This program and the accompanying materials
are made available under the terms of the Eclipse Public License v1.0
which accompanies this distribution, and is available at


To install safe, you must have Ruby and Ruby Gems installed. From the command
line, type:

gem install safe

safe depends on two gems:

1) crypt
2) highline

Also, you must set up an environment variable called SAFE_DIR that points to the
directory in which your encrypted password file (called .safe.xml) will be
stored. Examples:

Linux/Mac OS X:
export SAFE_DIR=~

set SAFE_DIR=c:\data

Version History

0.1 -- May 12, 2007
0.2 -- August 19, 2007
0.3 -- September 7, 2007
0.4 -- April 4, 2008
0.5 -- April 6, 2008
0.6 -- December 16, 2010
0.7 -- February 18, 2011
0.8 -- February 18, 2011

See Release-Notes.txt for more information


Run safe by typing:


The first time you run safe, you will be prompted for a password, and a new
password file (.safe.xml) will be created in the directory specified by
SAFE_DIR, like this:

$ safe
Password: ****
Creating new file . . .

If you have not set up the SAFE_DIR environment variable, you will see this

Set environment variable SAFE_DIR to the directory for your safe file

To correct, set the SAFE_DIR environment variable.

If you have set up SAFE_DIR to point to a non-existent directory, you will see
this message:

Environment variable SAFE_DIR does not point to an existing directory

where "/home/foo" is the value of SAFE_DIR. To correct, point SAFE_DIR to an
existing directory.

If you type:

safe -h

the available options display. They are:

Usage: safe [options]

-a, --add NAME Add an entry
-c, --count Print the count of entries
-d, --delete NAME Delete an entry
-i, --import FILE Import a file in <name,ID,password> format
-l, --list NAME List an entry
-v, --version Print version
-p, --password Change password
-f, --diff DIR Diff against password file in directory DIR
-m, --merge DIR Merge with password file in directory DIR

For example, to add an entry to your password file for, you type:

safe -a

You will be prompted for your master password, and then your
user ID and password, like this:

Password: **** User ID: myuserid Password: ****

NOTE: If NAME contains spaces, you must surround it in quotes, like this:

safe -a "A Cool Site"

To list your password, you type:

safe -l

You will be prompted for your master password, and then your
user ID and password will display, like this: myuserid mypassword

NOTE: The NAME you pass to -l is not case sensitive, and will find all entries
beginning with NAME. For example, typing:

safe -l r

will list all entries beginning with "r" or "R."

To delete your password, you type:

safe -d

You will be prompted for your master password, and then your
password is irretrievably deleted. You will not be asked to confirm the

Diff and Merge

Diffing and merging deviates slightly from diffing and merging other types of
files, since typically users want a union of the files without deleting any
entries. Consequently, instead of Add/Delete/Change, the output of diff will
indicate Master/Other/Change, meaning the entry is only in the Master copy
(the one in the directory pointed to by SAFE_DIR), the Other copy (the one in
the directory passed on the command line), or is in both but has been Changed,

Merge does two things:
1) Adds all entries from the Other copy that don't exist in the Master copy
to the Master copy
2) Interactively performs requested changes to changed entries on the Master


Please back up your .safe.xml file! See License section for disclaimer


You can contact me, Rob Warner, at

Grailbox Home