# keycli -- The Keystone Command-Line Interface

## Overview

`keycli` provides access to certain Keystone features from a command-line program. This allows users running from shell prompts to read slips without having to go through the web interface. A command line interface also allows users to work with traditional Unix environments, doing things like piping the data from a slip into some other program.

This version of `keycli` only supports queries of a local Keystone database. The next version will allow for adding data to the database.

Generally, only public data will be reported on. On the assumption that if a user's login name matches a Keystone login name, they are the same person, private data will be reported if this match condition exists. Keystone administrators will be able to disable this assumption by setting the configuration variable `$sys_usermatch` to `0`. This will prevent any private data from being accessed by keycli.

For emailed results, additional information can be provided in the `.../templates/keycli_mail_intro.txt` and `.../templates/keycli_mail_trailer.txt` files. This information will be inserted into the email message before and after the query results, respectively.

## Mode Options

One of these options must be specified, or keycli will default to `--list`.

--help, -h
  Show a help message. Any other options are ignored.
--list, -l
  Query the Keystone database for slip information.

## Selection Criteria

The following options control which Keystone slips will be selected for display.

--slip=n, -s n
  Select the slip whose ID number is `n'.
--parent=n, -p n
  Select slips whose parent is `n'.
--status=c
  Select slips with status `c'.
--currtech=s
  Specify the current tech for selected slips.
--priority=n
  Select slips with a priority of `n'.
(The default query will be ``--currtech=$USER --priority=1''.)
--children
  When showing a slip, list out it's children as well.

## Output Options

These options control how the output is formatted or redirected.

--brief, -b
  The results of a query will be returned in 'brief' form -- only a single line per slip. This is the default.
--full
  The results of the query are returned in full.
--oneline
  Each slip will be displayed on a single line, with the fields separated by commas. Each field will be contained within double quotes. Any double quote or slash characters within a field will be preceded by a slash. This option is for extracting data for further automated processing.
--mailreply={address}, -m {address}
  The output of the command should be sent via email to 'address'. If address is not specified, the Mail::Internet's 'reply' method should be used to figure out what the reply-to address will be, and that will be used. If no appropriate reply address is found in content of the input, and no address is specified in the command line, an error condition is generated.
--replyto={address}, -r {address}
  Set the 'Reply-To' when generating mail back to a user. If 'mailreply' is not set, this command is ignored. This is used to force a Reply to go to .
--debug, -d
  Show debugging information on STDERR.

## Examples

>     keycli.pl

This will display a brief listing of all of the priority `1' slips assigned to this user.

>     keycli.pl --list --full --status=0 --children --mailreply=user@someplace.com

This will list all open slips, and the children of those slips in the full display format. That listing will be sent via email to `user@someplace.com`.