TeamForge CLI Command Reference

This page documents the Digital.ai TeamForge command line interface (CLI) commands. For an introduction to navigation and command levels, see Introduction and Basic Navigation. For list handling, see Working with Lists.

api​

The api command accesses any TeamForge SOAP API method. It works in much the same way as the describe command. Without arguments it lets you select the service and method you want to invoke.

ctf> api 2.19
CollabNet->getApiVersion
5.4.0.0
ctf> api CollabNet->getApiVersion
CollabNet->getApiVersion
5.4.0.0

Provide arguments for methods that need them as a comma separated list. If you do not provide them, the CLI prompts for them.

ctf> api 2.37 joeuser

ctf> api 2.37
CollabNet->getProjectListForUser
   sessionId: soapCF51D51EF8AA50747F62C60D1D9BE93C
   userId: >

Data returned from method calls is presented using the CLI list and object views as appropriate. For example, the following two commands produce the same results.

ctf> api 2.37 `whoami print username`
ctf> my projects

rest​

The rest command accesses any TeamForge REST API method.

Usage

rest [-n] [ -m get | post | put | delete ] end_point
parameters
{
   "parameter1": "value1"
   "parameter2": "value2"
}
end

Options

Responses

Example

rest -m get ctfrest/foundation/v1/objects/artf1065/comments
parameters
{
    "sortby": "dateCreated",
    "offset": "0",
    "count": -1
}
end

echo CONTENT: $CONTENT
echo CONTENT_HASH: $CONTENT_HASH

set COUNT 0
for item in $CONTENT_HASH.items
do
    set -e COUNT expr $COUNT + 1
    echo $CONTENT_HASH.items[$COUNT].id
done

Data returned from a method call is presented as JSON content and also as hash content, so that it is easy to process.

rrest​

The rrest command accesses any RESTful application.

Usage

rrest -a alias -p [-h] [-n] [ -m get | post | put | delete ] end_point
headers
{
   "header1": "value1"
   "header2": "value2"
}
end
parameters
{
   "parameter1": "value1"
   "parameter2": "value2"
}
end

Options

Responses

Example 1-Getting specific artifact comments

rrest -a cu248 -m get ctfrest/foundation/v1/objects/artf1065/comments
parameters
{
    "sortby": "dateCreated",
    "offset": "0",
    "count": -1
}
end

echo CONTENT: $CONTENT
echo CONTENT_HASH: $CONTENT_HASH

set COUNT 0
for item in $CONTENT_HASH.items
do
    set -e COUNT expr $COUNT + 1
    echo $CONTENT_HASH.items[$COUNT].id
done

Example 2-Modifying a project title and description

set TITLE New Title
set DESC New Description
set ACCESS private

rrest -a cu248 -h -m PATCH ctfrest/foundation/v1/projects/$PROJ
headers
{
  "If-Match": "*"
}
end
parameters
{
  "title": "$TITLE",
  "description": "$DESC",
  "accessLevel": "$ACCESS"
}
end

echo CODE: $CODE
if `validjson $CONTENT`
do
  printjson $CONTENT
else
  echo CONTENT: $CONTENT
done

cache​

The CLI has a built-in cache that improves performance. It is used most often with the lookup feature of the CLI.

cache [ depth | flush | items ]

In the following example the title of the tracker that artf1234 belongs to is printed. The artifact itself has only the tracker id (folderId), but the CLI can do a lookup based on that id.

go artf1234 print folderId->title

The first time this is used, the CLI downloads the tracker data object to display its title. The second time, the CLI uses the cached copy of that object. This is especially useful when operating on lists where many lookups happen.

my artifacts
 foreach -row
 do
  print id,title,status,folderId->title
 done

The cache command has several options to control and view the contents of the cache.

cgi​

The cgi command provides access to the CGI object. This is mainly useful when the CLI is used as part of the CLI Server.

set -e VAR cgi param inputVariable

cgi header text/plain

cgi header text/plain, 500

connect​

Connect to a TeamForge server. If the CLI has saved your username and password, or the last session key used is still active, it reconnects without prompting.

