rt/docs/design_docs/cli_spec

   1
   2 Find tickets to operate on:
   3         --id=<tickets>          Find only tickets in the range <tickets>
   4                 synonyms:
   5                 --limit-id, --tickets, --limit-tickets
   6         --limit-queue=<queue>
   7         --limit-status=<status>
   8         --limit-owner=<owner>
   9         --limit-priority=<priority>
  10         --limit-requestor=<email>
  11         --limit-subject=<string>      (Subject contains)
  12         --limit-body=<string>         (body contains)
  13         --limit-created=(before/after) <date>
  14         --limit-due=(before/after) <date>
  15         --limit-starts=(before/after) <date>
  16         --limit-started=(before/after) <date>
  17
  18         --limit-first=<int>           Start on the <int>th row returned by the
  19                                 database
  20         --limit-rows=<int>      Find only <int> rows
  21
  22 Display:
  23         --show                  shows a ticket history
  24         --history               ditto
  25
  26         --summary               default option. shows a ticket summary
  27                 --format        Optional format string. If not specified,
  28                                 uses the value of ENV{'RT_LISTING_FORMAT'}
  29                                 or an internal default
  30
  31
  32 Basic ticket editing:
  33
  34         --status=(open|stall|resolve|kill)
  35         --subject=<string>
  36         --owner=<owner>
  37         --queue=<queue>
  38         --time-left=<minutes>
  39
  40 Watcher-related editing:
  41
  42         --add-requestor=<email>
  43         --del-requestor=<email>
  44         --add-cc=<email>
  45         --del-cc=<email>
  46         --add-admincc=<email>
  47         --del-admincc=<email>
  48
  49 Priority related editing:
  50
  51         --priority=<int>
  52         --final-priority=<int>
  53
  54 Date related editing:
  55
  56         --due=date
  57         --starts=date
  58         --started=date
  59         --contacted=date
  60
  61
  62
  63 Ticket updates:
  64
  65         --comment
  66         --reply | --respond
  67
  68
  69 Links
  70
  71         --add-link
  72                 --type=<DependsOn|MemberOf|RelatedTo>
  73                 needs one of:
  74                    --target=<ticketid>
  75                    --base=<ticketid>
  76
  77         --del-link <link-id>
  78
  79
  80
  81 Condiments:
  82         any update can take:
  83
  84                 --time-taken <minutes>
  85
  86         Ticket updates can take:
  87
  88                 --source        -- specify a source file to read the content from
  89                 --edit          = give me an editor to edit the message
  90                 --no-edit       = don't give me an editor to edit the message.
  91
  92
  93
  94
  95 ----- Forwarded message from deborah kaplan <deborah@curl.com> -----
  96
  97 Date: Fri, 14 Apr 2000 11:43:18 -0400 (EDT)
  98 From: deborah kaplan <deborah@curl.com>
  99 To: Jesse <jesse@fsck.com>
 100 Subject: Re: [rt-devel] RT Projects list
 101
 102 Finally, here is the functional spec for the command line
 103 interface.  This is for the user interface only; if you think
 104 this is right, I will add the administrative interface as well.
 105 Should I post to rt-devel, add to the ticket, or just modify
 106 based on your kibbitzing?  When you are happy with it I'll start
 107 the code.
 108
 109 -deborah
 110
 111
 112 RT command line interface functional specification
 113 Author: Deborah Kaplan (Deborah@suberic.net)
 114 Version:0.1
 115
 116 Requirements:
 117
 118 RT needs a CLI for various reasons.  If a user is restricted to a
 119 dumb terminal, she needs to be able to access the RT database and
 120 manipulate it fully.  The full functionality of both the RT
 121 database and the RT administrative interface should be available
 122 from this CLI.
 123
 124 There are two possible types of CLI which I will discuss here.
 125 The first is a curses-style interface, which allows the user to
 126 move about a series of menus and choices, usually using arrow
 127 keys.  As RT supplies a Web interface, there is no need for this
 128 curses-style interface to be written as part of RT.  Instead, the
 129 RT developers should pick one tty-based Web browser (e.g. lynx,
 130 w3m) and make sure that all of the RT pages are easily readable
 131 with that tty based browser.  Installation of that browser should
 132 be recommended in the RT installation documentation as a
 133 supported method of accessing RT from a tty.
 134
 135 The second possible type of CLI is more minimal: a series of
 136 commands which can be run at a UNIX command prompt which provide
 137 full functionality to the RT database and administrative
 138 interface.  There are two major benefits to this second type of
 139 CLI.  First of all, in order to use this CLI, you need no extra
 140 tools (Web browsers, etc.).  All that is required is a UNIX
 141 command line prompt and an installation of RT.  Secondly, a user
 142 of RT who has a very specific command to run and who knows the
 143 appropriate CLI commands can accomplish her task much more
 144 quickly with a single command then she could navigating through a
 145 menu based interface.
 146
 147 In the specification, I will describe the second type of CLI.
 148
 149 Caveats:
 150
 151 This specification draws heavily on the structure of formatting
 152 command line options for cvs.  RT faces a smaller version of the
 153 same kinds of problems cvs faces: we want to create a very rich
 154 command set without sacrificing ease-of-use.
 155
 156 I am not wedded to any specific command names if they seem
 157 impractical; I merely am proposing the command names that seem
 158 reasonable to me at this moment.
 159
 160 Finally, I am finding the functioning of the web UI from RT 1.
 161 If the functionality differs greatly in RT 2, I will need to
 162 modify this specification.
 163
 164 Specification:
 165
 166 There are two commands: "rt", which is the primary interface to
 167 the database, and "rtadmin", which is the administrative
 168 interface to the database.
 169
 170 The format of an rt command is as follows:
 171
 172  rt <command>
 173     <command> is one of:
 174
 175     - help
 176       print an overview of the commands which can be run
 177
 178     - print <queue> <options>
 179       with no options, dump to the screen a list of all open
 180       requests in <queue> -- the equivalent of "Display Queue" in
 181       the existing Web interface.
 182
 183       <queue> is the name of an RT queue
 184       <option> is either:
 185
 186         -f <filename> |  --filename <filename>
 187            where <filename> is the name of a file (defaulting to
 188            ~/.rtrc) in which the options described below can be
 189            placed in the format "^ <long option name> <option value>
 190            $".
 191
 192         Or a series of the following options:
 193
 194         -o <owner name> |  --owner <owner name>: restrict tickets
 195         viewed to those owned by <owner name>.
 196            This option can be used multiple times in one call of
 197            the rt command in order to produce a list which
 198            contains tickets owned by multiple owners.  Giving the
 199            empty string ("") as an option to this switch will
 200            restrict tickets viewed to those which have no owner.
 201            If this switch is given with no argument, the option
 202            defaults to the user name of the currently running
 203            process.
 204
 205         -r <requestor name> | --requestor <requestor name>:
 206         restrict tickets viewed to those requested by <requestor
 207         name>.
 208            This option can be used multiple times in one call of
 209            the rt command in order to produce a list which
 210            contains tickets requested by multiple requesters.  If
 211            this switch is given with no arguments, it produces an
 212            error.
 213
 214         -s <status> | --status <status>: restrict tickets viewed
 215         to those with the status named in <status>.
 216            This option can be used multiple times in one call of
 217            the rt command in order to produce a list which
 218            contains tickets with multiple statuses (statii?
 219            Dragon NaturallySpeaking recognizes "statuses" as a
 220            word).  This option defaults to status "open".
 221
 222         -j <subject> | --subject <subject>: restrict tickets
 223         viewed to those which contain <subject> as a substring in
 224         the subject field of the ticket.
 225            This command can be used multiple times in one call of
 226            the rt command in order to produce a list which
 227            contains tickets with various subject substrings.  If
 228            the option is called with no argument, the result is
 229            an error.
 230
 231         -h | --help: print a usage message.
 232
 233         -n | --number: print out a specific ticket.
 234            This command can be used multiple times to produce a
 235            list which contains multiple tickets.  If the option
 236            is called with no argument, the result is an error.
 237
 238     This completes all of the print options which are available
 239     in the Web interface, except the sort options.  I maintain
 240     that this command is already excessively complex, and that
 241     adding functionality which can be replicated easily by
 242     standard UNIX tools is unnecessary added complexity.  I
 243     recommend that the man pages and documentation for this
 244     option contain an example of a command line run (e.g. of rt |
 245     awk) which replicates the sorting functionality provided by
 246     the Web interface.
 247
 248     - edit <ticket> <options>
 249       with no options, or with no <ticket>, produces the same
 250       output as the --help option.
 251       Otherwise, edits the ticket with number <ticket> as
 252       indicated in the options given.  All options listed below
 253       except for --help and --number can be used in conjunction
 254       with one another to change many features of the same ticket
 255       all at once.
 256
 257         -h | --help: print usage message
 258
 259         -s <status> | --status <status>: change the status to the
 260         status listed in <status>.
 261            No <status> listed, or 1 listed it does not come from
 262            a list of approve statuses, produces an error.
 263
 264         -o <owner name> |  --owner <owner name>: set to the owner
 265         of the ticket the owner named.
 266            Follows whatever convention is finally decided on for
 267            the requirement to steal a ticket that is owned by
 268            somebody else.  No <owner named> listed has the user
 269            who is running the rt program take the ticket.  If
 270            that user is not a valid owner, or the 1 listed does
 271            not come from a list of approve names, produces an
 272            error.
 273
 274         -r <requestor name> | --requestor <requestor name>: sets
 275         the requestor to <requestor name>.
 276            Follows any conventions that the Web UI follows to
 277            make sure that this is a legal name.  If not legal, or
 278            left blank, produces an error.
 279
 280         -j <subject> | --subject <subject>:  sets the subject of
 281         the ticket to <subject>.
 282            If the option is called with no argument, the result
 283            is an error.
 284
 285         -n <number one> <number 2> | --number <number one>
 286         <number 2>: merges ticket number <number one> into ticket
 287         <number 2>.
 288            If both arguments are not provided, the result is an
 289            error.
 290
 291         -q <queue> | --queue <queue>: set the queue to that
 292         named.
 293            If <queue> is not listed, or the 1 listed does not
 294            come from a list of approve queues, produces an
 295            error.
 296
 297         -a <area> | --area <area>: set the area of the ticket to
 298         that named.
 299            If <area> is not listed, or the 1 listed does not come
 300            from a list of approve areas, produces an error.
 301
 302         -c <time stamp> | --contact <time stamp>: sets the last
 303         user contact field, and produces an error if the format
 304         is invalid.
 305            If the argument is left blank, sets the last user
 306            contact field to now.
 307
 308         -p <priority> | --priority <priority>: sets the current
 309         priority to the 1 listed.
 310            Produces an error if the argument is left blank.
 311
 312         -f <priority> | --final <priority>: sets the final
 313         priority to the 1 listed.
 314            Produces an error if the arguments left blank.
 315
 316         -d <date due> | --datedue <date due>: sets the due date
 317         to the 1 listed.
 318            Produces an error if the argument is left blank, or if
 319            the format is invalid.
 320
 321     - comment <options>
 322       with no options, this command reads from standard input
 323       until it sees EOF and appends that to the ticket as a
 324       comment.
 325
 326         -h | --help: print usage message
 327
 328         -c | --comment: append as a comment.  This is the default behavior.
 329
 330         -r | --reply: append as a reply.
 331
 332         -f <filename> | --file <filename>: can be used with
 333         either the comment or reply options.  Instead of reading
 334         from standard input, read the text of the comment or
 335         reply from the file <filename>.
 336
 337     - report <options>
 338       this command is a place holder for reporting functionality
 339       which does not yet exist.  It will probably have the
 340       default behavior to select reports at the command line or
 341       choose default reports from a .rtrc file.  In a future
 342       version, it can output graphs in some graphical format.
 343
 344
 345
 346 ----- End forwarded message -----
 347
 348 --
 349 jesse reed vincent -- root@eruditorum.org -- jesse@fsck.com
 350 70EBAC90: 2A07 FC22 7DB4 42C1 9D71 0108 41A3 3FB3 70EB AC90
 351
 352 "If IBM _wanted_ to make clones, we could make them cheaper and faster than
 353 anyone else!"  - An IBM Rep. visiting Vassar College's Comp Sci Department.
 354