O'Reilly logo

RT Essentials by Robert Spier, Jesse Vincent, Richard Foley, Dave Rolsky, Darren Chamberlain

Stay ahead with the world's most comprehensive technology and business learning platform.

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, tutorials, and more.

Start Free Trial

No credit card required

Chapter 4. Command-Line Interface

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.

Running the CLI

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.com

If 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 logout

The 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.

Creating a Ticket

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 ticket

When 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: General

You 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:

Finding a Ticket

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: 0

As 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: 90

By 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 jdoe

You 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: SuperUser

When 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

Replying to a Ticket

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/42

The -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

Editing a Ticket

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: 0

In 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.com

You escalate a ticket by increasing its priority:

    $ rt edit ticket/42 set priority=80

To 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 for Tickets

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/3

rt 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... again

If 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... again

Here 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.
    ...

Command-Line Help

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 Shell

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).

Scripting RT

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.

Shell Functions

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.

Shell Aliases

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'

MIME

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";

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, interactive tutorials, and more.

Start Free Trial

No credit card required