connect [ alias | to url ] [ as username ] [ with (key|token|password) value ] [ use apilevel ]

ctf> connect cocn

ctf> connect to https://ctf.open.collab.net

ctf> connect cocn as joeuser

ctf> connect cocn use 5.4.0.0

ctf> connect to https://ctf.open.collab.net as joeuser use 5.4.0.0

If this is the first time you are connecting to a new TeamForge server, you are prompted to enter your username and password. If the savePassword property is enabled, which is the default, the CLI saves your password in an obfuscated format. See options.

Normally you connect using the alias for your server entry. An alias is a name you give to a TeamForge server to make it easier to connect to. Edit the alias and other server settings with the server command.

You can also connect using the URL, or a portion of the URL, of the server you want to connect to. The server must already be configured for this to work. In the following example, any unique portion of the URL can be used, such as connect to ctf.

connect to https://ctf.open.collab.net

Connecting as a Different User​

To connect as a different user than the one currently configured for the server, use the as clause. This saves the new username with the server record.

connect cocn as joeuser

Connecting with a Key, Token, or Password​

TeamForge has several methods available to create a session. The with keyword accesses these methods. You can also use with to specify a password at connect time instead of having one pre-configured or prompted for.

Connecting with a Different API Level​

Much like the use command, you can specify the API level to use.

connect cocn use 5.4.0.0

This forces the CLI to use the API methods available for that version instead of the current TeamForge version. This is useful to ensure compatibility of your scripts if any of the API methods you use change from version to version.

rconnect​

The rconnect command accesses TeamForge applications.

Usage

rconnect -a alias -p [-h] [-n] [ -m get | post | put | delete ] end_point
headers
{
   "header1": "value1"
   "header2": "value2"
}
end
parameters
{
   "parameter1": "value1"
   "parameter2": "value2"
}
end

Options

Responses

Example 1-Getting specific artifact comments

rconnect -m get ctfrest/foundation/v1/objects/artf1065/comments
parameters
{
    "sortby": "dateCreated",
    "offset": "0",
    "count": -1
}
end

echo CONTENT: $CONTENT
echo CONTENT_HASH: $CONTENT_HASH

set COUNT 0
for item in $CONTENT_HASH.items
do
    set -e COUNT expr $COUNT + 1
    echo $CONTENT_HASH.items[$COUNT].id
done

Example 2-Modifying a project title and description

set TITLE New Title
set DESC New Description
set ACCESS private

rconnect -h -m PATCH ctfrest/foundation/v1/projects/$PROJ
headers
{
  "If-Match": "*"
}
end
parameters
{
  "title": "$TITLE",
  "description": "$DESC",
  "accessLevel": "$ACCESS"
}
end

echo CODE: $CODE
if `validjson $CONTENT`
do
  printjson $CONTENT
else
  echo CONTENT: $CONTENT
done

delete​

To delete a TeamForge object you need to know the id number of the object and you must put the word YES in capitals at the end of the command.

ctf> delete artf12345 YES

describe​

The describe command gives documentation on all of the TeamForge SOAP API methods. With no arguments, describe displays a list of all the services. Choose a service and all the methods in that service are displayed. Pick a method and it displays the documentation for that method.

ctf> desc
 1.CategorizationApp   7.IntegrationDataApp  13.ScmApp
 2.CollabNet           8.NewsApp             14.ScmListenerService
 3.DiscussionApp       9.PageApp             15.SimpleFileStorageApp
 4.DocumentApp        10.PlanningApp         16.TaskApp
 5.FileStorageApp     11.PluggableApp        17.TrackerApp
 6.FrsApp             12.RbacApp            18.WikiApp
select> 18
 1.addAttachment       4.getFormattedWikiPageText  7.getWikiPageList
 2.createWikiPage      5.getWikiPageData           8.setWikiPageData
 3.deleteWikiPage      6.getWikiPageDataByName
select> 2

WikiApp->createWikiPage
  Arguments:
       sessionId => xsd:string
       projectId => xsd:string
            name => xsd:string
        wikiText => xsd:string
  versionComment => xsd:string

  Returns Wiki page data object.

  Since 4.3

  Provides SOAP web service for wiki application.

  Change HistoryVersion 4.4: No changes. Creates a new wiki page with
  the specified name, text, etc.

