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