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