You can also give this command partial arguments to reach the service and method you need more quickly.

desc 18.
desc 18.2
desc WikiApp->createWikiPage

Searching API Documentation​

To search the API documentation, use the -k option with the keywords you are interested in. Matching methods are returned in a list. Choose a method to get the full documentation on that method.

desc -k project admin
 1.CollabNet->listProjectAdmins  2.CollabNet->listProjectAdmins2  3.RbacApp->getUserRoleList
select>

edb​

Send a query to the events database, that is, Orchestrate, using its query language.

edb restrict_to builds ; after 2.weeks.ago ; group_by_field "status"

Initialization

The CLI queries the currently connected TeamForge instance to determine the Orchestrate URL. If the default URL does not work, use the init command to set the URL.

edb init http://<orchestrate-url>

Query templating

The CLI treats the query string as a simple template, which makes it easier to reuse queries in different contexts.

set query restrict_to builds ; field_contains ["status.type", ["[:var:type:]"] ] ; limit 3
set type FAILURE
edb $query

env​

When the CLI starts, it copies the user environment variables to make them available in the CLI.

env

The env command shows all the variables in the CLI, both those loaded from the environment and those defined using the set command at the main ctf prompt.

fetch​

The fetch command downloads or grabs content from the web interface of a TeamForge site. In some cases there may be operations that the web UI can do that are not available, or are too complex to do, through the API. The fetch command can grab web pages, submit HTML forms, and download files.

fetch [-n] [ -m get | post ] /sf/sfmain/do/something [ as filename ]
fields
  username jsmith
end

fetch -n /sf/global/do/about

fetch -m post /sf/sfmain/do/broadcastMessage
fields
  broadcastMessage Scheduled Site Maintenance on Thursday
end

Options

Fields

Many pages and forms in TeamForge require a number of fields to be set. For example, to get the news page from the My Workspace page, you need to set the selectedTab variable to news.

fetch /sf/sfmain/do/myPage
fields
  selectedTab news
end

if $CODE == 200
do
  message info Success!
done

Responses

Interactive use

When you use fetch interactively, the fields/end syntax is optional. The CLI prompts for more fields until you enter a blank line.

fetch -m post /sf/sfmain/do/broadcastMessage
broadcastMessage Scheduled Site Maintenance on Thursday

Inspecting the CONTENT variable

To look for a line that matches a certain pattern, use the for and if commands. Because the results of the fetch command are returned as a series of lines, the for command can iterate over each line and pass it to any commands in its do/done block.

for LINE in $CONTENT
do
  if $LINE =~ /Date/
  do
    echo $LINE
  done
done

See also the match command, which parses lines and extracts specific values from them.

filters​

The CLI has its own saved filters, stored locally. The filters command shows the list of local saved filters.

ctf> filters
  1) tracker : none
  2) tracker : allOpen
  3) tracker : thisWeek
  4) tracker : closedToday
  5) tracker : test
ctf/list(5)>

The command takes an optional argument of the filter name, which jumps directly to the edit interface for that filter.

ctf> filters allOpen
tracker : allOpen
ctf/ctf/filter102>

To create a filter, use the add command. You can do this either at the main ctf prompt or in the filter list.

ctf> filter add tracker myFilter

ctf/list(5)> add tracker myFilter

The CLI creates an empty filter object with all the available filter fields. Date type fields can be set to the same relative date phrases that the date command takes. This lets you have a filter that always gives the appropriate result when it runs. For example, to get a list of open artifacts modified this week, set the modifiedAfter field to last sunday and the statusClass to Open.

find​

The find command gives access to the full text search engine in TeamForge. To use it, specify the tool to be searched. Supported tools include the following.

ctf> find project labs
  1) proj1437: CollabNet Labs
ctf/list(1)>

include​

Sometimes CLI scripts have common code that other scripts need to use. The include command loads and runs the commands from another script.

include myOtherScript.cli

The include command looks at the absolute path of the given filename to see whether it exists. If not, it searches the directories in the CTF_LIB environment variable, which is expected to be a colon separated list of directories.

