CLI

Guide to the RT Command Line Interface (CLI)

RT has a command line tool you can use to interact with your RT install. You can execute commands from your terminal with the 'rt' command or launch the rt shell with 'rt shell' and execute commands there.

The nice thing about the RT CLI is you can run it on a different machine from your RT install.

---

Setting up a working environment for RT CLI

Before you can start using the RT CLI you have to set up a working environment for your RT, here we have two possible ways:

Environment Variables

Setting environment variables is a good way to start using the CLI. The following variables could be defined:

• RTUSER
• RTPASSWD
• RTSERVER
• RTDEBUG
• RTQUERY
• RTORDERBY
• RTCONFIG
• EDITOR or VISUAL

You can set the important variables inside a BASH in this way:

export RTUSER=your.rtusername
export RTPASSWD=your rt password
export RTSERVER=http://your.rt3.installation

RT Config File

Create at the users Home Directory a .rtrc file with the following min. Options:

server http://your.rt3.installation
user your.rtusername
passwd your rt password

Advanced settings can also be defined here:

query your default query string ("Status = 'new' and Priority > 5")
orderby your default sort order

---

Let's start working with the CLI - the first call

I assume you have installed RT with the default layout (/opt/rt3) then you can find the RT CLI executable under /opt/rt3/bin its called rt

[tbrumm@messenger ~]$ rt
rt>

This will bring you directly to the rt cli shell. Now lets try us to getting help:

[tbrumm@messenger ~]$ rt
rt> help

 ** THIS IS AN UNSUPPORTED PREVIEW RELEASE **
 ** PLEASE REPORT BUGS TO rt-bugs@bestpractical.com **

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>

The normal usage looks like this:

rt <action> [options] [arguments]

_The RT 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)

_The RT Objects:_

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

_The RT Types:_

You can currently operate on the following types of objects:

- tickets
- users
- groups
- queues

Working with Links via the CLI

Syntax:

rt link [-d] <id-A> <link> <id-B>

Creates (or, with -d, deletes) a link between the specified tickets. See 'rt help link' for more details.

Examples

To Make a new user:

rt create -t users add Name=userName EmailAddress=email@address.com Password=password

To get a users information:

rt show user/userName

To create a ticket in Quux:

rt create -t ticket set subject='New ticket' queue=Quux priority=10 add cc=foo@example.com

To edit a Custom Field (use prefix CF-):

rt edit ticket/63066 set CF-Release-Status='Deployed'

To show all info for a specific ticket:

rt show ticket/3

To show specific fields for a ticket:

rt show -t ticket 42 -f id,subject,status,queue,owner,priority

To show the history for a ticket:

rt show ticket/42/history -f created,content,description

To add a comment to a ticket:

rt comment ticket/42 -m "this text will be added as a comment to the ticket"

To make a report of tickets in a queue: not resolved, that are 30 days old:

rt ls -o -Created -t ticket "Queue = '4' AND Status != 'resolved' AND \
   Created < '30 days ago'" -f id,subject,status,created,lastupdated,owner \
   | mail -s "Report of tickets 30 days old" username@email
   

Creating tickets with multiple lines of text

To Create a ticket with multiple lines of text in the body indent the lines with a space. Example:

rt create -t ticket set queue=myqueue subject="MultiLine Test" text = "Line 1
 Line 2
 Line 3
"

To Enter multiple lines of text into the interactive Form, put a space at the begining of the second line, third line, etc. Example:

rt comment <someticketnumber>

Now, if your editor is vi/m you see something like this:

Ticket: 1311875
Action: comment
Cc:
Bcc:
Attachment:
TimeWorked:
Text: now put your text here.
 begin each new line with a space !
 also this one. and so on...