Caché Web Terminal is a Caché TERM replacement build for browsers. This page describes almost all the features that WebTerminal introduces.

Special Commands

WebTerminal introduces special commands, the ones that start with slash symbol, which allow you to perform different tasks like favoring commands, entering special modes, configuring WebTerminal and displaying help. The list of these features is listed on the right.

Mobile-Friendly Terminal

Is it Mobile-friendly? It is! As WebTerminal is a browser-based application, it is accessible from the mobile devices as well as from the desktop ones. Perform the tasks with Caché from your pocket!

Embedded SQL mode

You can enter an convenient SQL mode and execute any SQL query right from the terminal. The output would be formatted in HTML table. You can change number of rows displayed in this table by entering /config sqlMaxResults = 1000 command in WebTerminal.

Intelligent Autocomplete and Syntax Highlight

Intelligent autocomplete feature will help you to complete you input faster. It differs methods from properties, classes from keywords. It suggests variable names, as well as variable properties and methods, simple variables of data type from the variables holding an object reference.

In addition, you get the intelligent syntax highlighting, which differs variable names from simple keywords and highlights almost all Caché ObjectScript statements.


Tracing feature enables you to track for changes in globals and local files. The terminal will simply print these changes with some additional information.

Configuring Behavior

WebTerminal is customizable. As time goes by, the more and more customization options may appear. You can even request the ones you would like to see! Follow GitHub's issue tracker and leave your request there.

Check other cool features by downloading and installing Caché Web Terminal, it is free!

Documentation And Frequently Asked Questions

Table Of Contents

  1. Installation and configuration
    1. Installing Caché Web Terminal
      1. Importing Classes
      2. Resolving Import Errors
      3. Launching WebTerminal
      4. Installing Old WebTerminal Versions (1-2)
    2. Configuring WebTerminal Web Application
      1. Password Protection
      2. Setting Web Application Up
      3. Restricting Access To A Particular Users Group
  2. Usage Basics
    1. Using Autocomplete
    2. Using WebTerminal's Special Commands
      1. Getting Help
      2. Clearing All The History
      3. Configuring WebTerminal
      4. Remembering Particular Commands
      5. Showing Project Information
      6. Logging Out From WebTerminal
      7. Toggling SQL Mode
      8. Tracing Globals And Files
      9. Updating WebTerminal Manually
    3. Configuring WebTerminal
      1. Changing Default Namespace
      2. Hiding Initial Messages
      3. Changing The Language
      4. Increasing Stored History Size
      5. Changing The Rows Limit In SQL Mode
      6. Toggling Autocomplete
      7. Toggling Syntax Highlight
      8. Toggling Updates Check
      9. Changing The Server Name
    4. Interrupting Commands Execution
  3. Output Options
    1. Changing Output Color And Font
    2. Formatting Output
    3. Cursor Control
    4. Printing Hyperlinks (WebTerminal Only)
    5. Printing HTML (WebTerminal Only)
    6. Other Supported Output Options
  4. Embedding WebTerminal To Other Applications
    1. Embedding With IFrame
      1. IFrame Attributes
      2. URL Parameters
    2. JavaScript API
      1. Handling Terminal Initialization
      2. Executing Commands
      3. Handling User Input
      4. Printing
      5. Handling Output
      6. Removing Callbacks
  5. Contributing To WebTerminal Project
    1. Development Workflow
    2. Guidelines
    3. Entry Points
  6. Licensing (MIT)

Please note that this documentation is actual only for the latest WebTerminal version. All outdated WebTerminal versions should be updated to match this documentation.

1. Installation and Configuration

This section describes how to install WebTerminal to your Caché system and perform a basic (optional) configuration to make it ready for any use case.

1.1. Installing Caché Web Terminal

The latest WebTerminal versions are supported for any Caché (Ensemble, HealthShare, etc) platform version higher than 2014.1. The older versions of WebTerminal (versions 1-2) will work on 2013.1.

The installation begins from the simple import of classes to Caché. Before doing that, you need to download the latest available version on this website. To do this, go to the downloads page and select the most up-to-date (the most top one) version from the list.

The download will save the XML file to your computer, which you will need to import then. See the section below to import the classes to your Caché installation.

1.1.1. Importing Classes

