Command Line Interface (CLI)

Introduction

Introduced with ChartIQ v9.6.0, the CLI plugin is an experimental feature that functions primarily as a command palette. This command palette provides users with streamlined access to various chart functions and enhances our accessibility initiatives by offering efficient ways to interact with the chart.

With the CLI plugin, you can:

Change the chart type
Adjust the periodicity or range
Add a study
Add a series

Additionally, this plugin offers an experimental command line interface that enables further manipulation of the chart by allowing the user to run pre-defined commands.
This interface allows you to quickly check the version of the ChartIQ Library in use, reset the chart layout, export the current chart settings, and more. For further details, see the Command Line Interface section of this tutorial.

Activating

The CLI plugin is currently compatible only with our sample-template-advanced.html template and is included as a commented-out plugin alongside the other included plugins.

To enable the CLI plugin, simply uncomment the following line:

import "./plugins/cli/cli.js";

Locating

Once the plugin is activated, you will find it in the footer of the chart, next to the Share and Shortcuts buttons.

Figure. Location of the CLI toggle.

Command Palette

When you open the CLI Plugin in your chart, you'll find a list of commands that you can click or activate using your keyboard to change the Display Type, Periodicity, Range, or add a Study. The list is generated by scraping the available commands from the ChartIQ UI, which means that custom UI commands are not included by default. Only the commands relevant to your chart preferences will be displayed in the command palette, along with any commands you have recently used. When you start typing in the CLI input, the plugin will dynamically filter the commands in the command palette based on your input.

Configuration

The CLI plugin is included in defaultConfiguration.js and allows for some minor customization of the plugin.

arrow_nav: Set to "palette" to enable arrow navigation within the command palette. If set to "history", it allows cycling through recently used commands.
container: Defines the location of the CLI plugin within the UI.
- Note: Additional CSS styling is necessary if the CLI plugin is moved out of the footer.
customSelectors: Enables the specification of a custom selector for UI elements that you want to include in the Command Palette. (Commented out by default)
customTransform: A custom function that transforms your UI elements into a format compatible with the plugin. (Commented out by default)
max_history: Specifies the maximum number of commands that can be stored in the plugin's history.
moduleName: The designated name of the module.
- Important: This name should not be altered.
show_recent: Determines the number of recently used commands displayed in the Command Palette.
toggleMarkup: The markup for the button that identifies the CLI plugin.

cli: {
  arrow_nav: "pallet", // set to "history" to navigate command history with arrow keys
  container: ".ciq-footer",
  // customSelectors: "", 
  // customTransform: (acc, cur) => {
  // 	const label = cur.innerText.trim();
  // 	const id = `Custom ${label}`;
  // 	acc[id] = { type: "Custom", label, cur };
  // },
  max_history: 100,
  moduleName: "CLI",
  show_recent: 5,
  toggleMarkup: `
<cq-cli></cq-cli>
<cq-toggle feature="cli" class="ciq-cli-button bottom" stxtap="Layout.toggleCLI()" reader="Toggle Command-line Interface" icon="cli" tooltip="Command Line"></cq-toggle>
  `
},

Command Palette in Action
Figure. Interacting with the chart through the command palette.

Command Line Interface

As mentioned earlier in this tutorial, the CLI plugin functions as a command palette with experimental command line interface capabilities. The command line interface is actively being developed and refined.

The commands listed below are accessible through this interface but may change, be modified, or removed in future updates.

Important: The command line interface is an advanced feature. If you have experience with command line tools, you will likely find this feature familiar.

To display all available commands, type cmdlist into the CLI text input.

Command Palette displaying available commands
Figure. Command Palette interface illustrating the list of available commands for user navigation.

To get help for a specific command, you can type help <cmd>.

For example: help series will display:
"Add or remove a series; use the -c option to add as a comparison series, and the -r option to remove (or -x to remove all)"

To show the usage string for a given command, you can type <cmd> -h.

For example: series -h will display:
"series [-c] [-rx] <symbol> [color]"

Important Considerations:

In line with common command line interface syntax, optional arguments are indicated in brackets [ ], while required arguments are enclosed in angle brackets < >, as shown in the example above.
Commands that accept a two-word argument should be enclosed in quotes. For example: type "Hollow Candle" or study "Bollinger Bands".

Commands

chart2music

Enables Chart2Music.

cmdlist

Lists the available commands in the CLI plugin.

customer

Displays the customer information as reflected in the key.js file.

export

Logs the drawings, layouts, and preferences to the console in the form of a JSON object.

help

Get help with using the help command. Alternatively, pass another command as an argument immediately after help to receive help for that command's usage and details.

Usage String: help [-l] [command]

help Displays a message on how to use the help command.
help -l Lists all available commands
(returns the same output as cmdlist)
help [command] Displays the description and usage information for the specified command.

home

Returns the chart to the home position, placing the most recent tick on the right side of the screen.

info

Returns the customer's package info as reflected in the key.js file.

Usage String: info [field]

info Displays all of the customer's package information.
info expirationDate displays the specified info field.

layout

Retrieves the current layout settings of the chart.

Usage String: layout [field]

