RT 2.0 included a basic command-line interface (CLI), which was simply a Perl script. It was mostly feature complete but wasn’t heavily used. Because it operated independently of an RT server, it had to load all of the RT libraries before it could execute. This made it slow and tough to use interactively. It also was difficult to install, since any machine that ran it needed to have the full compliment of Perl modules, access to the database machine that was running RT, and the ability to read RT’s configuration file, which includes sensitive information like the password for the database.
For RT 3.0, however, the CLI was rewritten from the ground up to be simple, lightweight, and well-suited for automated use. Instead of loading all of RT for each invocation, it does its work with an RT server over the Web. Furthermore, the API that the CLI uses to communicate with an RT server is well-documented and available for any client, written in any language. The CLI can run on any machine with Perl installed, and it doesn’t require RT itself to be installed. All it requires is a network connection.
RT’s CLI, generally installed as rt, can query the database, look at tickets or users, and even edit their contents. Although you can use rt from the command line in a shell session, it is also suited to being used from another program. This chapter explains how to set rt up, how to integrate it into your particular environment, and how to use it in a number of different scenarios.
Your RT web server must be up and running for rt to respond in any meaningful way, even via the CLI. rt doesn’t talk to the database directly. Instead it formulates an HTTP request and sends it to the RT server. The server then replies with the appropriate data and the CLI interprets it for you, including handling interactive forms. So, before you can use the CLI, you need to have a complete RT installation and an operational RT server. Chapter 2 covers installation. Here we assume your RT server is fully functional and running.
Make sure rt is in your path. It’s usually located in the bin/ directory of the main RT installation directory—/opt/rt3, /usr/local/rt3 or some custom location. Run rt without any options. It displays a help message:
$ rt
This is a command-line interface to RT 3.
...Next, you need to configure rt so it can connect to the RT server. It needs two pieces of information: the URL of the server and the authentication information to use for that server. You can set this information using environment variables or in a configuration file.
The relevant environment variables are RTUSER and RTSERVER. The following example sets these in the bash shell:
$export RTUSER=jdoe$export RTSERVER=https://rt.example.com
The relevant options in a configuration file are user and server. The following example shows the contents of .rtrc in the home directory of user jdoe:
user jdoe
server https://rt.example.comIf neither $RTUSER or user are defined, rt defaults to the current login name. For complete details on configuring the rt command-line, see Appendix C.
Most rt commands look something like this:
$rt /<action>/<options>A list of available actions is available in Appendix B.
The first time you run rt with an action, it will prompt you for your password:
$ rt list "status='new'"
Password:Just like in the browser, once you’ve entered your password, a session is established so you don’t need to keep entering your password. rt remembers this session information by storing it in a file in your home directory: ~/.rt_sessions, accessible only to yourself. You should protect this file with strict permissions, otherwise another user could copy it and operate on the RT server as you.
To log out from RT and end this session, use the logout command:
$ rt logoutThe CLI has two different forms, a command-line tool and an interactive shell. The rt command is designed to be easy to use from another program or on-the-fly. The following example uses the command-line tool to tell RT to display several specific fields from the ticket with the unique id of 42.
$ rt show -t ticket 42 -f id,subject,status
id: ticket/42
Subject: A special number
Status: open
$The interactive shell starts when you run rt with the action shell. In the following example, the rt> prompt remains after the command has been executed, because the RT shell is still active. This dispenses with the delay of waiting for a new shell process to startup on each invocation. The functionality is identical.
$ rt shell
rt> edit ticket/42 set queue=emergency status=resolved
Ticket 42 Resolved.
rt>These few examples just scratch the surface of what you can do with rt. The rest of this chapter covers a broad range of possibilities, and Appendix B provides a quick reference to rt’s actions and the options for each.
In order to create a ticket with rt, use the create action. This action creates users and queues in addition to new tickets, so create requires an object type:
$ rt create -t ticketWhen this command is issued, your editor will open up with some basic data and fields for you to fill out:
# Required: Queue, Requestor, Subject
id: ticket/new
Queue: General
Requestor: jdoe
Subject:
Cc:
AdminCc:
Owner:
Status: new
Priority: 50
InitialPriority: 50
FinalPriority: 0
TimeEstimated: 0
Starts: 2004-09-21 01:05:11
Due: 2004-09-21 01:05:11
Text:Once you fill in the required fields—queue, requestor, and subject—and write the file to submit the data to the server, you will get a message indicating success:
# Ticket 23 created.
If any of the required fields are not present, rt will reopen your editor with the data and a message indicating which fields were missing.
You also can create a ticket by passing values for the fields directly on the command line. At a minimum, you need a valid subject line and a queue:
$ rt create -t ticket set subject="urgent contact request" set queue=general
# Ticket 45 created.Now use the show
action to check that the ticket was correctly created.
$ rt show ticket/45 -f id,subject,queue
id: ticket/45
Subject: urgent contact request
Queue: GeneralYou also can create users with the same create action, setting the minimal required name to avoid the interactive form.
$ rt create -t user set name=bigboote
# User 66 created.
$ rt show user/66
id: user/66
Name: bigboote
Password: ********
EmailAddress:
The show action displays a ticket and its metadata, history, and attachments:
$ rt show ticket/3
id: ticket/3
Queue: General
Owner: darren
Creator: root
Subject: Bring more coffee rolls!
Status: open
Priority: 90
InitialPriority: 0
FinalPriority: 0
Requestors:
Cc:
AdminCc:
Created: Mon May 03 21:18:30 2004
Starts: Mon May 03 21:17:43 2004
Started: Mon May 03 22:20:23 2004
Due: Mon May 03 21:17:43 2004
Resolved: Not set
Told: Not set
TimeEstimated: 0
TimeWorked: 0
TimeLeft: 0As you can see, show displays a lot of information by default. To limit the amount of detail returned, pass the -f option to specify the fields you want to see. The field names correspond to what show displays, except they are not case-sensitive. The following example limits the display to ticket ID, queue name, subject, status, and priority:
$ rt show ticket/3 -f id,queue,subject,status,priority
id: ticket/3
Queue: General
Subject: Bring more coffee rolls!
Status: open
Priority: 90By default, show shows the object’s metadata. However, there are other object attributes you might want to see, like a ticket’s history or attachments. These attributes are addressed using the object specification syntax. To access the history attribute of ticket 9, use ticket/9/history.
$ rt show ticket/9/history
# 6/6 (/total)
63: Ticket created by jdoe
64: Cc root@localhost added by jdoe
72: Cc root@eruditorum.org added by jdoe
73: Cc root@localhost removed by root
74: Priority changed from 0 to 99 by jdoe
75: Status changed from new to open by jdoeYou also can display all of the attachments for a ticket with the attachments attribute:
$ rt show ticket/9/attachments
Attachments: 7: (multipart/mixed / 0b), 8: (text/plain / 29b),
9: (multipart/mixed / 0b), 10: (text/plain / 0b),
11: output.txt (text/plain / 164b),
12: (text/plain / 622b)To view the plain-text content of one of the attachments, use the content attribute together with the attachments attribute:
$ rt show ticket/9/attachments/11/content
This is the output I get when I try the first solution:
...Here’s a command to look at the information that makes up an RT user, reducing the output by specifying certain fields only:
$ rt show -t user -f id,name,emailaddress,comments root
id: user/12
Name: root
EmailAddress: root@localhost
Comments: SuperUserWhen looking at several tickets at once, note that you can specify multiple IDs separated by commas, and a range of IDs defined with a dash between the minimum and maximum ID, as in the following example:
$ rt show ticket/1,5-8,42 -f id,subject,status
id: ticket/1
Subject: a new ticket
Status: new
--
id: ticket/5
Subject: a new ticket
Status: new
--
id: ticket/6
Subject: a new ticket
Status: new
...In addition to the type/id form, you also can specify multiple object IDs at the end of the command, separated by either spaces or commas:
$ rt show -t ticket -f id,subject,status 1 5-8 42
id: ticket/1
Subject: a new ticket
Status: new
--
id: ticket/5
Subject: a new ticket
Status: new
--
id: ticket/6
Subject: a new ticket
Status: new
--
id: ticket/7
Subject: a new ticket
Status: new
--
id: ticket/8
Subject: a new ticket
Status: new
--
id: ticket/42
Subject: a new ticket
Status: new
The correspond
and comment actions post a response or comment to a ticket from the command line:
$ rt correspond -m "The vendor is supplying a patch" ticket/15
The -m option allows you to provide the text of the message on the command line. If this is not supplied, then rt will open your editor for you to enter a full message.
You also can attach files to a ticket with the -a option:
$ rt comment -m "This is what I see" -a screenshot.png ticket/15
The -w option lets you set a TimeWorked value for this comment:
$ rt correspond -m "Does the attached patch solve the problem?" \
> -a hairy.patch -w 300 ticket/42The -c and -b options set the Cc and Bcc fields:
$ rt correspond -m "I'll look into this problem tonight" \
> -c root@eruditorum.org,jdoe@example.org \
> -b me@isp.net ticket/23
The edit
action edits object metadata. When you invoke edit with an object specification, if no additional information is given on the command line, rt enters interactive mode in the editor specified by the $EDITOR environment variable. When you quit the editor, the ticket is updated. This is similar to the create action, except that the editor displays the current values of all the fields instead of an empty template. Only values that actually change are sent back to the server.
$ rt edit ticket/47
id: ticket/47
Queue: General
Owner: Nobody
Creator: jdoe
Subject: There is a light that never goes out
Status: new
Priority: 50
InitialPriority: 50
FinalPriority: 0
Requestors:
Cc:
AdminCc:
Created: Mon Sep 20 21:07:39 2004
Starts: Mon Sep 20 21:05:11 2004
Started: Not set
Due: Mon Sep 20 21:05:11 2004
Resolved: Not set
Told: Not set
TimeEstimated: 0
TimeWorked: 0
TimeLeft: 0In addition, you can set many of the fields of an object using the set, add, or del subactions on the command line:
$ rt edit ticket/42
> add cc=root@eruditorum.org \
> del cc=root@localhost \
> set priority=99 \
> set status=open \The available fields that you can set, add, or del are the same as the fields presented when you edit an object in a text editor. Some of these attributes cannot be changed, like Created and id.
Using the example of the user created above, modify the information by setting the emailaddress. The information in this case is sufficient to avoid entering interactive mode.
$ rt edit user/bigboote set emailaddress=bigboote@example.com
# User 66 updated.Now use show to display the modified information.
$ rt show user/66 -f id,name,emailaddress
id: user/66
Name: bigboote
EmailAddress: bigboote@example.comYou escalate a ticket by increasing its priority:
$ rt edit ticket/42 set priority=80To assign a ticket set the owner of the ticket. To take a ticket, set the owner to yourself.
$ rt edit ticket/7 set owner=fayewong
To resolve a ticket set the status to resolved:
$ rt edit ticket/15 set status='resolved'
Searching with rt involves the list
action and TicketSQL. See "Understanding TicketSQL in Chapter 3 for an introduction to TicketSQL syntax. The command-line interface doesn’t provide a query builder to help you out. The following command shows all tickets with a status of new:
$ rt list "status = 'new'"
3: Bring more coffee rolls!The -l option to list provides a long listing, exactly the same as using the show action (see "Finding a Ticket, earlier in this chapter). The -i option only lists object identifiers:
$ rt list -i "status = 'new'"
ticket/3rt passes your TicketSQL query directly to the RT server, which executes the query on your behalf and returns the results for rt to display. You can write arbitrarily complex TicketSQL, just be sure to enclose your entire query within quotes. The following example searches for open tickets in the General queue:
$ rt list "queue = 'General' AND status = 'open'"
3: Bring more coffee rolls!
5: My frobnitz is broken... againIf you double-quote the TicketSQL string, most shells will perform variable interpolation, which can be useful. For example, to get your own open tickets (assuming your system login is the same as your RT login), you could use the $USER environment variable:
$ rt list "status = 'open' AND owner = '$USER'"
5: My frobnitz is broken... againHere is an example of the list action, requesting a short list of all tickets which have non-closed Status.
$ rt list -s -t ticket "Status != 'closed'"
1: a new ticket
21: A request subject line
42: A special number
...Another, more useful example shows the LIKE query string for approximate matches. The following example also uses the -o option to order the output based on the status field rather than the default id.
$rt list -s -o +status "status != 'closed' \>AND subject LIKE 'request'"21: A request subject line ...
The following example uses the -i switch to return only object-ids from the list action. You can feed these results directly into another rt action such as show or edit, which in turn uses the - switch to take the object-ids from STDIN. The following example searches for a list of tickets that aren’t closed and shows details for each.
$ rt list -i "Status != 'closed'" | rt show -
id: ticket/1
Queue: General
Owner: Nobody
Creator: root
...
--
id: ticket/42
Queue: General
Owner: Nobody
Creator: root
...You can use the same strategy to update multiple tickets at the same time, for example, to add a cc address to all tickets with “urgent” in the subject:
$ rt list -i "Subject LIKE 'urgent'" | rt edit - add cc=bigboote@example.com
# Ticket 45 updated.
# Ticket 44 updated.
...If you are ever uncertain about the syntax or options for a particular action, rt has a help
menu. Even before the CLI is properly configured, you can view the help menu to find out which options are supported and how to use the program in the first place. To display the built-in help, either run rt without any arguments at all, or pass it the help parameter. Both print out a short helpful message to get you started.
$ rt help
This is a command-line interface to RT 3.
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 actions (a list of possible actions)
- rt help objects (how to specify objects)
- rt help usage (syntax information)
- rt help config (configuration details)
- rt help examples (a few useful examples)
- rt help topics (a list of help topics)The help output gives you information about using the help system. You can almost always go a little deeper to get the information or examples you need. You don’t even need an operational RT server to access the help features—the functionality is built into the client. The help system is somewhat flexible in spelling: whether you say rt help ticket or rt help tickets is irrelevant.
$ rt help actions
You can currently perform the following actions on all objects:
...
The rt command-line tool supports a shell
mode, which launches an interactive shell for running actions. The primary advantage is that you don’t have to wait for the client to start up on each command—it’s already running and waiting for your input. To enter the shell, give the shell action to rt.
$ rt shell
rt>The syntax and options for actions in the shell are the same as on the command line, except you skip the initial rt. You display a ticket with show:
rt> show ticket/42 -f id,queue,subject,status,priority
id: ticket/42
Queue: General
Subject: A special number
Status: open
Priority: 90
rt>modify it with edit:
rt> edit ticket/42 set priority=80
# Ticket 42 updated.
rt>and check your work with show again:
rt> show ticket/42 -f id,subject,priority
id: ticket/42
Subject: A special number
Priority: 80
rt>Quit the RT shell session by typing ^C (Control-C).
Sometimes the CLI can be overly verbose or confusing, with the many options and commands available. One way to make the interaction a bit simpler is to use your shell to simplify common operations.
If you’re using a Bourne-like shell (bash , ksh , /bin/sh on most systems), you can create shell functions by placing the following in your .profile:
rtspam() {
rt edit ticket/$1 set queue=spam status=deleted
}
rtresolve() {
rt edit ticket/$1 set status=resolved
}
rtshow() {
rt show ticket/$1
}Now to use these functions directly from your shell:
$ rtresolve 12345
Ticket 12345 Resolved.You could do this just as well with shell scripts, but shell functions are more elegant.
An alternative to dedicating a function to the task would be to do the same thing but use an alias instead. In a Bourne-like shell (bash, ksh, sh, etc.), alias commands like these may be useful in your .profile:
alias rtspam='rt edit ticket/$1 set queue=spam status=deleted'
alias rttop='rt ls -i "priority > 70 and status != resolved" | rt show - -f
id,subject'If you’re using a C shell (csh or tcsh), try these in your .cshrc:
alias rtspam 'rt edit ticket/\!:1 set queue=spam status=deleted'
alias rtresolve 'rt edit ticket/\!:1 set status=resolved'
alias rtshow 'rt show ticket/\!:1'One useful tidbit if you’re scripting RT from Perl is that the output of rt show is a valid MIME object. Modules like MIME::Parser or Email::Simple can parse it and manipulate it further:
use Email::Simple;
my $tno = $ARGV[0];
my $ticket = `rt show ticket/$tno`;
my $tobj = Email::Simple->new($ticket);
print "Ticket $tno was requested by ", $tobj->header("requestors"),
" on ", $tobj->header("created"), ".\n";Get RT Essentials now with the O’Reilly learning platform.
O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.
