Command Line Interface (CLI) - Programmatic Usage

Introduction

The CLI plugin provides a powerful command execution system that can be used programmatically for automation, AI/LLM integration, and API-driven chart control.

This tutorial focuses on headless command execution — using the CLI executor without the UI component. Use this tutorial if you are building AI integrations, automation scripts, APIs, or headless chart applications.

For the visual command palette UI, see the CLI-UI tutorial instead.

Who Should Use Programmatic CLI?

Use the CLI executor programmatically if you are:

Building AI or LLM integrations (see AI Ready)
Creating automation scripts for chart control
Developing headless chart applications
Building custom APIs that control charts
Integrating with external systems that need to manipulate charts
Running automated tests with command-based interactions

Before You Begin

Requirements

ChartIQ library version 10.4.0 or later
ChartIQ Core package
CLI plugin
CIQ.ChartEngine instance

Understanding the Architecture

The CLI plugin consists of two components (both included in CLI plugin):

Command Infrastructure (Required for programmatic use):
- plugins/cli/Executor.js - Command execution engine
- plugins/cli/registry.js - Command definitions
- Always available with CLI plugin license
UI Component (Optional to use):
- plugins/cli/cli.js - The <cq-cli> web component
- Only needed if you want the visual command palette
- Can be omitted for headless/AI usage

Important: The CLI plugin is required for AI features. The plugin includes both infrastructure and UI, but you can choose to use only the infrastructure for headless operation.

Getting Started

Step 1: Import Command Infrastructure

Import the headless CLI module — it defines 🔗CIQ.ChartEngine.prototype.getExecutor() on import, making stx.getExecutor() available on every chart instance with no extra setup:

// CORRECT: Single import for headless CLI (no UI component, no extra setup)
import "./plugins/cli/headlesscli.js";

DO NOT use cli.js for programmatic usage:
// WRONG: Loads unnecessary UI component
import "./plugins/cli/cli.js"; // Only use this for visual command palette
The cli.js file includes the <cq-cli> web component for the visual command palette. Use headlesscli.js instead for AI/automation to keep your bundle size smaller.

Step 2: Create Chart Engine

Create your chart engine instance as usual:

import { CIQ } from "./js/chartiq.js";

const stxx = new CIQ.ChartEngine({
  container: document.querySelector(".chartContainer")
});

Step 3: Get Executor Instance

Use the 🔗getExecutor() method to create an executor instance — it works immediately after import:

// Get executor from chart engine (v10.1.0+)
const executor = stxx.getExecutor();

// Execute commands
await executor("symbol AAPL");
await executor("type line");

That's it! No UI component, no extra setup call.

API Reference

CIQ.ChartEngine.prototype.getExecutor()

Creates a command executor bound to the chart engine instance.

Signature:

getExecutor(env, reg, rpcClient)

Parameters:

env (Object, optional): Custom environment object with callback functions
- echo (Function): Output function for command results
- log (Function): Logging function for informational messages
- toolResponse (Function): Callback for AI/LLM tool responses
- Additional custom properties as needed
reg (Object, optional): Custom command registry (defaults to the registry loaded via headlesscli.js)
rpcClient (Object, optional): RPC client for remote command execution

Returns:

Function: Executor function that accepts command strings

Example:

const executor = stxx.getExecutor({
  echo: (msg) => console.log("Command output:", msg),
  log: (msg) => console.log("Command log:", msg)
});

await executor("help");

Default Environment

If you don't provide a custom environment, getExecutor() creates a default headless environment with:

echo(): Logs to browser console
log(): Logs to browser console
stx: Reference to the chart engine instance🔗