# Add more functionality to PasswordSafe CLI

1. New Actions
2. Multi-safe operations

## 1. New Actions

#### Create a new safe

    pwsafe-cli newsafe.psafe3 --new

  newsafe.psafe3 must not exist.

#### Search for an entry

    pwsafe-cli mysafe.psafe3 --search='Group=Banks,Title=Citibank'

Search is a read-only operation. It would print the Group, Title & User of matching entries on stdout, which are usually enough to distinguish each entry.

#### Add a new entry

    pwsafe-cli newsafe-psafe3 --add title='NewEntry' user='newuser' password='secret'...

// Perhaps it would be better to have a uniform way of specifying parameters, e.g.,
// pwsafe-cli mysafe.psafe3 --add='Group:Forums,Title:AVSForum,email:me@newmail.com,password=secret'
// Password could be autogenrated if unspecified?
// Error if entry exists?

#### Delete an existing entry

    pwsafe-cli newsafe-psafe3 --select='Group:Forums,title:AndroidForum' --delete [--yes]

Would prompt for confirmation if the input is a terminal, unless --yes is specified. If invoked by another process, --yes must be passed or else it would result in a no-op.
// Error if > 1 entries match

#### Update an existing entry

    pwsafe-cli mysafe.psafe3 --select='Group:Forums,Title:AVSForum' --update=email:me@newmail.com

The entry must exist. This doesn't create a new entry.

#### Print some field(s) of an existing entry

    pwsafe-cli mysafe.psafe3 --select='Group:Forums,Title:AVSForum' --print=password

It is an error if the entry is not found. pwsafe-cli would exit with an error code. However, its not an error if the field is not set or is set to an empty value (in which case pwsafe-cli would print nothing).

More details entry selection and actions below.


## 2. Multi-safe operations


### Diff

	pwsafe-cli mysafe.psafe3 --diff othersafe.psafe3 [-u|-c|-s] [--diffprog=<path>]

Show unified (default), context or side-by-side diff. Or just hand it over to an external program like vimdiff

### Sync

	pwsafe-cli mysafe.psafe3 --sync [-n] othersafe.psafe3 [--confirm]

Update entries of mysafe.psafe3 with matching entries from othersafe.psafe3, wherever they differ. Entries in othersafe.psafe3 that don't exist in mysafe.psafe3 are ignored.

--confirm prompts before making each change with yes,no,no-to-all,yes-to-all,quit,abort options.

// --dryrun?

### Merge

	pwsafe-cli mysafe.psafe3 --merge [-n] othersafe.psafe3 --mine|--other|--confirm

  (-n for dry-run, to print out the changes without modifying mysafe.psafe3)

--confirm prompts before making each change for which value to prefer (--mine=mysafe, --other=othersafe), along with all-mine,all-other,quit,abort options.

## 3. Other mechanisms for safe password input

### From an environment variable
// I *really* don't think we should do this. It's a security hole waiting to be exploited...
    export PASSWORSAFE_PASSWORD=mysecret

    pwsafe-cli mysafe.psafe3 --combination-env=PASSWORDSAFE_PASSWORD --select='Title:ebay' --view

  This idea is from ipmitool, which works somewhat like that.

### From a keyring (if possible, like on OSX)

The keyring manager should prompt the user to allow/disallow specific apps from accessing the password.

    pwsafe-cli mysafe.psafe3 --combination-keyring --select='Group:Forums,Title:AVSForum' --print=notes

### From a file descriptor

An application having access to a safe's combination might want to launch pwsafe-cli and pass the combination to it *securely*. Passing safe combination as command line parameter has the security issue that the combination could be visible in the output of `ps` command. Instead, the parent application could create an fd and fork pwsafe such that pwsafe inherits it. The combination then be securely written to & read from the fd by the parent application and pwsafe-cli respectively.

    pwsafe-cli mysafe.psafe3 --combination-fd=5 --select='Title:SomeTitle' --autotype

## Selecting safe entries

The "select" argument essentially specifies the EXACT value of any field in the database. The field must be a known valid field type, which are

1. Group
2. Title
3. User
4. Password
5. URL
6. E-Mail
7. Notes
8. Autotype
9. Run Command
10. DCA & Shift-DCA

Multiple fields can be specified, but typically it would be Title, sometimes in combination with User. Selecting entries by partial matching is not supported, to prevent accidental overwriting/deletion of a wrong entry. However, entries can be search for by supplying a partial value for one of its fields, which is a read-only operation. All matching entries would be printed, and the desired entry can be selected exactly in the next command for any modifications.

**Any operation whose '--select=' clause results in multiple matches would fail.**

## Actions on selected entries

Possible actions are as follows. They could take a valid field name a valid value for that field, depending on the semantics of
that action

_Both field name and a valid value are required_

#### 1. Update

    pwsafe-cli mysafe.psafe3 --select='Title:Amazon' --update='email:me@newmail.com'

_Only the fieldname is required_

#### 2. Copy to clipboard (only if X is running)

    pwsafe-cli mysafe.psafe3 --select='Title:Github' --to-clipboard='password'
// Would be nice to be able to do this without linking in any X windows library.

#### 3. Delete

    pwsafe-cli mysafe.psafe3 --select='Title:SourceForge' --delete='URL'

_No fieldname or field value are required for these_

#### 4. Generate new password

    pwsafe-cli mysafe.psafe3 --select='Title:Hotmail' --generate-new-password

#### 5. Autotype

    pwsafe-cli mysafe.psafe3 --select='Title:Gmail' --autotype
// How would this work on a CLI version??

#### 6. Run Command

    pwsafe-cli mysafe.psafe3 --select='Title:HomeNAS' --run-command

#### 7. View (dump all fields. May be in some parseable format like JSON, YAML?)
// I'd call this 'export', and specify format from text and XML - trivial. JSON/YAML should be simple to add.
    pwsafe-cli mysafe.psafe3 --select='Title:Netflix' --view

#### 8. Clear Password History

    pwsafe-cli mysafe.psafe3 --select='Title:Atlassian' --clear-pw-history