Once you have the XML file of the latest WebTerminal version downloaded from the downloads page, you need to import it to your Caché system. To do this, you need to have system privileges. On a clean Caché installation the user _SYSTEM can perform this operation. The default password of this user is SYS. Once you notice the window prompting you to enter a username and a password, try the default ones (_SYSTEM / SYS).

There are three common ways of how to install WebTerminal:

  1. Import using Caché Studio (Windows OS only)

    If you have access to Caché Studio, then this is the simplest method. Open up the Studio window, choose the namespace you want to import WebTerminal to (for example, select USER namespace), and just drag & drop the XML file onto the Studio window. Caché Studio will prompt you to compile the classes, check "yes" and then press OK.

    At the bottom of the studio (by default) you will see the message saying that compilation is successful. However, there may appear some errors. Check the Resolving Import Errors (1.1.2) section for more information on this.

  2. Import Using Management Portal (any OS)

    If you have access to the Management Portal, then you can go to "System Explorer" -> "Classes" page and click on the "Import" button there. Select the "File" option in the dialog, and then choose the full path to the XML file you want to import (WebTerminal-?.?.?.xml). Check "Compile imported items" checkbox and then press OK. Check the output of the compilation process and refer to Resolving Import Errors (1.1.2) section for more information on errors if there are any.

  3. Import Using Terminal (any OS)

    If you have access to Caché Terminal, you can import WebTerminal by using this command:

    do $system.OBJ.Load("/path/to/xml/file/WebTerminal-?.?.?.xml","ck")

    Replace the /path/to/xml/file/WebTerminal-?.?.?.xml to the path to WebTerminal's XML file in your filesystem. Then, check the output of the compilation process and refer to Resolving Import Errors (1.1.2) section for more information on errors if there are any.

1.1.2. Resolving Import Errors

During the installation, there may happen some errors. You will receive the alert message with the error description, as well as the Studio (terminal) output describing the error. There are the most common errors and their descriptions listed:

  • <PROTECT> error.

    If you have this error, double check if the user within you are currently logged in has sufficient privileges to access the %SYS namespace. During the installation, WebTerminal tries to change the namespace to %SYS and then tries to set up the /terminal web application.

  • ERROR #921: Operation requires %Admin_Secure:USE privilege

    This means that the current user (the one you are trying to import WebTerminal under) is missing %Admin_Secure resource access. The access to this resource is provided with the %All (superuser) by default, so make sure you are logged in as a superuser (_SYSTEM user by default).

1.1.3. Launching WebTerminal

WebTerminal is a web application. To open WebTerminal, use the next URL address: http://[host]:[port]/terminal/

There are a few things you need to take into account:

  1. The slash symbol (/) at the end of the URL is required.
  2. [host] and [port] URL parts must be replaced with the hostname and port number of the server you installed WebTerminal to. You can easily check this data by opening the Management Portal — the URL beginning will be the same for WebTerminal as well as for Management Portal. Here is the default URL of Caché WebTerminal installed on the clean system: http://localhost:57772/terminal/
  3. If the web application still showing "404 not found" error, double check if the installation process resulted with no errors.

1.1.4. Installing Old WebTerminal Versions (1-2)

It is always recommended to install the newest versions. However, if you exited so much about WebTerminal project and want to try it, for example, on Caché 2013.1, the only option you have is to install version 2. Do this by performing the following steps:

  1. Go to WebTerminal Downloads and download the version 2.0.0-beta.8, which is the XML file. This page also has some additional instructions.
  2. Using Studio or whatever you like (see above), import this XML file into the %SYS namespace and compile all imported classes and CSP pages. If you have the "access error" while importing classes, then you need to temporarily enable write access to CACHELIB database, see here how.
  3. Open {host}:{port}/csp/sys/webterminal/index.CSP page in the browser.

Note that the newer versions have several fixes and enhancements introduced, so please do not submit any issues affecting versions 1-2. These versions are not supported "officially".

1.2. Configuring WebTerminal Web Application

Once you install WebTerminal, there are two Caché web applications appear. The first one, /terminal, is a user interface of the terminal application. The second one, /terminalsocket, is the "empty" web application for incoming WebSocket connections. The /terminalsocket web application has to be opened to any user and the password protection must be disabled on it, as Caché CSP gateway will block any WebSocket connections. The token accepted by opened WebSocket connection is generated by the /terminal application, and this is exactly the web application you need to apply restrictions to.

