# TCL Script Writer Reference

## Using the scripting interface <a href="#toc492984194" id="toc492984194"></a>

The CAP Console ships with a scripting interface to facilitate automated management by other tools. The scripting interface is based on the TCL (Tools Command Language) version 8.4 syntax and commands, but also includes a number of CAP specific commands.

As scripting is a programming interface, the scripting engine is not multi-lingual. It is invoked by a simple **HTTP/S POST** command to the URL:

`http://<server>/console/ScriptRunner`

The parameters for the POST are as follows:

<table data-header-hidden><thead><tr><th width="267"></th><th></th></tr></thead><tbody><tr><td>Parameter</td><td>Value</td></tr><tr><td>user</td><td>The console user ID under which the script will be executed</td></tr><tr><td>password</td><td>The password for the user</td></tr><tr><td>script</td><td>The script to execute</td></tr></tbody></table>

All parameters should be UTF-8 encoded.

## Learning TCL <a href="#toc492984195" id="toc492984195"></a>

It is beyond the scope of this manual to provide complete details of the TCL language. TCL has been in use for many years and plenty of online resources exist for learning the language. An excellent primer can be found here:

[`https://www.tcl.tk/`](https://www.tcl.tk/)

Sample scripts are included in the **ConsoleCLI/README.md** file distributed with CAP Console.

## Using ConsoleCLI for script execution <a href="#toc492984195a" id="toc492984195a"></a>

ConsoleCLI is a standalone command-line tool distributed with CAP Console for remote script execution. It supports both file-based and inline script execution:

**File-based execution:**

```bash
java -jar ConsoleCLI.jar -h <host> -u <user> -p <password> -f <scriptfile>
```

**Inline execution:**

```bash
java -jar ConsoleCLI.jar -h <host> -u <user> -p <password> -s "<script>"
```

**Example - List all users:**

```bash
java -jar ConsoleCLI.jar -h localhost -u admin -p mypassword -s "set users [userList]; puts \"User count: [\$users length]\""
```

ConsoleCLI is ideal for automation, CI/CD pipelines, and integration with external systems. For complete documentation including all CAP-specific TCL commands and workflow examples, see **ConsoleCLI/README.md** in your CAP Console installation.

## Testing scripts <a href="#toc492984196" id="toc492984196"></a>

To assist with testing scripts interactively, a web-based script runner is available:

`http://<server>/console/scriptRunner.jsp`

This page allows you to enter a user ID and password, as well as a script, and submit it to the console. The output from the submission is returned to the browser. This is useful for debugging and verifying scripts before automating them with ConsoleCLI.

## CAP specific TCL extensions <a href="#toc492984197" id="toc492984197"></a>

CAP introduces a number of extensions to the standard TCL language. All of the extensions relate to specific console management tasks.

In addition, output written with the "puts" command is written to the HTTP Response stream rather than `STDOUT`.

### Result formats: handles, lists, JSON

CAP TCL commands return results in three styles:

* **Java object handles** - for example `serverStatus` returns an object whose methods (`getStatus`, `isRunning`, ...) are called via `[$obj method]`. Use when a script needs to read many fields from a single record.
* **Java arrays** - for example `serverList` returns a string array. Iterate with `[$arr length]` and `[$arr get $i]`. Use for simple membership tests.
* **JSON strings** - every accessor that returns a handle or array has a sibling ending in `Json` (`serverListJson`, `serverStatusJson`, `getUserJson`, `userListJson`, `getAuditJson`, `getAuditNativeJson`). These return a UTF-8 JSON string that can be printed with `puts`, parsed via `package require json`, or piped to an external tool. The JSON shape matches the REST response bodies that CAP will expose in a future release, so scripts written against the `Json` variants remain meaningful after the transition.

`puts` prints handles and arrays as `java0xNN` object identifiers - always call methods on them rather than printing them directly. Use the `Json` variants when you need a printable, parseable, or transportable representation.

### Command: createUser <a href="#toc492984198" id="toc492984198"></a>

The **createUser** command creates a new console user. The command takes a number of parameters to correctly define a user in the console:

<table data-header-hidden><thead><tr><th width="200"></th><th></th></tr></thead><tbody><tr><td>Parameter</td><td>Value</td></tr><tr><td>Logon</td><td>The console user ID for the new user</td></tr><tr><td>Name</td><td>The full name of the user</td></tr><tr><td>Password</td><td>The initial password for the user</td></tr><tr><td>Email</td><td>The email address of the user</td></tr><tr><td>Type</td><td><p>The user type. Valid values are:</p><p>0 = Administrator</p><p>1 = Standard User</p><p>2 = Super User</p><p>3 = Security User</p></td></tr><tr><td>Role</td><td>The role name for the user. Can be blank if no role is required.</td></tr><tr><td>Time Zone</td><td>The new users time zone. Must correspond to the time zone list found in the appendixes of this manual.</td></tr><tr><td>Additional Auth</td><td><p>The class name of any additional authentication settings. Can be blank if no additional authentication is required. Please note that only basic authentication selections are available. Overrides (such as the number of digits for one-time emails) are not supported. Currently the following are valid additional auth classes:</p><p>software.tomorrow.authenticate.OneTimeEmailPlugin</p><p>software.tomorrow.authenticate.LocalHostPlugin</p></td></tr></tbody></table>

The following script snippet shows an example of how to use this command:

```
createUser test123 "Test User" test123 test@test.com 1 "" GMT ""
```

This command can only be executed with administrator or security authority.

### Command: deployConfiguration <a href="#toc492984199" id="toc492984199"></a>

The deployConfiguration command deploys a specific configuration to a nominated server. Only configurations located in a repository can be deployed using this command. The parameters for the command are Server ID, Repository Name and Configuration Name. The following script snippet shows an example of how to use this command:

```
deployConfiguration Qwerty "Product Trial" BasicWebTrial
```

The command will wait for the deployment task to complete before continuing. The deployment does not result in a server restart. The stopServer and startServer commands should be used after this command to ensure that the deployed configuration takes effect. This command is only valid for production servers.

### Command: deployContent <a href="#toc492984199a" id="toc492984199a"></a>

The deployContent command deploys content files from a repository to a nominated server. Content repositories are located in the Console content folder and contain HTML, CSS, JavaScript, and other web assets. The parameters for the command are Server ID and Repository Name. The following script snippet shows an example of how to use this command:

```
deployContent LocalProxy "AI Spark"
```

The command will wait for the deployment task to complete before continuing. The deployment triggers a live reload of content on the target server without requiring a server restart. Changes are immediately available to end users. This command is only valid for production servers.

### Command: installExtension <a href="#toc492984199b" id="toc492984199b"></a>

The installExtension command installs an extension from the rules catalog into the Console database. Extensions must first be copied to the catalog directory (HOME/Console/rules/Version 11/) before installation. The command invokes the extension's RulesInstaller.install() method to create InputAdaptors, CredentialsVault entries, or other database records. The parameters for the command are Extension Name and Version. The following script snippet shows an example of how to use this command:

```
installExtension "RulesStress-EXTENSION.zip" "Version 11"
```

The command returns true if installation succeeded, false otherwise. Extensions without a RulesInstaller (such as RulesBaseFactory) will return true but perform no database setup, as they only provide rules.xml definitions. This command can only be executed with administrator authority.

### Command: deleteUser <a href="#toc492984200" id="toc492984200"></a>

The deleteUser command deletes a user based on a provided user ID. The following script snippet shows an example of how to use this command:

```
deleteUser super
```

This command can only be executed with administrator or security authority.

### Command: getAudit <a href="#toc492984201" id="toc492984201"></a>

The getAudit command retrieves a subset of the internal CAP audit log. The following snippet shows an example of how to use this command:

```
set clause "WHERE ACTIONTIME>1425064936463 ORDER BY ACTIONTIME DESC"
set auditRows [getAudit $clause]
puts "Row count = [$auditRows length]<p>\n"
for { set i 0 } { $i < [$auditRows length] } { incr i } {
puts "[$auditRows get $i]<p> \n"
}
```

The above commands retrieve all audit log entries after the Java Time Stamp 1425064936463.

This command can only be executed with administrator or security authority.

### Command: getAuditJson

The **getAuditJson** command is the JSON-returning sibling of `getAudit`. It emits a JSON array of row objects with the same labelled fields (`action`, `elementType`, `source`, formatted `actionTime`) ready to print or parse:

```
set clause "WHERE ACTIONTIME>1425064936463 ORDER BY ACTIONTIME DESC FETCH FIRST 10 ROWS ONLY"
puts [getAuditJson $clause]
```

A sample response (truncated):

```json
[{"action":"Login","elementType":"User","elementId":"admin","source":"Console",
  "actionUser":"admin","actionSourceIp":"127.0.0.1",
  "actionTime":"2026 Apr 30, Thu 09:56:01 Eastern European Summer Time","details":"OK"}]
```

Use this variant when piping to `package require json` or to external tooling. This command can only be executed with administrator or security authority.

### Command: getAuditNative <a href="#toc492984201a" id="toc492984201a"></a>

The getAuditNative command is similar to getAudit but retrieves audit log entries in native format rather than formatted output. The following snippet shows an example of how to use this command:

```
set clause "WHERE ACTIONTIME>1425064936463 ORDER BY ACTIONTIME DESC"
set auditRows [getAuditNative $clause]
puts "Row count = [$auditRows length]<p>\n"
for { set i 0 } { $i < [$auditRows length] } { incr i } {
puts "[$auditRows get $i]<p> \n"
}
```

This command can only be executed with administrator or security authority.

### Command: getAuditNativeJson

The **getAuditNativeJson** command is the JSON-returning sibling of `getAuditNative`. It emits the same shape as `getAuditJson` but with `action`, `elementType`, `source`, and `actionTime` left as raw numeric values for machine consumption rather than translated labels:

```
set clause "WHERE ACTIONTIME>1425064936463 ORDER BY ACTIONTIME DESC FETCH FIRST 10 ROWS ONLY"
puts [getAuditNativeJson $clause]
```

This command can only be executed with administrator or security authority.

### Command: getConfiguration <a href="#toc492984202" id="toc492984202"></a>

The getConfiguration command reads a specific configuration from a specific repository and provides access to all elements of the configuration (including the ability to update it if the user has the appropriate authority.

The following script snippet shows an example of how to use this command:

```
set cnf [getConfiguration "Product Trial" BasicWebTrial]
puts "Configuration rule set [$cnf getRuleSet]"
$cnf setTestDataDepth 20000
$cnf update
```

The above command obtains the BasicWebTrial configuration from the Product Trial repository, outputs the default rule set file name and then sets the maximum number of test records to 20,000 before updating the configuration (writing it to the file system).

The following table provides a list of all of the readable properties on the configuration object:

<table data-header-hidden><thead><tr><th width="233"></th><th></th></tr></thead><tbody><tr><td>Method</td><td>Return value</td></tr><tr><td>getAttributeLabels</td><td>An array of strings with the input field labels of the configuration</td></tr><tr><td>getAttributeNames</td><td>An array of strings with the input field names of the configuration</td></tr><tr><td>getAttributeValues</td><td>An array of strings with the input field values of the configuration</td></tr><tr><td>getContentRuleSet</td><td>The file name of the content rule set</td></tr><tr><td>getDatabaseAliases</td><td>An array of strings with the database aliases of the configuration</td></tr><tr><td>getDatabaseDrivers</td><td>An array of strings with the database drivers of the configuration</td></tr><tr><td>getDatabaseNames</td><td>An array of strings with the database names of the configuration</td></tr><tr><td>getDatabaseSchemas</td><td>An array of strings with the database schemas of the configuration</td></tr><tr><td>getDatabaseSystems</td><td>An array of strings with the database system names of the configuration</td></tr><tr><td>getDescription</td><td>The description of the configuration</td></tr><tr><td>getDirectory</td><td>The directory where the configuration is located</td></tr><tr><td>getDoneRuleSet</td><td>The file name of the completion rule set</td></tr><tr><td>getFileName</td><td>The file name of the configuration</td></tr><tr><td>getInitRuleSet</td><td>The file name of the startup rule set</td></tr><tr><td>getInputClass</td><td>The class name of the input adaptor used by the configuration</td></tr><tr><td>getInputParms</td><td>A string with the input parameters passed to the configuration upon startup</td></tr><tr><td>getLoopPrevent</td><td>The maximum number of chain point interactions before a rule set is considered looping</td></tr><tr><td>getName</td><td>The configuration name</td></tr><tr><td>getPerformanceLevel</td><td><p>The level of performance data collection</p><p>0 = Transaction counts</p><p>1 = Transaction count and inline time</p><p>2 = Transaction count, inline time and URI statistics</p><p>3 = All counters</p></td></tr><tr><td>getRuleSet</td><td>The base rule set file name</td></tr><tr><td>getServerType</td><td><p>The server type</p><p>0 = Production</p><p>1 = Test</p></td></tr><tr><td>getTestDataDepth</td><td>The maximum number of test data collected</td></tr><tr><td>getTimerDelays</td><td>An array of strings with the timer delay in seconds for each timer rule set of the configuration</td></tr><tr><td>getTimerNames</td><td>An array of strings with the timer rule set file names for each timer rule set of the configuration</td></tr><tr><td>getTimerTypes</td><td><p>An array of strings with the timer rule set types for each timer rule set of the configuration</p><p>0 = Real time</p><p>1 = Pause</p></td></tr><tr><td>isAutoStart</td><td>Set to 1 if this configuration is auto starting, 0 otherwise</td></tr><tr><td>isCollectTestData</td><td>Set to 1 if this configuration collects test data by default, 0 otherwise</td></tr><tr><td>isEchoOut</td><td>Set to 1 if this configuration provides an echo of console messages to System.out, 0 otherwise</td></tr><tr><td>isFailOpen</td><td>Set to 1 if this configuration fails open, 0 otherwise</td></tr></tbody></table>

Each of the above values can also be set using the equivalent setter method *(replacing "get"/"is" with "set")*.

Please note that for any arrays, ALL arrays in a set (attributes, databases, timer rule sets) MUST be set to the same length before invoking update.

The TCL interface only supports updating existing configurations. New configurations cannot be created using TCL and existing configurations cannot be deleted.

### Command: getUser <a href="#toc492984203" id="toc492984203"></a>

The getUser command reads a specific user and provides access to some elements of that user.

The following script snippet shows an example of how to use this command:

```
set usr [getUser test123]
puts "User name [$usr getName]"
$usr setRole analyst
$usr update
```

The above command reads the user test123, outputs the name of that user and then sets the role before updating the user.

The following table provides a list of all the readable properties on the user object:

<table data-header-hidden><thead><tr><th width="197"></th><th></th></tr></thead><tbody><tr><td>Method</td><td>Return value</td></tr><tr><td>getAuth</td><td>The class name of any additional authentication. Can be blank.</td></tr><tr><td>getCreated</td><td>The time the user was first created in the format: CCYY-MM-DD hh:mm:ss.fff based on GMT.</td></tr><tr><td>getEmail</td><td>The email address of the user</td></tr><tr><td>getLastLogon</td><td>The time of the user's last logon in the format: CCYY-MM-DD hh:mm:ss.fff based on GMT.</td></tr><tr><td>getLogon</td><td>The user ID of the user</td></tr><tr><td>getName</td><td>The name of the user</td></tr><tr><td>getRole</td><td>The role set for the user (if any)</td></tr><tr><td>getTimeZone</td><td>The users time zone. Will contain a value from the time zone list found in the appendixes of this manual.</td></tr><tr><td>getType</td><td><p>The user type. Valid values are:</p><p>0 = Administrator</p><p>1 = Standard User</p><p>2 = Super User</p><p>3 = Security User</p></td></tr></tbody></table>

Most of the above values can also be set using the equivalent setter method *(replacing "get"/"is" with "set")*. The values that cannot be set are: **Logon**, **Created** and **LastLogon**.

This command can only be executed with administrator or security authority.

### Command: getUserJson

The **getUserJson** command is the JSON-returning sibling of `getUser`. It emits the same fields as a single object plus a split `roles` array for clients that want structured access:

```
puts [getUserJson admin]
```

A sample response:

```json
{"logon":"admin","name":"Default Administration User","email":"noreply@tomorrow.software",
 "type":0,"role":"","roles":[],"timeZone":"EST","auth":"",
 "created":"2026-02-03 14:06:21.364","lastLogon":"2026-04-30 06:54:57.058"}
```

The `getUserJson` command is read-only - use `getUser` (which returns a Java object) when you need to call `setRole`, `setEmail`, or `update`. This command can only be executed with administrator or security authority.

### Command: getInstallLocation <a href="#toc492984203a" id="toc492984203a"></a>

The getInstallLocation command retrieves the installation location (home directory) of the Console. The following script snippet shows an example of how to use this command:

```
set location [getInstallLocation]
puts "Installation location = $location<p>"
```

### Command: serverList <a href="#toc492984203b" id="toc492984203b"></a>

The serverList command obtains a list of all configured servers in the console that the user is authorized to view. The response is in the form of an array of server IDs. The following script snippet shows an example of how to use this command:

```
set srvList [serverList]
puts "Server count = [$srvList length]<p>"
for { set i 0 } { $i < [$srvList length] } { incr i } {
puts "Server [$srvList get $i]<p>"
}
```

A sample output from running the above script is as follows:

```
Server count = 3
Server Console
Server LocalProxy
Server TestServer1
```

### Command: serverListDetails

The **serverListDetails** command returns a human-readable multi-line listing of visible agents, one per row, in the format `name | description | type`. The description column matches the label shown in the Console UI, making it easier to match a Coop name to a familiar agent:

```
puts [serverListDetails]
```

Sample output:

```
Console | Console Agent | Production
LocalProxy | X Agent | Production
MPServer1 | Multi-Protocol Agent | Multi-Protocol
StressTest1 | Stress Test Agent | Production
TestServer1 | Test Agent | Test
```

The `type` column is translated to the session locale.

### Command: serverListJson

The **serverListJson** command is the JSON-returning sibling of `serverList`. It emits an array of `{name, description, type, typeCode}` objects:

```
puts [serverListJson]
```

Sample output:

```json
[{"name":"Console","description":"Console Agent","type":"Production","typeCode":0},
 {"name":"LocalProxy","description":"X Agent","type":"Production","typeCode":0},
 {"name":"MPServer1","description":"Multi-Protocol Agent","type":"Multi-Protocol","typeCode":5},
 {"name":"TestServer1","description":"Test Agent","type":"Test","typeCode":1}]
```

`type` is the translated label (locale-aware); `typeCode` is the raw numeric value (0=Production, 1=Test, 2=Database, 3=Template, 4=Production with Forwarder, 5=Multi-Protocol) for programmatic comparisons.

### Command: serverStatus <a href="#toc492984205" id="toc492984205"></a>

The serverStatus command is used to interrogate the current status of a server, based on the server's ID. The following script snippet shows an example of how to use this command:

```
set srvId Qwerty
set srv [serverStatus $srvId]
puts "Server status = [$srv getStatus]<p>"
puts "Server is running = [$srv isRunning]<p>"
```

The return value from the command is a server status object. The following methods are available on the object:

<table data-header-hidden><thead><tr><th width="216"></th><th></th></tr></thead><tbody><tr><td>Method</td><td>Return value</td></tr><tr><td>getBuild</td><td>The base rules build number for the server</td></tr><tr><td>isCollectTestData</td><td><p>A flag to indicate if the server is collecting test data.</p><p>0 = No</p><p>1 = Yes</p></td></tr><tr><td>getConfiguration</td><td>The name of the configuration currently deployed on the server</td></tr><tr><td>getConfUser</td><td>The name of the user that created the current configuration used on the server</td></tr><tr><td>getConfVersion</td><td>The version of the configuration currently deployed on the server</td></tr><tr><td>getDeployErrorCode</td><td>Any error code issued (if any) when attempting to deploy the last configuration to the server</td></tr><tr><td>getDeployFrom</td><td>The repository name from which the configuration was deployed</td></tr><tr><td>getDeployTime</td><td>The time the current configuration was deployed to the server in the format: CCYY-MM-DD hh:mm:ss.fff based on GMT</td></tr><tr><td>getDeployUser</td><td>The name of the user that deployed the current configuration to the server</td></tr><tr><td>getDescription</td><td>The description of the configuration currently deployed on the server</td></tr><tr><td>getErrorCode</td><td>Any error codes detected on the server. The corresponding error messages are found in the "translation.properties" file for the console application.</td></tr><tr><td>getFlightRecorders</td><td>A string array with the IDs of any flight recorders in use by the currently deployed configuration</td></tr><tr><td>getHost</td><td>The host name of the server</td></tr><tr><td>getInputAdapter</td><td>The class name (identifier) of the input adaptor used for the current configuration</td></tr><tr><td>getInputParms</td><td>The input parameters provided to the configuration to be used in conjunction with the input adaptor. This is mainly used for file polling servers and in that instance provides the directory that is polled for files. For test servers it provides the input file name to the configuration.</td></tr><tr><td>getJavaVersion</td><td>The current version of Java used by the server</td></tr><tr><td>getLastStarted</td><td>The time the <code class="expression">space.vars.X_Agent_Name_Single</code> was last started in the format: CCYY-MM-DD hh:mm:ss.fff based on GMT</td></tr><tr><td>getLastStopped</td><td>The time the <code class="expression">space.vars.X_Agent_Name_Single</code> was last stopped in the format: CCYY-MM-DD hh:mm:ss.fff based on GMT</td></tr><tr><td>getLastTransaction</td><td>The time the <code class="expression">space.vars.X_Agent_Name_Single</code> was last invoked in the format: CCYY-MM-DD hh:mm:ss.fff based on GMT</td></tr><tr><td>getMajorVersion</td><td>The major version number of the <code class="expression">space.vars.X_Agent_Name_Single</code></td></tr><tr><td>getMinorVersion</td><td>The minor version number of the <code class="expression">space.vars.X_Agent_Name_Single</code></td></tr><tr><td>getOperatingSystem</td><td>The operating system and version of the server</td></tr><tr><td>isPolling</td><td>If the server is polling for data (feed servers)</td></tr><tr><td>getPort</td><td>The port the server is accepting instructions from</td></tr><tr><td>getRevisionVersion</td><td>The revision version number of the <code class="expression">space.vars.X_Agent_Name_Single</code></td></tr><tr><td>getRuleset</td><td>The name of the currently deployed rule set</td></tr><tr><td>isRunning</td><td>Whether the server is currently running (started).</td></tr><tr><td>getStatus</td><td>The status of the server. 0=Offline, 1=Online</td></tr><tr><td>getTestData</td><td>The number of available test data lines</td></tr><tr><td>isTraceData</td><td>If the server has trace data</td></tr><tr><td>isTraceMode</td><td>If the server is in trace mode</td></tr><tr><td>getTransactions</td><td>Number of transactions processed since last server start</td></tr><tr><td>getType</td><td><p>The agent type code:</p><p>0 = Production</p><p>1 = Test</p><p>2 = Database</p><p>3 = Template</p><p>4 = Production with Forwarder</p><p>5 = Multi-Protocol</p></td></tr><tr><td>getVersion</td><td>Full version number of the <code class="expression">space.vars.X_Agent_Name_Single</code> in text format</td></tr></tbody></table>

### Command: serverStatusJson

The **serverStatusJson** command is the JSON-returning sibling of `serverStatus`. It emits a single object containing every field exposed by the `serverStatus` method table plus `type` (translated label) and `typeCode` (raw numeric value):

```
puts [serverStatusJson TestServer1]
```

Sample response (truncated):

```json
{"status":1,"running":false,"build":9000,"version":"11.0.0 B21140",
 "configuration":"","ruleset":"","host":"localhost","port":9932,
 "type":"Test","typeCode":1,"traceMode":false,"traceData":false, ...}
```

### Command: getServerType

The **getServerType** command returns the translated type label for a single agent. Useful for conditional logic in scripts that only need the type rather than the full status record:

```
puts [getServerType TestServer1]
```

Sample output:

```
Test
```

The return value is one of `Production`, `Test`, `Database`, `Template`, `Production with Forwarder`, or `Multi-Protocol` (translated to the session locale).

### Command: setCredentials <a href="#toc492984206" id="toc492984206"></a>

The setCredentials command is used to set the value of a given field in the credentials vault. The specific vault and field must exist already.

The following script snippet shows an example of how to use this command:

```
setCredentials KapowSMS UserID Fred
```

This command can only be executed with administrator or security authority.

### Command: getServerHome <a href="#toc492984206a" id="toc492984206a"></a>

The getServerHome command retrieves the home directory (data directory) for a specific server and optionally exports it to a designated output directory. The following script snippet shows an example of how to use this command:

```
set homeDir [getServerHome Qwerty ""]
puts "Server home directory = $homeDir<p>"
```

To export the server home to an output directory:

```
set result [getServerHome Qwerty "/tmp/export"]
puts "Export result = $result<p>"
```

### Command: startServer <a href="#toc492984207" id="toc492984207"></a>

The startServer command is used to start a nominated server.

The following script snippet shows an example of how to use this command:

```
startServer Qwerty
```

The command will wait for up to 30 seconds to ensure that the server is actually started. Provided the server starts, the command will return "1". If the server fails to start, then "0" will be returned.

### Command: stopServer <a href="#toc492984208" id="toc492984208"></a>

The stopServer command is used to stop a nominated server.

The following script snippet shows an example of how to use this command:

```
stopServer Qwerty
```

The command will wait for up to 30 seconds to ensure that the server is actually stopped. Provided the server stops, the command will return "1". If the server fails to stop then "0" will be returned.

### Command: startTrace

The **startTrace** command turns on trace mode on a running agent. It is equivalent to clicking the trace toggle in the Console UI - subsequent transactions handled by the agent are captured in its in-memory trace buffer until trace mode is turned off again.

```
puts [startTrace LocalProxy]
```

Returns `1` on success, `0` on failure. Trace mode affects only a running agent; the command throws an error if the agent is offline or if the caller lacks the required permission.

### Command: getTraceData

The **getTraceData** command retrieves the current contents of an agent's in-memory trace buffer as a newline-joined string, ready to `puts` or post-process. Each call drains whatever trace lines are currently held on the agent, making partial captures during a long-running workload viable:

```
set trace [getTraceData LocalProxy]
puts "captured [string length $trace] bytes of trace"
puts $trace
```

Sample output (one transaction):

```
**** BEGIN TRANSACTION ****
2026-04-30 09:59:52.352::REQUEST_TIMESTAMP = 1777532392350
2026-04-30 09:59:52.352::REQUEST_URL = http://localhost/something
2026-04-30 09:59:52.352::URI = /something
2026-04-30 09:59:52.352::Entering rule Display Text in test-non-proxy.xml
2026-04-30 09:59:52.366::Chaining to Continue
**** END TRANSACTION ****
```

Returns an empty string if the agent has no trace data. The command throws an error if the agent is offline or if the caller lacks the required permission.

### Command: userExists <a href="#toc492984209" id="toc492984209"></a>

The userExists command checks if a given user ID exists. The command returns "0" if the user ID is not found or "1" if the user ID is found. The following script snippet shows an example of how to use this command:

```
set checkUser admin
puts "User $checkUser exists [userExists $checkUser]"
```

This command can only be executed with administrator or security authority.

### Command: updateApplication <a href="#toc492984210" id="toc492984210"></a>

The updateApplication command updates a console application (such as Qwerty or the console itself. The following script snippet shows an example of how to use this command. In this case the console itself will be updated:

```
updateApplication console
```

This command can only be executed with administrator authority.

### Command: updateExtension <a href="#toc492984211" id="toc492984211"></a>

The updateExtension command updates/installs an extension from the update server (such as the Base Rules or the Http Rules). The following script snippet shows an example of how to use this command:

```
updateExtension "MaxMind Rules"
```

This command can only be executed with administrator authority.

### Command: updateRepository <a href="#toc492984212" id="toc492984212"></a>

The updateRepository command updates/installs a repository from the update server (such as the Product Trial repository). The following script snippet shows an example of how to use this command:

```
updateRepository "Product Trial"
```

This command can only be executed with administrator authority.

### Command: userList <a href="#toc492984213" id="toc492984213"></a>

The userList command obtains a list of all users in the console. The response is in the form of an array of user IDs. The following script snippet shows an example of how to use this command:

```
set usrList [userList]
puts "User count = [$usrList length]<p>"
for { set i 0 } { $i < [$usrList length] } { incr i } {
puts "[$usrList get $i]<p>"
}
```

A sample output from running the above script is as follows:

```
User count = 3
admin
security
super
```

This command can only be executed with administrator or security authority.

### Command: userListJson

The **userListJson** command is the JSON-returning sibling of `userList`. It emits an array of `{logon, name, type}` objects - richer than the `userList` name-only form since JSON has room for the extra fields clients typically want:

```
puts [userListJson]
```

Sample response:

```json
[{"logon":"admin","name":"Default Administration User","type":0},
 {"logon":"security","name":"Default Security User","type":3},
 {"logon":"super","name":"Default Super User","type":2}]
```

`type` is the numeric user type (0=Administrator, 1=Standard, 2=Super, 3=Security). This command can only be executed with administrator or security authority.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.tomorrowx.com/cap/guides/tcl-script-writer-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.