When a script is running, you can access the current script name and the directory it was invoked from with the SCRIPT_NAME and SCRIPT_PATH variables. This is useful when an included script needs to load additional content from the same directory it was called from.

template load $SCRIPT_PATH/myReport.html

index​

Use this command to tell TeamForge to reindex an object on the site if the object does not appear in search results as expected. It may take several minutes before the object shows up in the results.

index artf1234

load​

Import data from an external file into a variable.

load DATA file.txt

output -tmp
go tracker1234 print description
output
load DATA $TMPFILE

Parsing options

By default, files are loaded as UTF-8 text files. The CLI can import files of various types into structured variables to make them easy to interact with.

load -xml config config.xml

echo $config.attribute.value

loadcsv​

To work with a set of data in an external CSV file, the loadcsv command imports the data and presents it as a standard CLI style list.

loadcsv listofstuff.csv

loadcsv -encoding iso-8859-1 file.csv

An optional -encoding option tells the CLI to convert the imported CSV file from the specified format to UTF-8.

logoff​

Disconnects the CLI from the current TeamForge server and invalidates the session key.

logoff

match​

The match command compares the given pattern to either a field in a data object or a CLI variable.

match FIELD|VAR pattern

When match is used at the main CLI prompt (ctf>), it examines CLI variables. When you are viewing an object, it examines fields in the current object. Patterns can be full regular expressions and can take advantage of back references.

Back References-Extracting Values​

A back reference is a way to look back at a value that was saved because it matched the specified pattern. The parentheses around the pattern tell the match command which part to save. The saved value is stored in the MATCH array variable.

ctf> set EXAMPLE The big dog was 12 years old.
ctf> match COLUMNS (\d+)
ctf> echo $MATCH[0]
12

ctf/artf1234> match title ^(\w+)

In the above example, \d matches one or more numbers from the COLUMNS variable, and \w matches one or more word characters from the title of artf1234.

ctf> set DATE Thu Oct  6 10:33:41 EDT 2011
ctf> match DATE \d+:(\d+):\d+ (\S+)

ctf> echo $MATCH[0]
33
ctf> echo $MATCH[1]
EDT

In the above example, the DATE variable is set to a date. The match command is given the pattern \d+:\d+:\d+ \S+ to match the time and time zone portion of the date. The parentheses around \d+ and \S+ tell the match command to save those two patterns in the MATCH variable.

Patterns​

A pattern in the CLI is based on the Perl regular expression syntax. In most cases, patterns used in the CLI are passed as-is to the Perl interpreter. For more information, see Perl Regular Expressions.

A pattern can be a literal string or contain meta-characters, that is, characters that represent other characters. For example, \d means a number. A single \d can be any number from 0 through 9, which is a single digit.

\d matches:
  1
  1234
  1.1

In the above, all three examples return a 1. This is because \d matches just a single value. To change the behavior of the match, use a modifier.

With an asterisk as a modifier, \d* matches 5, 1234, and a blank line, whereas a + requires at least one digit to match.

Common meta-characters

my​

Each of these commands creates a list filtered appropriately for the currently logged in user.

my artifacts
my history
my tasks
my projects

As with any command that results in a list, you can add more commands to the line to invoke list commands.

my projects where title like labs

my artifacts foreach print id,status,title

options​

The TeamForge CLI has a number of options that you can configure to control the behavior of the CLI. Once set, the options stay set until changed back.

ctf> options
CLI Options
ctf/cli001> details
  1. autoCommit    => 1
  2. autoOverlay   => 1
  3. auto_proxy    =>
  4. cacheDepth    => 20
  5. chunksize     => 6553600
  6. dateFormat    => %C
  7. filter_commit => filter130
  8. filter_task   =>
  9. filter_tracker => filter102
 10. filter_user   =>
 11. hideErrors    => 0
 12. http_proxy    =>
 13. https_proxy   =>
 14. id            == cli001
 15. lastServer    => fcn
 16. messages      => 1
 17. pagerLines    => 15
 18. proxy_pass    => ******
 19. proxy_user    =>
 20. returnOnEnter => 1
 21. savePassword  => 1
 22. showSummary   => 1
 23. userkey       => 6nvP1qLbWBGWWW20oqTUdJvQpH1IzbGN4