layout logs the entire layout object to the console.
layout studies displays the specified layout field within the CLI plugin.

Figure. List of active studies generated by the command layout studies.

periodicity

Usage String: periodicity <periodicity>

periodicity "1 D" change periodicity to 1 Day
periodicity "1 Hour" change periodicity to 1 hour
periodicity "15 Min" change periodicity to 15 minutes
- (Note: Ensure that the periodicity passed is in quotes and is case sensitive. There should also be a space between the number and the time unit for the CLI plugin to recognize your input as a periodicity command.)

polling

Pauses or resumes the quote feed. If no argument is passed, the current polling interval of the chart is displayed.

Usage String: polling [start|stop]

polling Displays the current polling interval.
polling stop Pauses the polling.
polling start Resumes the polling.

range

Usage String: range <range> | <start date> <end date>

Set the chart's range to 6M
- range 6M
Set the chart's range to a custom span
- To set a custom range, include a start date and an end date for your desired range after the command range.
- The range command accepts various date formats.
  - Acceptable formats include, but are not limited to: 'YYYY-MM-DD', 'MM-DD-YY', and 'MM/DD/YYYY'.
- To set a custom start range that spans to the current or nearest market date/time, include an empty string as a replacement for the end date.
  - range 2025-01-15 2025-01-30 Custom start and end date range in YYYY-MM-DD format
  - range 1/15/2025 1/30/2025 Custom start and end date range in the MM/DD/YYYY format
  - range 2025-01-15 "" Custom start date to current or closest market date/time

reset

Reset the chart to default settings

reset -f This will clear the local storage and reload the page.

series

Usage String: series [-c] [-rx] <symbol> [color]

Show active series:
- series
Add a series:
Use the following command to add a series:
- series GOOG #008000
  (Note: The color parameter can be a named color or a hex color.)
Add a series as a comparison:
To include a series as a comparison, add -c after the word series and before the symbol name:
- series -c GOOG Green
Remove a series:
To remove a specific series, add -r after the word series and before the symbol name:
- series -r GOOG
  (Note: -r removes the named series.)
Remove all series:
To remove all series from the chart, simply include -x after the word series:
- series -x

study

Usage string: study [-l] [-rx] <study name> [param1=value1 param2=value2 ...]

Show active studies:
- study
Show all available studies:
- study -l
Add a study:
- study Aroon
- study Moving Average
Remove a study:
To remove a specific study, add -r after the word study and before the study name:
- study -r "Aroon (14)"
  (Use the study name from the chart's layout object, e.g., "Aroon (14)" for Aroon.)
Remove all studies:
To remove all studies from the chart, simply include -x after the word study:
- study -x

symbol

Change the chart's main symbol.

Usage string: symbol <symbol>

symbol Display the current symbol.
symbol IBM Change the symbol to IBM.

type

Set the main symbol's display type.
- type Mountain

version

Returns the current ChartIQ library version being used.

version

Custom Commands

To add a custom command to the command line interface or modify the name of an existing command, update the registry.js file.

For example, you can rename the reset command to restore by changing the name of the reset object in registry.js.

restore: {
  func: function reset() {
    if (reset.opts.f) {
      localStorage.clear();
      location.reload();
    } else {
      this.echo(
        "To reset the chart to defaults, use the -f option to clear local storage and reload the page."
      );
    }
  },
  man: "Reset the chart to defaults when including the -f option. \n\nThis will clear local storage and reload the page. \n\nUsage:\nrestore [-f]",
  opts: "f",
  usage: "restore [-f]"
},

To add a custom command, include it as a property within the registry object. Each property should be an object that defines the func, man, opts, and usage properties to properly configure your new command.

Note: If a particular option requires an argument (i.e. -o arg) then that option's character in the opts string must be followed by a colon, :. Not passing an argument for an option that requires one will throw an error.

Example:

gandalf: {
  func: function gandalf() {
    if (gandalf.opts.g) {
      this.echo(
        "A wizard is never late, nor is he early; he arrives precisely when he means to."
      );
    } else if (gandalf.opts.w) {
      this.echo(
        "The world is indeed full of peril, and in it there are many dark places; but still there is much that is fair."
      );
    } else if (gandalf.opts.q) {
      const characters = {
        frodo:
          "Frodo, my dear Hobbit. You have been chosen, and you must bear this burden.",
        sam: "You have a good heart, Sam. You will be a great hero.",
        aragorn:
          "You must understand, my dear Aragorn, that the fate of Middle-earth rests upon your shoulders."
      };
      this.echo(
        `Here is a quote from Gandalf spoken to ${gandalf.opts.q}:\n\n${
          characters[gandalf.opts.q]
        }`
      );
    } else {
      this.echo(
        "Please specify an option: -g for Gandalf the Grey or -w for Gandalf the White. \n\nUse the -q option to return a quote spoken to a provided character."
      );
    }
  },
  man: "Display a quote from either Gandalf the Grey or Gandalf the White.\n\nUse the -g option for Gandalf the Grey, -w for Gandalf the White, and -q to return a quote spoken to a specified character.",
  opts: "gwq:",
  usage: "gandalf [-q (frodo|sam|aragorn)] [-gw]"
}