1.2.1. Password Protection

Password protection is enabled by default for the /terminal web application. This means that any Caché user would be able to log in with their username and a password to WebTerminal, if they have the access to the database WebTerminal were installed to.

1.2.2. Setting Web Application Up

The /terminal web application is set up automatically the first time you install WebTerminal. You can find it by going to the Management Portal -> System Administration -> Security -> Applications -> Web Applications and then selecting /terminal web application from the list.

You should not change the name of this application, as this will prevent WebTerminal from updating normally. Also, do not change the dispatch class this application refers to.

However, the things you can change are listed on the web application definition edit page: description, namespace, security and session settings and roles added to the web application user. You can find more information about setting up web applications in the InterSystems documentation.

1.2.3. Restricting Access To A Particular Users Group

You may want to restrict the access to WebTerminal web application only to specific users. To do this, open up the WebTerminal web application configuration by going to the Management Portal -> System Administration -> Security -> Applications -> Web Applications page and then selecting /terminal web application from the list. Now, select the %WebTerminal as a required resource (Resource Required drop-down menu in Security Settings). If you don't have this resource in the list, check if you have the latest WebTerminal version installed. Or, alternatively, you can create your own resource and role to access this resource, and then assign created resource to the web application (see the documentation).

Once you choose %WebTerminal resource, click Save on the top of the page. Then go to the System Administration -> Security -> Users page and select the user you need to allow the access to WebTerminal. Then, go to the Roles tab and assign the WebTerminal role by selecting the role from the left list, pressing the right arrow button and then pressing Assign button.

Note that superuser (_SYSTEM by default) does not require WebTerminal role to be assigned, as superuser has %All role, which grants the full access to all resources in the system.

2. Usage Basics

This section describes the basic usage of WebTerminal and all of its features.

2.1. Using Autocomplete

When you type commands you may notice the autocompletion variants appearing. To complete the input with proposed suggestion, use TAB key.

If there is a list of autocomplete variants available, use left and right CTRL key to switch to the next or the previous variant in the list respectively.

2.2. Using WebTerminal's Special Commands

All special commands in WebTerminal start from / symbol. Enter this symbol to get the list of available commands as a suggestion.

2.2.1. Getting Help

To get the help information printed, enter /help special command. This command, as well as any other special command can be entered in both default and SQL terminal modes.

2.2.2. Clearing All The History

WebTerminal does not have the history limit like standard terminal. This is useful to see all the output and search through it, but sometimes, when you execute a lot of commands in one session terminal may slow down because of this. In this case, you can trigger /clear special command to clear all the history.

2.2.3. Configuring WebTerminal

To customize the WebTerminal's behavior, use /config command. Refer to 2.3 section to find out more about local and global configuration.

2.2.4. Remembering Particular Commands

If you execute some command frequently, you can define a shortcut for it. To do this, enter

/favorite {name} write "I am always right!"

where {name} can be any symbolic name of the command you want to save. Then you can restore this command by entering

/favorite {name}

To delete previously saved commands, use

/favorite delete {name}

To delete all saved commands, use

/favorite delete

2.2.5. Showing Project Information

To display information about the project, use /info command.

2.2.6. Logging Out From WebTerminal

WebTerminal, as any other web application remembers the username and password you enter. You will still be logged in after the page refresh or even browser restart. To log out from the current user use /logout command.

2.2.7. Toggling SQL Mode

WebTerminal features the convenient SQL mode build in. To enter the SQL mode, use /sql command. To exit this mode, enter /sql command again.

In SQL mode you can execute any SQL queries and get the syntax highlight and suggestions for SQL. Also, when getting SQL results you will see simple SQL table, which is easy to read comparing to the simple terminal output.

2.2.8. Tracing Globals And Files

You can start tracking changes in globals or files. For globals, tracking is available only for multi-dimensional ones. WebTerminal will notify you about the changes in global dimension. To start tracking, use the following commands:

/trace /path/to/file (to track files)
/trace ^globalName (to track globals)

You will start receiving notifications as a printed output to the current session. Use

/trace stop

To stop tracking all files and globals.

2.2.9. Updating WebTerminal Manually