ctf/cli001> set hideErrors 1

ctf> options set messages 0

output​

When you open an output file with this command, all echo and print statements write their results to this file. Use this when creating reports that need to be saved.

ctf> output report.out
file opened.
ctf> output
file closed.

ctf> output -tmp
ctf> echo $TMPFILE

The command works like a toggle switch. The second usage closes the output file, and echo and print statements again send their results to the console.

The -tmp option tells the output command to create a temporary file. The filename is saved in the TMPFILE variable. Temporary files are removed automatically when the CLI exits.

pathmap​

Convert a planning folder path, document folder path, or category path to its TeamForge id number.

pathmap planFolder proj1234 folder > folder > folder
pathmap docFolder  proj1234 folder > folder > folder
pathmap category   category > category > category

The planFolder and docFolder functions both take a project id and a folder path. The category function takes only a path argument.

replace​

Edit any variable or object field using the replace command. It has two forms, simple and regular expression.

replace field findthis replacewiththis
replace VAR /find/replace/

The simple method finds all occurrences of a word and replaces it. The search is case insensitive and the replacement matches the case used in the command.

The regular expression version gives you more control over the replacement. In the basic form, only the first occurrence of a word is replaced, the search is case sensitive, and the replacement matches that used in the expression.

/find/replace/

Several modifiers can be used here.

For more complete details on supported expressions, see Perl Regular Expressions.

replace field /(\d+)/\$1/

server​

The server command manages the list of TeamForge servers the CLI can connect to. To add a server, use the add command in the server list, or as an argument to the server command, followed by an alias of your choosing and the URL of the TeamForge site.

ctf> server
  1) cocn    : https://ctf.open.collab.net
ctf/list(1)>

ctf/list(1)> add mysite https://forge.mysite.com

ctf> server add mysite https://forge.mysite.com

To connect to a server, either use the connect command at the ctf prompt, or type connect when editing a server.

ctf> connect mysite
Connected to mysite as dspeers

ctf> server cocn
cocn    : https://ctf.open.collab.net
ctf/ctf/svr101> connect
Connected to cocn as dspeers

rserver​

The rserver command manages the list of any RESTful application servers the CLI can rconnect to a TeamForge application and rrest to any RESTful applications. To add a server, use the add command in the server list, or as an argument to the server command, followed by an alias of your choosing and the URL of the TeamForge site.

ctf> rserver
  1) cocn    : https://ctf.open.collab.net
ctf/list(1)>

ctf/list(1)> add mysite https://forge.mysite.com

ctf> rserver add mysite https://forge.mysite.com

set​

The CLI supports the use of environment variables in reports and scripts, and to control the behavior of the tool. To use a variable, precede it with a dollar sign.

ctf> set EDITOR emacs
ctf> set COLUMNS 100

ctf> echo $EDITOR
emacs

ctf> set COLUMNS 100
ctf> echo $COLUMNS
100

ctf> set -e DATE date

Create multi-level complex objects using a dot (.) separator.

ctf> set report.property.title My Report
ctf> set report.property.name other

ctf> echo $report
property

ctf> echo $report.property
title,name

If only a portion of the complex object is used, the CLI returns a list of the keys for the next level of the object.

You can also use variables as part of the complex object path.

ctf> set report.property.title My Report
ctf> set p property

ctf> echo $report.$p
title

ctf> echo $report.$p.title
My Report

The -e option tells the CLI to treat the right hand side as code that should be run, so that the return value of that command is in the variable.

Variables used by the CLI

silent​

The CLI has a number of options that are often changed when the CLI is running a script. This command overrides those options without changing them, so that when the script is done, any options the user set are left as they were.

ctf> silent

ctf> silent [on|off]

In a script, put this command at the beginning and the script runs silent from there. When you are creating a script, it is good practice to leave this out so that you can see any errors or messages that arise.

Normally the silent command acts as a toggle, but you can give it an argument to tell it explicitly which mode you want it to be in. This is useful when you are using scripts with the include command.

