diff options
Diffstat (limited to 'rt/docs/design_docs/cli_spec')
| -rw-r--r-- | rt/docs/design_docs/cli_spec | 361 |
1 files changed, 19 insertions, 342 deletions
diff --git a/rt/docs/design_docs/cli_spec b/rt/docs/design_docs/cli_spec index 48a7f34e1..ae5f29f76 100644 --- a/rt/docs/design_docs/cli_spec +++ b/rt/docs/design_docs/cli_spec @@ -1,354 +1,31 @@ -Find tickets to operate on: - --id=<tickets> Find only tickets in the range <tickets> - synonyms: - --limit-id, --tickets, --limit-tickets - --limit-queue=<queue> - --limit-status=<status> - --limit-owner=<owner> - --limit-priority=<priority> - --limit-requestor=<email> - --limit-subject=<string> (Subject contains) - --limit-body=<string> (body contains) - --limit-created=(before/after) <date> - --limit-due=(before/after) <date> - --limit-starts=(before/after) <date> - --limit-started=(before/after) <date> +Things the cli must do + create ticket + comment + reply + update ticket metadata + search for tickets + update a bunch of tickets. + list tickets + login/logout - --limit-first=<int> Start on the <int>th row returned by the - database - --limit-rows=<int> Find only <int> rows -Display: - --show shows a ticket history - --history ditto +should support multiple rt servers - --summary default option. shows a ticket summary - --format Optional format string. If not specified, - uses the value of ENV{'RT_LISTING_FORMAT'} - or an internal default - +create/edit/update should use EDITOR or take from a file or stdin -Basic ticket editing: +should be able to update ticket sttributes from a commandline without invoking an editor or needing to use stdin. - --status=(open|stall|resolve|kill) - --subject=<string> - --owner=<owner> - --queue=<queue> - --time-left=<minutes> +login/logout should store RT session cookies rather than constantly transmitting the username/password combo. -Watcher-related editing: +rtserver and rt username should come from env variables. but should be able to be overridden by commandline options. - --add-requestor=<email> - --del-requestor=<email> - --add-cc=<email> - --del-cc=<email> - --add-admincc=<email> - --del-admincc=<email> +rt password should be able to be specified on the commandline (say from a script) or, failing that be prompted for within the application (as rt's sbin/initdb script does) ...or maybe able to be read from a stash file on disk. -Priority related editing: +must be able to dowaload attachments from cli. + + it might also be cool to be able to generate session-length urls for attavhments so you can use a browser. but that's not necessary. - --priority=<int> - --final-priority=<int> -Date related editing: - - --due=date - --starts=date - --started=date - --contacted=date - - - -Ticket updates: - - --comment - --reply | --respond - - -Links - - --add-link - --type=<DependsOn|MemberOf|RelatedTo> - needs one of: - --target=<ticketid> - --base=<ticketid> - - --del-link <link-id> - - - -Condiments: - any update can take: - - --time-taken <minutes> - - Ticket updates can take: - - --source -- specify a source file to read the content from - --edit = give me an editor to edit the message - --no-edit = don't give me an editor to edit the message. - - - - ------ Forwarded message from deborah kaplan <deborah@curl.com> ----- - -Date: Fri, 14 Apr 2000 11:43:18 -0400 (EDT) -From: deborah kaplan <deborah@curl.com> -To: Jesse <jesse@fsck.com> -Subject: Re: [rt-devel] RT Projects list - -Finally, here is the functional spec for the command line -interface. This is for the user interface only; if you think -this is right, I will add the administrative interface as well. -Should I post to rt-devel, add to the ticket, or just modify -based on your kibbitzing? When you are happy with it I'll start -the code. - --deborah - - -RT command line interface functional specification -Author: Deborah Kaplan (Deborah@suberic.net) -Version:0.1 - -Requirements: - -RT needs a CLI for various reasons. If a user is restricted to a -dumb terminal, she needs to be able to access the RT database and -manipulate it fully. The full functionality of both the RT -database and the RT administrative interface should be available -from this CLI. - -There are two possible types of CLI which I will discuss here. -The first is a curses-style interface, which allows the user to -move about a series of menus and choices, usually using arrow -keys. As RT supplies a Web interface, there is no need for this -curses-style interface to be written as part of RT. Instead, the -RT developers should pick one tty-based Web browser (e.g. lynx, -w3m) and make sure that all of the RT pages are easily readable -with that tty based browser. Installation of that browser should -be recommended in the RT installation documentation as a -supported method of accessing RT from a tty. - -The second possible type of CLI is more minimal: a series of -commands which can be run at a UNIX command prompt which provide -full functionality to the RT database and administrative -interface. There are two major benefits to this second type of -CLI. First of all, in order to use this CLI, you need no extra -tools (Web browsers, etc.). All that is required is a UNIX -command line prompt and an installation of RT. Secondly, a user -of RT who has a very specific command to run and who knows the -appropriate CLI commands can accomplish her task much more -quickly with a single command then she could navigating through a -menu based interface. - -In the specification, I will describe the second type of CLI. - -Caveats: - -This specification draws heavily on the structure of formatting -command line options for cvs. RT faces a smaller version of the -same kinds of problems cvs faces: we want to create a very rich -command set without sacrificing ease-of-use. - -I am not wedded to any specific command names if they seem -impractical; I merely am proposing the command names that seem -reasonable to me at this moment. - -Finally, I am finding the functioning of the web UI from RT 1. -If the functionality differs greatly in RT 2, I will need to -modify this specification. - -Specification: - -There are two commands: "rt", which is the primary interface to -the database, and "rtadmin", which is the administrative -interface to the database. - -The format of an rt command is as follows: - - rt <command> - <command> is one of: - - - help - print an overview of the commands which can be run - - - print <queue> <options> - with no options, dump to the screen a list of all open - requests in <queue> -- the equivalent of "Display Queue" in - the existing Web interface. - - <queue> is the name of an RT queue - <option> is either: - - -f <filename> | --filename <filename> - where <filename> is the name of a file (defaulting to - ~/.rtrc) in which the options described below can be - placed in the format "^ <long option name> <option value> - $". - - Or a series of the following options: - - -o <owner name> | --owner <owner name>: restrict tickets - viewed to those owned by <owner name>. - This option can be used multiple times in one call of - the rt command in order to produce a list which - contains tickets owned by multiple owners. Giving the - empty string ("") as an option to this switch will - restrict tickets viewed to those which have no owner. - If this switch is given with no argument, the option - defaults to the user name of the currently running - process. - - -r <requestor name> | --requestor <requestor name>: - restrict tickets viewed to those requested by <requestor - name>. - This option can be used multiple times in one call of - the rt command in order to produce a list which - contains tickets requested by multiple requesters. If - this switch is given with no arguments, it produces an - error. - - -s <status> | --status <status>: restrict tickets viewed - to those with the status named in <status>. - This option can be used multiple times in one call of - the rt command in order to produce a list which - contains tickets with multiple statuses (statii? - Dragon NaturallySpeaking recognizes "statuses" as a - word). This option defaults to status "open". - - -j <subject> | --subject <subject>: restrict tickets - viewed to those which contain <subject> as a substring in - the subject field of the ticket. - This command can be used multiple times in one call of - the rt command in order to produce a list which - contains tickets with various subject substrings. If - the option is called with no argument, the result is - an error. - - -h | --help: print a usage message. - - -n | --number: print out a specific ticket. - This command can be used multiple times to produce a - list which contains multiple tickets. If the option - is called with no argument, the result is an error. - - This completes all of the print options which are available - in the Web interface, except the sort options. I maintain - that this command is already excessively complex, and that - adding functionality which can be replicated easily by - standard UNIX tools is unnecessary added complexity. I - recommend that the man pages and documentation for this - option contain an example of a command line run (e.g. of rt | - awk) which replicates the sorting functionality provided by - the Web interface. - - - edit <ticket> <options> - with no options, or with no <ticket>, produces the same - output as the --help option. - Otherwise, edits the ticket with number <ticket> as - indicated in the options given. All options listed below - except for --help and --number can be used in conjunction - with one another to change many features of the same ticket - all at once. - - -h | --help: print usage message - - -s <status> | --status <status>: change the status to the - status listed in <status>. - No <status> listed, or 1 listed it does not come from - a list of approve statuses, produces an error. - - -o <owner name> | --owner <owner name>: set to the owner - of the ticket the owner named. - Follows whatever convention is finally decided on for - the requirement to steal a ticket that is owned by - somebody else. No <owner named> listed has the user - who is running the rt program take the ticket. If - that user is not a valid owner, or the 1 listed does - not come from a list of approve names, produces an - error. - - -r <requestor name> | --requestor <requestor name>: sets - the requestor to <requestor name>. - Follows any conventions that the Web UI follows to - make sure that this is a legal name. If not legal, or - left blank, produces an error. - - -j <subject> | --subject <subject>: sets the subject of - the ticket to <subject>. - If the option is called with no argument, the result - is an error. - - -n <number one> <number 2> | --number <number one> - <number 2>: merges ticket number <number one> into ticket - <number 2>. - If both arguments are not provided, the result is an - error. - - -q <queue> | --queue <queue>: set the queue to that - named. - If <queue> is not listed, or the 1 listed does not - come from a list of approve queues, produces an - error. - - -a <area> | --area <area>: set the area of the ticket to - that named. - If <area> is not listed, or the 1 listed does not come - from a list of approve areas, produces an error. - - -c <time stamp> | --contact <time stamp>: sets the last - user contact field, and produces an error if the format - is invalid. - If the argument is left blank, sets the last user - contact field to now. - - -p <priority> | --priority <priority>: sets the current - priority to the 1 listed. - Produces an error if the argument is left blank. - - -f <priority> | --final <priority>: sets the final - priority to the 1 listed. - Produces an error if the arguments left blank. - - -d <date due> | --datedue <date due>: sets the due date - to the 1 listed. - Produces an error if the argument is left blank, or if - the format is invalid. - - - comment <options> - with no options, this command reads from standard input - until it sees EOF and appends that to the ticket as a - comment. - - -h | --help: print usage message - - -c | --comment: append as a comment. This is the default behavior. - - -r | --reply: append as a reply. - - -f <filename> | --file <filename>: can be used with - either the comment or reply options. Instead of reading - from standard input, read the text of the comment or - reply from the file <filename>. - - - report <options> - this command is a place holder for reporting functionality - which does not yet exist. It will probably have the - default behavior to select reports at the command line or - choose default reports from a .rtrc file. In a future - version, it can output graphs in some graphical format. - - - ------ End forwarded message ----- - --- -jesse reed vincent -- root@eruditorum.org -- jesse@fsck.com -70EBAC90: 2A07 FC22 7DB4 42C1 9D71 0108 41A3 3FB3 70EB AC90 - -"If IBM _wanted_ to make clones, we could make them cheaper and faster than -anyone else!" - An IBM Rep. visiting Vassar College's Comp Sci Department. +I'm envisioning this as similar to the subversion cli, actually. |