When you disable the auto-update, or if the initial output is omitted, you can still check for the updates manually by entering /update command.

2.3. Configuring WebTerminal

WebTerminal configuration is divided into to client and server configuration. The client configuration persists in the browser's local storage (so it resets when browser changes), and the server configuration is global for the whole Caché instance. All the settings can be changed with /config special command.

2.3.1. Changing Default Namespace

Affects client only. To change the default namespace use the next command:

/config defaultNamespace = "USER"

The user logged will enter this namespace at start if they have access to it.

2.3.2. Hiding Initial Messages

Affects client only. If you want to stop showing the initial messages upon the start, enter

/config initMessage = false


2.3.3. Changing The Language

Affects client only. The closest interface language you need is detected automatically during the WebTerminal start. But you can change it by entering

/config language = ru

Affects client only. You can try entering any language and WebTerminal will show the list of available languages if the one you entered cannot be set up.

2.3.4. Increasing Stored History Size

Affects client only. WebTerminal stores 200 last commands in history. To change this limit, enter

/config maxHistorySize = 777

2.3.5. Changing The Rows Limit In SQL Mode

Affects client only. If you need to change the maximum number of rows displayed in SQL mode, enter

/config sqlMaxResults = 999

2.3.6. Toggling Autocomplete

Affects client only. If for some reason you don't want autocomplete to help you, turn it off by using

/config suggestions = false

2.3.7. Toggling Syntax Highlight

Affects client only. If for some reason you don't want the input to be highlighted, turn it off by using

/config syntaxHighlight = false

2.3.8. Toggling Updates Check

Affects client only. There may be some cases when you won't need to notify client about available WebTerminal updates. The most common case is embedding WebTerminal to other applications for non-privileged users. If you are using clean URL parameter, than you don't need to turn this option off. In case of you don't want to update terminal regularly, it's sad, but you can turn the updates off by using

/config updateCheck = false

2.3.9. Changing The Server Name

Affects server. Changes the name of the server displayed in initial message and in the browser's tab. This becomes extremely useful if you have WebTerminal installed on multiple servers and you open many browser tabs at once. Use this to change the server name:

/config serverName = "Pentagon"

2.4. Interrupting Commands Execution

Sometimes the line of code you execute in WebTerminal may freeze for a while or even never get completed. In this case you may want to interrupt the command execution. To do this, press Ctrl + C keys combination. If no text were selected, the interrupt signal will be sent to the server and you will get <EXTERNAL INTERRUPT> error.

3. Output Options

WebTerminal supports VT100 escape sequences and some others to format and control the output. This section describes the supported escape sequences and their usage.

The <ESC> designation in this section stands for the non-printable character with ASCII code 27 (equivalent of COS $Char(27) result), which is commonly used escape character. This character begins the control sequence, and it is usually followed by other characters which apply the different conditions and control the terminal output.