When enabled, it acts as an override for the following options.

• hideErrors is on
• messages is off
• showSummary is off

To see whether silent mode is on, use the stat command.

sql​

Send a SQL query to the TeamForge ad-hoc query interface. Results are returned in a list format and can be used like any other CLI based list.

sql select id,username from sfuser limit 10

sql -dm select count(*) from artifact_daily_snapshot_fact

The -dm option, added in CLI 1.4.3, tells the CLI to query the TeamForge datamart instead of the operational data store.

Result limits

TeamForge limits the results to 1000 records. To get more than that, use the LIMIT and OFFSET commands in PostgreSQL.

For Oracle systems, use the special rownum field that Oracle adds to query results.

select * from sfuser where rownum > 100 and rownum < 200

You can increase the result limit by changing the ADHOC_QUERY_RESULTS_LIMT option on the TeamForge server itself.

Query templating

The CLI treats the query string as a simple template, which makes it easier to reuse queries in different contexts.

set query select count(*) from [:var:tablename:]
set tablename sfuser
sql $query

stat​

When the CLI is connected to a server, the stat command gives a number of status values about the server.

ctf> stat
TeamForge CLI : 1.2
  SVN Revision : 656 - ok
  Perl SDK    : 2.5-2
Current server: ctf6
  Server URL  : https://ctf6latest.collab.net
  Version     : 6.1.0.0
  API Version : 5.4.9.0
  API Level   : 5.4.1.0
  User        : jsmith
  Session Key : soap82Exxxxx
Silent Mode   : off

Save the results of stat in a variable using the as syntax.

stat as stat
echo $stat.version

To see the names of the fields you can use, use the -keys option.

stat -keys

systemlog​

Without any arguments, this command lists all of the available log files on the current TeamForge server. Given a matching filename, this command downloads the specified log file from TeamForge.

systemlog

systemlog httpd/ssl_access_log

The file is downloaded to the current directory using the filename portion of the log file path. The file must not already exist on your system, or it is reported as an error.

tmpfilter​

Create and use a temporary filter for use with API methods that are able to use them. Once a tmpfilter is created, it is used with the next API call of the appropriate type.

tmpfilter init type
tmpfilter init type SoapType
tmpfilter set field value
tmpfilter unset
tmpfilter show

tmpfilter init tracker
tmpfilter set priority 1
go tracker1234 items

Valid filter types are tracker, task, user, and commit.

The init command takes an optional SOAP data type. Some API methods that use filters have extended filter features. For example, TrackerApp->getArtifactList3 can use an Artifact3SoapDO based filter.

tmpfilter init tracker Artifact3SoapDO
tmpfilter set planningFolderId plan1234
api TrackerApp->getArtifactList3 proj1234

To go back to using the currently selected saved filters, unset the tmpfilter. To see all the available filter fields in the current tmpfilter, use the show argument.

To see which API methods support CLI filters, use the following CLI command.

eval dump \%FILTERS

unset​

Remove the specified variable from the environment. If the variable name is a complex value, the end name is removed from the variable.

unset varname

use​

Normally the CLI adapts automatically to use the closest version of the API that the connected version of TeamForge supports. For example, TeamForge 5.4.0.1 uses the 5.4.0.0 API.

use 5.4.0.0

The use command forces the CLI to use a specific version of the SOAP API instead of the default. The stat command shows the current API version settings.

versioncheck​

When you write CLI scripts, it is good practice to note the version of the CLI you are using. When you use the versioncheck command, the CLI checks the current CLI version to make sure it matches the specified version.

versioncheck 1.1

If the running version of the CLI is older than the noted version, it triggers a fatal error and tells the user that a newer version of the CLI is required to run the script.

whoami​

This is the same command as the whois command, except that it automatically loads the user record for the currently connected user.

ctf> whoami

whois​

This is a simple get user data call to find information on another user on the system.

ctf> whois joeuser

TeamForge 5.4 added features to this call, such as lastLogin and license type. To access those added features, use the direct api method instead.

ctf> api CollabNet->getUserData2 joeuser