View source for 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 &gt; 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&gt;

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

 [tbrumm@messenger ~]$ rt
 rt&gt; 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&gt;

The normal usage looks like this:

 rt &lt;action&gt; [options] [arguments]

<u>_The RT Actions:_</u>

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)

<u>_The RT Objects:_</u>

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

<u>_The RT Types:_</u>

You can currently operate on the following types of objects:

 - tickets
 - users
 - groups
 - queues

=== Working with Links via the CLI ===

Syntax:

 rt link [-d] &lt;id-A&gt; &lt;link&gt; &lt;id-B&gt;

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

=== Examples ===

To Make a new user:

<source lang="sh">rt create -t users add Name=userName EmailAddress=email@address.com Password=password</source>

To get a users information:

<source lang="sh">rt show user/userName</source>

To create a ticket in Quux:

<source lang="sh">rt create -t ticket set subject='New ticket' queue=Quux priority=10 add cc=foo@example.com</source>

To edit a ''Custom Field'' (use prefix <code>CF-</code>):

<source lang="sh">rt edit ticket/63066 set CF-Release-Status='Deployed'</source>

To show all info for a specific ticket:

<source lang="sh">rt show ticket/3</source>

To show specific fields for a ticket:

<source lang="sh">rt show -t ticket 42 -f id,subject,status,queue,owner,priority</source>

To show the history for a ticket:

<source lang="sh">rt show ticket/42/history -f created,content,description</source>

To add a comment to a ticket:

<source lang="sh">rt comment ticket/42 -m "this text will be added as a comment to the ticket"</source>

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 &lt;someticketnumber&gt;

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