For example, <ESC>[31m stands for printing these characters using the next COS code: write $Char(27), "[31m".

3.1. Changing Output Color And Font

There is an option to change the output font weight and color. The table below demonstrates the basic escape sequences that can be used in output.

Sequence Description
<ESC>[0m Reset all output options mentioned in 3.1 to default
<ESC>[1m Switch font to bold
<ESC>[2m Make font dim
<ESC>[3m Make font italic
<ESC>[4m Underline the text
<ESC>[5m Print blinking text
<ESC>[7m Print Invert the printed text colors
<ESC>[8m Print invisible text (but still selectable)

For example, to print "Impossible is nothing!" on the screen, you can type the following write statement in terminal (Caché ObjectScript):

write "Impossible is ", $Char(27), "[4mnothing", $Char(27), "[0m!"

Alternatively, if you are using JavaScript API, then the next will do the same:

term.print("Impossible is \x1b[4mnothing\x1b[0m!");

As well as font, the color of the text and its background can be changed by using these sequences:

Sequence Description
<ESC>[3Xm Changes the font color. The X here is a number which can be one of the following: 0 for Black, 1 for Red, 2 for Green, 3 for Yellow, 4 for Blue, 5 for Magenta, 6 for Cyan and 7 for White.
<ESC>[4Xm Changes the background color. The same digits described for <ESC>[3Xm sequence can be used here instead of X.
<ESC>[38;5;Ym Changes the font color according to 8-bit color table. The Y here can take integers from 0 to 255, which corresponds to pre-defined 8-bit color table.

3.2. Formatting Output

To format output and set up tab stops the next escape sequences are used:

Sequence Description
<ESC>[XG Moves cursor to column X. In Caché ObjectScript you can just use a "?" symbol to shorten this escape sequence, for example: w ?25, "duck"
<ESC>H Set the tab stop at the current position. By default tab stops are set at each 8th column.
<ESC>[g Clears the tab stop at the current position if present.
<ESC>[3g Clears all tab stops.

3.3. Cursor control

The next escape sequences are used to control the cursor:

Sequence Description
<ESC>[Y;XH Moves cursor to (X, Y) position (the upper left corner is (1, 1)). Both X and Y can be omitted, e.g. <ESC>[H will set the cursor to position (1, 1).
<ESC>[XA Moves the cursor up by X rows; the default count is 1.
<ESC>[XB Moves the cursor down by X rows; the default count is 1.
<ESC>[XC Moves the cursor forward by X rows; the default count is 1.
<ESC>[XD Moves the cursor backward by X rows; the default count is 1.
<ESC>[s Saves the current cursor position.
<ESC>[u Loads the last saved cursor position.
<ESC>7 Save the current cursor positions and its attributes (font and color).
<ESC>8 Restore the last saved cursor positions and its attributes (font and color).

3.4. Printing Hyperlinks (WebTerminal Only)

WebTerminal provides a special escape sequence to print hyperlinks. Note that this will work only for WebTerminal.

Sequence Description
<ESC>!URL=<link> (<text>) Prints the <text> highlighted as a link. Pressing on the printed <text> will open a new tab with the URL address <link>. Make sure that the <link> does not contain spaces (they must be encoded with %20 character combination) and other non-URL symbols. Note that there is a space between <link> and ( symbol.


USER > write "Visit ", $Char(27), "!URL= (GitHub)!" Visit GitHub!

3.5. Printing HTML (WebTerminal Only)

WebTerminal can print HTML! This opens almost infinite possibilities of extending WebTerminal applications with modern web technologies. See the table below for the HTML printing options.

Sequence Description
<ESC>(<classname>)m Prints the text wrapped into HTML <span class="<classname>"> element. To clear the assigned class use <ESC>[0m escape sequence as well. Check the available WebTerminal classes here.
<ESC>!<HTML>{html}</HTML> Converts the current line in output to the HTML line. This line will include any {html} given to the sequence. Once the given {html} will be rendered on the screen, the height of the rendered part will be calculated instantly and assigned to the containing line (the height of the line may be slightly higher than the content height). This height will not be changed when content height changes.
NOTE that this sequence will block output until the closing </HTML> comes.


USER > write $Char(27), "!<HTML><h1>I am a very big title!</h1></HTML>end."

I am a very big title!


3.6. Other Supported Output Options

There are more escape sequences not mentioned above but is supported by VT100 terminal standard. You can check the other escape sequences here. If you find the escape sequence missing in WebTerminal, you can request for this sequence to be impemented. Go to describe an issue, or, you can even implement it by yourself starting from this file.

4. Embedding WebTerminal To Other Applications

WebTerminal can be easily used inside any other web application. See the description below to find out more about embedding.

4.1. Embedding With IFrame

To embed WebTerminal to any other web application, you can use <iframe> HTML tag. Example:

<iframe id="terminal" src=""></iframe>

The id="terminal" attribute will be used in examples below to refer the iFrame element on the page. You are free to use any other JavaScript references in your application.

4.1.1. IFrame Attributes

  • The src attribute specifies the URL of the WebTerminal web application.
  • Any styles can be applied to iFrame element with HTML style or class attributes.

4.1.2. URL Parameters

URL parameters are specified after the ? symbol in the URL. They are used to configure WebTerminal behavior when embedding. WebTerminal supports the following URL parameters:

  • Parameter ns allows to specify the namespace to start from. If the user logged is not allowed to access this namespace, the error message will appear and user will start from their startup namespace. Example:
  • Parameter clean makes terminal start without printing any broadcast messages or update notifications. Example:

4.2. JavaScript API

WebTerminal has its own JavaScript API. Please refer to the section below.

4.2.1. Handling Terminal Initialization

To use WebTerminal's API, you need to get WebTerminal instance first. Use iFrame's onTerminalInit function for this:

document.querySelector("#terminal").contentWindow.onTerminalInit(function (term) { // now you can access the term object here });

The callback is triggered only after WebTerminal establish an authorized connection. But we need to handle the iFrame load event before you can start using the onTerminalInit function. To do this, add the load listener to iFrame element:

var iFrame = document.querySelector("#terminal"); // This function will be shown in the examples below without iFrame binding code. function myInitHandler (term) { // now you can access the term object here } // At first, handle iFrame load event. Note that the load handler won't work // if this code is executed at the moment when iFrame is already initialized. iFrame.addEventListener("load", function () { iFrame.contentWindow.onTerminalInit(myInitHandler); });

4.2.2. Executing Commands

To execute a line of Caché ObjectScript code in runtime, use term.execute(command, [options], [callback]) function. It accepts three arguments:

  • String command, specifying the command to be executed.
  • Optional object options, which may have two boolean properties echo (default is false) and prompt (default is false). When echo is true, the command being executed will be output to the screen like it was entered by user. When prompt is true, the user will be prompted to enter a command after execution (NAMESPACE > will be printed as well).
  • If callback is passed, the output buffer will come as a first argument of the callback function in a form of an array of strings.

Example of executing the line of COS code at the startup:

function myInitHandler (term) { term.execute("set hiddenVariable = 7", { echo: true, prompt: false // the default is false, this is shown just for the demo }); }

4.2.3. Handling User Input

To handle the commands user enters, use the term.onUserInput(cb) function. callback(text, mode) is fired right after user presses enter. Argument text is a String of user input, and mode is a Number, which can be compared with one of the terminal mode constants, such as MODE_PROMPT. The list of these constants is shown below:

  • term.MODE_PROMPT handles regular input (COS command).
  • term.MODE_SQL handles input in SQL mode (SQL command)
  • term.MODE_READ handles prompt issued by COS read x command
  • term.MODE_READ_CHAR handles prompt issued by COS read *x command
  • term.MODE_SPECIAL handles special WebTerminal's commands like /help, /config etc.

Here is example of user input handling:

function myInitHandler (term) { term.onUserInput(function (text, mode) { if (mode !== term.MODE_PROMPT) return; // expect only the COS input if (text.indexOf("set secret = ") === 0) alert("Do not set secret variables!!!"); }); }

4.2.4. Printing

To print something to terminal output, use term.print(text) function, where text is a simple string. This string can include any special characters and escape sequences. This function is input-safe, which means that you can print event when terminal is waiting for user input. In this case the input will reappear right after the printed text.


function myInitHandler (term) { term.print("\r\nWe're ready!\r\n\n"); }

4.2.5. Handling Output

You can handle terminal output by using term.onOutput([ options ], callback). By default, callback(strings) will be called before the user is prompted for input, and strings array will always contain an array of chunks of all the text printed between the prompts. For example, if user writes write 123 and presses "Enter", the strings will contain this array: ["\r\n", "123", "\r\n"]. However, when user enters write 1, 2, 3, strings will result with ["\r\n", "1", "2", "3", "\r\n"]. You can join this array with join("") array method to get the full output.
Optional options object may include stream property, which is false by default. When set to true, callback will be fired every time something is printed to the terminal simultaneously.


function myInitHandler (term) { term.onOutput((chunks) => { // If you "write 12", chunks are ["\r\n", "12", "\r\n"]. // If you "write 1, 2", chunks are ["\r\n", "1", "2", "\r\n"]. if (chunks.slice(1, -1).join("") === "duck") { // if the user enters: write "duck" alert(`You've found a secret phrase!`); } }); }

4.2.6. Removing Callbacks

Every function that accepts callback also returns the same callback, which can be passed to term.removeCallback(callback). After callback is passed to this function, it will not longer execute.

5. Contributing To WebTerminal Project

The Caché WebTerminal is an open-source project anyone can contribute to. Anyone are welcome to join and contribute to this project on InterSystems official GitHub. This section describes the basic guidelines and principles of contributing.

5.1. Development Workflow

The development workflow of Caché WebTerminal lies completely outside Caché (without using Caché Studio / Atelier) and is possible for any platform. It uses a Gulp building tool to gather and build the Caché-ready project from bare sources, JavaScript ECMAScript 6 standard and SCSS (SASS) for styling.

To set up the project, you have to have latest Git and NodeJS installed (tested on NodeJS v4-6). Then, use command line to download and setup the project:

git clone cd webterminal # enter repository directory npm install # install all project's dependencies npm run build # build the project

After this, you will get the build directory containing Caché classes in UDL format. To import these classes to Caché, and to perform the build with one single command, go to edit the import.cmd or file (depending on your OS). There you need to change only constants like CACHE_DIR, which may be different for your system. Just do not commit this file after changing, and use the next command


to build and import new classes to Caché. Once you have imported classes, you should receive IMPORT STATUS: OK and EXPORT STATUS: OK messages.

The workflow to release a new version of WebTerminal is presented below. Please, be very careful when releasing new versions, as all the WebTerminal users will start receiving updates. To release a new WebTerminal version, do the following:

  1. Build and carefully test the project as described above.
  2. Copy build/WebTerminal-vX.Y.Z.xml file to the docs/files directory.
  3. Append a record describing changes to docs/terminal.json file. You can accurately copy-paste-edit record from the previous records. Make sure you changed the /versions/X/v and /versions/X/url properties to the latest version and the location of the file respectively. Note that the latest version bust be greater than the previous version. Make sure that the JSON structure is still valid.
  4. If the change is pretty important, add it to visible releases (this website) by editing docs/index.html file.
  5. After you push these changes to repository, test whether terminal receives the new version and properly updates.

A special care must be taken while altering WebTerminal updating mechanism (WebTerminal.Updater class). If you push a broken change, WebTerminal will update itself normally for the first time. During the next updates WebTerminal will use the new update code which can possibly make it never update again, and user will need to reinstall WebTerminal manually).

You can put the /motd (message of the day) message to docs/terminal.json: all WebTerminal users will start to see this message in console. Do it only when absolute necessary: do not distract users. This functionality is kept for the critical WebTerminal faults, when users will need to reinstall WebTerminal manually (hopefully never).

One more thing for repository maintainers: **never** rename the repository or move the docs (website) to the custom domain until you will be completely sure that this won't break the WebTerminal auto-updating mechanism (update URLs).

5.2. Guidelines

There are several guidelines you should consider if you want to contribute to WebTerminal project by yourself:

  1. Create a new issue or open a pull request for every new contribution.
  2. Use spaces instead of tabs (4 spaces), comment and format well any contribution if needed.
  3. When introducing new features or extending WebTerminal API, open a new issue to discuss the way how to implement it as best as possible.

5.3. Entry Points

This section describes the main files of the project.

File name / Directory Description
/import.* Script used to build and import the project to local Caché with one command. This script assumes editing before usage (changing constants).
/src/client/ Directory containing the client files (HTML, SCSS, JavaScript).
/src/cls/ Directory containing the server files (HTML, SCSS, JavaScript). Both client and server files are pre-processed. For example, you may notice that server files include comments with special syntax (f.e. <!-- @echo package.title -->). These lines are pre-processed during the build and are replaced with corresponding values.
/src/client/js/ output/esc.js File that describes all supported escape sequences. The exported object's keys contain the character pattern of escape sequence, and the regular expression patterns enclosed by {} characters. The function as a key is triggered once the sequence is printed. However, no characters will appear in the output if the sequence is recognized.
/src/client/js/ parser/grammar.js You can easily make pull requests on this file if you need to enhance Caché ObjectScript grammar recognition.
This file describes the grammar for Caché ObjectScript and SQL languages. See the comments in this file to understand its structure and feel free to enhance the grammar file to improve highlighting and autocomplete.
/src/client/js/ localization/dictionary.js You can easily make pull requests on this file if you need to support any UI language for WebTerminal.
This file includes all available translations for WebTerminal user interface. Using the same file structure, new languages can be easily introduced just by adding text only to this file.
others There are many other project files, please consider exploring their comments if you need more information.

6. Licensing (MIT)

The Caché WebTerminal is an open-source project developed and supported primarily by Nikita Savchenko for the InterSystems community. Anyone are welcome to join and contribute to this project on InterSystems official GitHub.

The project is distributed under the MIT license, which provides absolutely free non-commercial and commercial use of the software. The license text is shown below.

The MIT License (MIT)

Copyright (c) 2013-2017 Nikita Savchenko

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.



How to Install WebTerminal

  1. Download and import latest XML file (see below) into any namespace (preferably USER), compiling all the classes. Make sure you have system privileges to do it.
  2. Open http://[host]:[port]/terminal/ (slash at the end is required) web page. (By default the URL is http://localhost:57772/terminal/)
  3. Enter user credentials (by default it's _SYSTEM / SYS).
  4. That's all!

Refer to the installation section of documentation page to find out more. The guide above works for Caché WebTerminal version 3+. For versions 1-2 use this guide.

The Latest Versions:

Old Beta Versions:

Older Versions:

Versions 1-2.* to 3.* Migration Note

After version 3.* successful (perform manual WebTerminal package compilation) install, please, remove /csp/sys/webterminal directory and %WebTerminal class manually - these files won't work anymore. Now use http://[host]:[port]/terminal/ to access terminal WEB application (slash at the end of the URL is required).

The Oldest Versions:

Ancient Versions:


Importing WebTerminal.Installer class will also create /terminal WEB-application. The WEB-application will be protected with a password authorization by default.

Use /update terminal command (from CWT v2.0 only) to automatically update terminal application to the newest version.

Please, take a note that starting from v4.0.0-alpha.53, Caché WebTerminal collects anonymous statistics (via Google Analytics) during the installation and usage process. The information WebTerminal collects includes:

The only goal of statistics collection is to have analytics over WebTerminal usage by users for delivering a better product. Any error reports collected in this way will help me, the developer of WebTerminal to improve the application. This data is completely anonymous and will never include any licensing or Caché usage information, so feel free to use WebTerminal anytime, anywhere, for your needs. If you still don't want to use WebTerminal because of analytics collection - check WebTerminal's related source code (server, client) by yourself. The project is completely safe to use and trusted by hundreds of users worldwide.

Feedback / Contact Me

Follow the project on GitHub.

We will be glad to hear any wishes, requests, and comments. Leave any issues and report bugs at GitHub's issue tracker. If you have some extra information or questions - please feel free to contact me, the developer of this application, Nikita.

Welcome to Caché Web Terminal Homepage!

Caché Web Terminal is the first and the most powerful web-based terminal for InterSystems Caché®, Ensemble®, HealthShare®, TrakCare® and other products built on top of InterSystems Caché. It is a complete terminal utility packed with a lot of useful features in your favorite browser.

WebTerminal can replace the standard Caché terminal for you at all. The goal of this project is to develop more than just a terminal, but the universal utility to ease developers workflow and save their time. It features a lot of useful things like syntax highlighting, autocomplete, embedded SQL mode and tracing, which are not included in the standard Caché TERM.

To see the complete list of features in WebTerminal, please navigate to the showcase tab. To see the documentation, go to documentation tab.

Good News


Caché WebTerminal v4 Released!

Today the Caché WEB Terminal v4 gets released! Comparing to the previous WebTerminal versions, this release includes major stability and security improvements, intelligent syntax highlight and autocomplete features and a lot of small, but useful things!
Go to downloads page to get the latest version of WebTerminal, or, if you had any v4 betas installed just update them to the latest version. Check the documentation to find out answers to any related questions.

Caché WebTerminal v4 Alpha Release

A first early alpha version of Caché WEB Terminal v4 is released. This release will introduce auto-updates to the newest versions, so you won't need to check the updates by surfing the net. New version notifications will be displayed during the WebTerminal's startup as soon as new updates arrive.

Caché WEB Terminal v4 Is Under Development

This new version will become more stable and will perform better as well as other great features like intelligent autocomplete will be introduced. Follow the progress here.

Caché WEB Terminal v3.1.4 Major Fixes

The new version comes with major changes: first, WebTerminal can now be installed to any namespace, not only to the %SYS. Secondly, some issues with /update command were fixed as well as other minor bugs.

Caché WEB Terminal v2 Beta Release

Caché WEB Terminal v2 is available now. The new version brings VT100 and Caché TERM escape sequences support, some new features like self-updating, lots of performance and security improvements and more stable work. Check it out in downloads!