2 Find tickets to operate on:
3 --id=<tickets> Find only tickets in the range <tickets>
5 --limit-id, --tickets, --limit-tickets
7 --limit-status=<status>
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>
18 --limit-first=<int> Start on the <int>th row returned by the
20 --limit-rows=<int> Find only <int> rows
23 --show shows a ticket history
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
34 --status=(open|stall|resolve|kill)
40 Watcher-related editing:
42 --add-requestor=<email>
43 --del-requestor=<email>
49 Priority related editing:
52 --final-priority=<int>
72 --type=<DependsOn|MemberOf|RelatedTo>
84 --time-taken <minutes>
86 Ticket updates can take:
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.
95 ----- Forwarded message from deborah kaplan <deborah@curl.com> -----
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
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
112 RT command line interface functional specification
113 Author: Deborah Kaplan (Deborah@suberic.net)
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
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.
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.
147 In the specification, I will describe the second type of CLI.
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.
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.
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.
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.
170 The format of an rt command is as follows:
176 print an overview of the commands which can be run
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.
183 <queue> is the name of an RT queue
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>
192 Or a series of the following options:
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
205 -r <requestor name> | --requestor <requestor name>:
206 restrict tickets viewed to those requested by <requestor
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
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".
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
231 -h | --help: print a usage message.
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.
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
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
257 -h | --help: print usage message
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.
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
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.
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
285 -n <number one> <number 2> | --number <number one>
286 <number 2>: merges ticket number <number one> into ticket
288 If both arguments are not provided, the result is an
291 -q <queue> | --queue <queue>: set the queue to that
293 If <queue> is not listed, or the 1 listed does not
294 come from a list of approve queues, produces an
297 -a <area> | --area <area>: set the area of the ticket to
299 If <area> is not listed, or the 1 listed does not come
300 from a list of approve areas, produces an error.
302 -c <time stamp> | --contact <time stamp>: sets the last
303 user contact field, and produces an error if the format
305 If the argument is left blank, sets the last user
306 contact field to now.
308 -p <priority> | --priority <priority>: sets the current
309 priority to the 1 listed.
310 Produces an error if the argument is left blank.
312 -f <priority> | --final <priority>: sets the final
313 priority to the 1 listed.
314 Produces an error if the arguments left blank.
316 -d <date due> | --datedue <date due>: sets the due date
318 Produces an error if the argument is left blank, or if
319 the format is invalid.
322 with no options, this command reads from standard input
323 until it sees EOF and appends that to the ticket as a
326 -h | --help: print usage message
328 -c | --comment: append as a comment. This is the default behavior.
330 -r | --reply: append as a reply.
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>.
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.
346 ----- End forwarded message -----
349 jesse reed vincent -- root@eruditorum.org -- jesse@fsck.com
350 70EBAC90: 2A07 FC22 7DB4 42C1 9D71 0108 41A3 3FB3 70EB AC90
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.