====== request tracker :: cli (/usr/bin/rt) ====== Here go the help pages from ''rt'' cli tool (RT 3.0 or newer). ===== rt help ===== This is a command-line interface to RT 3.0 or newer. It allows you to interact with an RT server over HTTP, and offers an interface to RT's functionality that is better-suited to automation and integration with other tools. In general, each invocation of this program should specify an action to perform on one or more objects, and any other arguments required to complete the desired action. For more information: - rt help usage (syntax information) - rt help objects (how to specify objects) - rt help actions (a list of possible actions) - rt help types (a list of object types) - rt help config (configuration details) - rt help examples (a few useful examples) - rt help topics (a list of help topics) ===== rt help usage ===== Syntax: rt [options] [arguments] or rt shell Each invocation of this program must specify an action (e.g. "edit", "create"), options to modify behaviour, and other arguments required by the specified action. (For example, most actions expect a list of numeric object IDs to act upon.) The details of the syntax and arguments for each action are given by "rt help ". Some actions may be referred to by more than one name ("create" is the same as "new", for example). You may also call "rt shell", which will give you an 'rt>' prompt at which you can issue commands of the form " [options] [arguments]". See "rt help shell" for details. Objects are identified by a type and an ID (which can be a name or a number, depending on the type). For some actions, the object type is implied (you can only comment on tickets); for others, the user must specify it explicitly. See "rt help objects" for details. In syntax descriptions, mandatory arguments that must be replaced by appropriate value are enclosed in <>, and optional arguments are indicated by [] (for example, and [options] above). For more information: - rt help objects (how to specify objects) - rt help actions (a list of actions) - rt help types (a list of object types) - rt help shell (how to use the shell) ===== rt help opjects ===== Syntax: /[/] Every object in RT has a type (e.g. "ticket", "queue") and a numeric ID. Some types of objects can also be identified by name (like users and queues). Furthermore, objects may have named attributes (such as "ticket/1/history"). An object specification is like a path in a virtual filesystem, with object types as top-level directories, object IDs as subdirectories, and named attributes as further subdirectories. A comma-separated list of names, numeric IDs, or numeric ranges can be used to specify more than one object of the same type. Note that the list must be a single argument (i.e., no spaces). For example, "user/root,1-3,5,7-10,ams" is a list of ten users; the same list can also be written as "user/ams,root,1,2,3,5,7,8-10". If just a number is given as object specification it will be interpreted as ticket/ Examples: 1 # the same as ticket/1 ticket/1 ticket/1/attachments ticket/1/attachments/3 ticket/1/attachments/3/content ticket/1-3/links ticket/1-3,5-7/history user/ams user/ams/rights user/ams,rai,1/rights For more information: - rt help (action-specific details) - rt help (type-specific details) ===== rt help actions ===== You can currently perform the following actions on all objects: - list (list objects matching some condition) - show (display object details) - edit (edit object details) - create (create a new object) Each type may define actions specific to itself; these are listed in the help item about that type. For more information: - rt help (action-specific details) - rt help types (a list of possible types) The following actions on tickets are also possible: - comment Add comments to a ticket - correspond Add comments to a ticket - merge Merge one ticket into another - link Link one ticket to another - take Take a ticket (steal and untake are possible as well) For several edit set subcommands that are frequently used abbreviations have been introduced. These abbreviations are: - delete or del delete a ticket (edit set status=deleted) - resolve or res resolve a ticket (edit set status=resolved) - subject change subject of ticket (edit set subject=string) - give give a ticket to somebody (edit set owner=user) ===== rt help types ===== You can currently operate on the following types of objects: - tickets - users - groups - queues For more information: - rt help (type-specific details) - rt help objects (how to specify objects) - rt help actions (a list of possible actions) ===== rt help config ===== This program has two major sources of configuration information: its configuration files, and the environment. The program looks for configuration directives in a file named .rtrc (or $RTCONFIG; see below) in the current directory, and then in more distant ancestors, until it reaches /. If no suitable configuration files are found, it will also check for ~/.rtrc, /etc/request-tracker4/rt.conf and /etc/rt.conf. Configuration directives: The following directives may occur, one per line: - server URL to RT server. - user RT username. - passwd RT user's password. - query Default RT Query for list action - orderby Default RT order for list action - queue Default RT Queue for list action - externalauth <0|1> Use HTTP Basic authentication explicitely setting externalauth to 0 inhibits also GSSAPI based authentication, if LWP::Authen::Negotiate (and GSSAPI) is installed Blank and #-commented lines are ignored. Sample configuration file contents: server https://rt.somewhere.com/ # more than one queue can be given (by adding a query expression) queue helpdesk or queue=support query Status != resolved and Owner=myaccount Environment variables: The following environment variables override any corresponding values defined in configuration files: - RTUSER - RTPASSWD - RTEXTERNALAUTH - RTSERVER - RTDEBUG Numeric debug level. (Set to 3 for full logs.) - RTCONFIG Specifies a name other than ".rtrc" for the configuration file. - RTQUERY Default RT Query for rt list - RTORDERBY Default order for rt list ===== rt help examples ===== some useful examples All the following list requests will be restricted to the default queue. That can be changed by adding the option -q queuename List all tickets that are not rejected/resolved rt ls List all tickets that are new and do not have an owner rt ls "status=new and owner=nobody" List all tickets which I have sent or of which I am the owner rt ls myaccount List all attributes for the ticket 6977 (ls -l instead of ls) rt ls -l 6977 Show the content of ticket 6977 rt show 6977 Show all attributes in the ticket and in the history of the ticket rt show -l 6977 Comment a ticket (mail is sent to all queue watchers, i.e. AdminCc's) rt comment 6977 This will open an editor and lets you add text (attribute Text:) Other attributes may be changed as well, but usually don't do that. Correspond a ticket (like comment, but mail is also sent to requestors) rt correspond 6977 Edit a ticket (generic change, interactive using the editor) rt edit 6977 Change the owner of a ticket non interactively rt edit 6977 set owner=myaccount or rt give 6977 account or rt take 6977 Change the status of a ticket rt edit 6977 set status=resolved or rt resolve 6977 Change the status of all tickets I own to resolved !!! rt ls -i owner=myaccount | rt edit - set status=resolved ===== rt help topics ===== Syntax: rt help Get help on any of the following subjects: - tickets, users, groups, queues. - show, edit, ls/list/search, new/create. - query (search query syntax) - forms (form specification) - objects (how to specify objects) - types (a list of object types) - actions/commands (a list of actions) - usage/syntax (syntax details) - conf/config/configuration (configuration details) - examples (a few useful examples) ===== rt help shell ===== Syntax: rt shell Opens an interactive shell, at which you can issue commands of the form " [options] [arguments]". To exit the shell, type "quit" or "exit". Commands can be given at the shell in the same form as they would be given at the command line without the leading 'rt' invocation. Example: $ rt shell rt> create -t ticket set subject='new' add cc=foo@example.com # Ticket 8 created. rt> quit $ ===== rt help list ===== Syntax: rt [options] "query string" Displays a list of objects matching the specified conditions. ("ls", "list", and "search" are synonyms.) Conditions are expressed in the SQL-like syntax used internally by RT. (For more information, see "rt help query".) The query string must be supplied as one argument. (Right now, the server doesn't support listing anything but tickets. Other types will be supported in future; this client will be able to take advantage of that support without any changes.) Options: The following options control how much information is displayed about each matching object: -i Numeric IDs only. (Useful for |rt edit -; see examples.) -s Short description. -l Longer description. -f Orders the returned list by the specified field. -r reversed order (useful if a default was given) -q queue[s] restricts the query to the queue[s] given multiple queues are separated by comma -S var=val Submits the specified variable with the request. -t type Specifies the type of object to look for. (The default is "ticket".) Examples: rt ls "Priority > 5 and Status=new" rt ls -o +Subject "Priority > 5 and Status=new" rt ls -o -Created "Priority > 5 and Status=new" rt ls -i "Priority > 5"|rt edit - set status=resolved rt ls -t ticket "Subject like '[PATCH]%'" rt ls -q systems rt ls -f owner,subject ===== rt help show ===== Syntax: rt show [options] Displays details of the specified objects. For some types, object information is further classified into named attributes (for example, "1-3/links" is a valid ticket specification that refers to the links for tickets 1-3). Consult "rt help " and "rt help objects" for further details. If only a number is given it will be interpreted as the objects ticket/number and ticket/number/history This command writes a set of forms representing the requested object data to STDOUT. Options: The following options control how much information is displayed about each matching object: Without any formatting options prettyprinted output is generated. Giving any of the two options below reverts to raw output. -s Short description (history and attachments only). -l Longer description (history and attachments only). In addition, - Read IDs from STDIN instead of the command-line. -t type Specifies object type. -f a,b,c Restrict the display to the specified fields. -S var=val Submits the specified variable with the request. Examples: rt show -t ticket -f id,subject,status 1-3 rt show ticket/3/attachments/29 rt show ticket/3/attachments/29/content rt show ticket/1-3/links rt show ticket/3/history rt show -l ticket/3/history rt show -t user 2 rt show 2 ===== rt help edit ===== Syntax: rt edit [options] set field=value [field=value] ... add field=value [field=value] ... del field=value [field=value] ... Edits information corresponding to the specified objects. A purely numeric object id nnn is translated into ticket/nnn If, instead of "edit", an action of "new" or "create" is specified, then a new object is created. In this case, no numeric object IDs may be specified, but the syntax and behaviour remain otherwise unchanged. This command typically starts an editor to allow you to edit object data in a form for submission. If you specified enough information on the command-line, however, it will make the submission directly. The command line may specify field-values in three different ways. "set" sets the named field to the given value, "add" adds a value to a multi-valued field, and "del" deletes the corresponding value. Each "field=value" specification must be given as a single argument. For some types, object information is further classified into named attributes (for example, "1-3/links" is a valid ticket specification that refers to the links for tickets 1-3). These attributes may also be edited. Consult "rt help " and "rt help object" for further details. Options: - Read numeric IDs from STDIN instead of the command-line. (Useful with rt ls ... | rt edit -; see examples below.) -i Read a completed form from STDIN before submitting. -o Dump the completed form to STDOUT instead of submitting. -e Allows you to edit the form even if the command-line has enough information to make a submission directly. -S var=val Submits the specified variable with the request. -t type Specifies object type. Examples: # Interactive (starts $EDITOR with a form). rt edit ticket/3 rt create -t ticket # Non-interactive. rt edit ticket/1-3 add cc=foo@example.com set priority=3 due=tomorrow rt ls -t tickets -i 'Priority > 5' | rt edit - set status=resolved rt edit ticket/4 set priority=3 owner=bar@example.com \ add cc=foo@example.com bcc=quux@example.net rt create -t ticket set subject='new ticket' priority=10 \ add cc=foo@example.com ===== rt help create ===== Syntax: rt edit [options] set field=value [field=value] ... add field=value [field=value] ... del field=value [field=value] ... Edits information corresponding to the specified objects. A purely numeric object id nnn is translated into ticket/nnn If, instead of "edit", an action of "new" or "create" is specified, then a new object is created. In this case, no numeric object IDs may be specified, but the syntax and behaviour remain otherwise unchanged. This command typically starts an editor to allow you to edit object data in a form for submission. If you specified enough information on the command-line, however, it will make the submission directly. The command line may specify field-values in three different ways. "set" sets the named field to the given value, "add" adds a value to a multi-valued field, and "del" deletes the corresponding value. Each "field=value" specification must be given as a single argument. For some types, object information is further classified into named attributes (for example, "1-3/links" is a valid ticket specification that refers to the links for tickets 1-3). These attributes may also be edited. Consult "rt help " and "rt help object" for further details. Options: - Read numeric IDs from STDIN instead of the command-line. (Useful with rt ls ... | rt edit -; see examples below.) -i Read a completed form from STDIN before submitting. -o Dump the completed form to STDOUT instead of submitting. -e Allows you to edit the form even if the command-line has enough information to make a submission directly. -S var=val Submits the specified variable with the request. -t type Specifies object type. Examples: # Interactive (starts $EDITOR with a form). rt edit ticket/3 rt create -t ticket # Non-interactive. rt edit ticket/1-3 add cc=foo@example.com set priority=3 due=tomorrow rt ls -t tickets -i 'Priority > 5' | rt edit - set status=resolved rt edit ticket/4 set priority=3 owner=bar@example.com \ add cc=foo@example.com bcc=quux@example.net rt create -t ticket set subject='new ticket' priority=10 \ add cc=foo@example.com ===== rt help comment ===== Syntax: rt [options] Adds a comment (or correspondence) to the specified ticket (the only difference being that comments aren't sent to the requestors.) This command will typically start an editor and allow you to type a comment into a form. If, however, you specified all the necessary information on the command line, it submits the comment directly. (See "rt help forms" for more information about forms.) Options: -m Specify comment text. -a Attach a file to the comment. (May be used more than once to attach multiple files.) -c A comma-separated list of Cc addresses. -b A comma-separated list of Bcc addresses. -w