[BETA] Configure Admin CLI

Last updated
Save as PDF

This article helps Gainsight CS admins install, configure, and use the Gainsight Admin Command-Line Interface (CLI) with an AI agent in Gainsight CS.

This document covers a BETA feature and is subject to change before general availability. Content may be updated as the feature evolves. If you have feedback, please share it with us at docs@gainsight.com

This article helps Gainsight CS admins install, configure, and use the Gainsight Admin Command-Line Interface (CLI) with an AI agent in Gainsight CS.

Overview

The Gainsight Admin CLI is a set of terminal commands that gives an AI agent, such as Claude, direct read and write access to your Gainsight instance. Instead of navigating the Gainsight UI manually to audit or change configuration, you connect the AI agent to your tenant and describe what you want in plain English. The AI agent determines which commands to run, executes them, and reports the results.

Prerequisites

Before setting up the Admin CLI, ensure the following are in place:

Node.js: Must be installed on your machine.
Super admin access: A Gainsight super admin account is required to authenticate and connect the CLI to your instance.

Before logging in, ensure an OAuth application is registered in your Gainsight tenant with the following settings:

Settings	Value
Scopes	Read, Write
PKCE	Enabled
Callback URL	`http://localhost:19876/callback`

For more information on how to configure an OAuth application, refer to the OAuth For Gainsight APIs article.

Key Capabilities

The Admin CLI ships with read and write access across the following modules. The table below describes what your AI Agent can do in each area.

Module	Access	What Your AI Agent Can Do
Connectors	Read	Describe connector jobs Sync schedules Field mappings
Data Designer	Read + Write	List and describe Design Templates Add and edit tasks within templates Preview task output Delete templates Discover source connections, objects, and fields across MDA, Salesforce, and Snowflake
Data Management	Read + Write	List objects and fields Create custom objects Create custom fields
Rules Engine	Read	List rules Describe rule configurations Analyze rule execution history
Journey Orchestrator	Read + Write	List programs Create Journey Orchestrator programs Configure steps Note: Survey creation is not supported.
Scorecard	Read	Describe scorecard structure, measures, weightings, and group assignments
Reporting	Read	List reports and dashboards

Admin CLI Use Cases

The Admin CLI enables three categories of AI-assisted admin work:

Instance Discovery and Documentation: Ask your AI agent to audit an org and return a structured summary of scorecards, rule configurations, redundancies, and gaps. Useful for onboarding handoffs and health checks.
Process Design and Brainstorming: Describe a business process in plain English. Your AI Agent inspects the instance and proposes a configuration plan before anything is built.
Configuration Through Write Operations: Once you confirm a plan, your AI Agent creates objects, fields, rules, and Journey Orchestrator programs directly in the live instance.

Write operations cannot be undone. Gainsight recommends asking your AI agent to create but not publish changes, then reviewing them in the Gainsight UI before confirming. Start with read-only operations until you are comfortable with the workflow.

Install Node.js

The Admin CLI runs on Node.js. To install Node.js:

Open Terminal on your system.
Run the command: brew install node. Homebrew lists the packages it will install.
Enter Y to start the installation. The installation begins, and progress is displayed in the terminal.

Once the installation is complete, verify Node.js is installed correctly by running:

node -v
npm -v

Install Admin CLI

Before installing the Admin CLI, you can create a working folder for the Admin CLI.

Your AI agent might save local snapshots of your instance metadata here, which reduces the need to re-query the instance for every question and improves token usage and response quality over time.

If you work across multiple Gainsight instances, create a sub-folder for each one inside this folder, for example, one for production and one for your sandbox.

Run the following command in the terminal to create a dedicated folder.

mkdir -p ~/Documents/gainsight-admin-cli

cd ~/Documents/gainsight-admin-cli

Once the folder is created, you can install the Admin CLI package.

Install the Package

After a folder is created, you can install the Admin CLI package using the terminal. To install the package:

Open the Terminal.
Run the command below to install the package in the created folder.

cd ~/Documents/gainsight-admin-cli
npm install -g @gainsight/gs-admin-cli@latest

The installation adds packages and registers the CLI commands globally on your machine.

Completed Installation of Admin CLI

After installation completes, verify the CLI is available by running:

gs-admin --help

Admin CLI Commands after installation

If you see a list of available commands, the installation is complete.

If you see command not found, the installation may not have completed correctly. Re-run the npm install command and try again.

Connect Admin CLI to Your Gainsight Tenant

After the Admin CLI is installed, you can now connect your instance to the Admin CLI. To do this, run the following command.

gs-admin login --base-url https://YOUR_TENANT.gainsightcloud.com

Replace the placeholder with your actual tenant URL.

A browser window opens for you to authenticate with your Gainsight super admin credentials. Once you complete the login, return to Terminal and verify the connection by running the command below.

gs-admin whoami

A successful connection returns your user information and tenant details, similar to the following:

Base URL: https://YOUR_TENANT.gainsightcloud.com

Auth mode: OAuth PKCE

Client ID: ...ZYbVJb

Config file: /*/.gs-admin/config.json

Token: valid (expires in 3584s)

Troubleshooting: Enrollment Failed

If the browser shows Enrollment failed: No OAuth app found in this environment, an OAuth app has not been configured in your Gainsight tenant.

Failed Login message

Alternate Setup For AI Agent Chat

You can also configure the CLI as an MCP server using chat within your AI Agent. Open your AI Agent configuration file and add the following, replacing the placeholders with your actual values:

{
  "mcpServers": {
    "gs-admin": {
      "command": "node",
      "args": ["PATH_TO_CODE/gsadmin.js"],
      "env": {
        "GS_CLIENT_ID": "YOUR_CLIENT_ID",
        "GS_CLIENT_SECRET": "YOUR_CLIENT_SECRET",
        "GS_AUTH_URL": "https://YOUR_TENANT.gainsightcloud.com"
      }
    }
  }
}

How to Use Admin CLI With an AI Agent

The steps below use Claude Code as the example, but the same workflow applies to any LLM with tool-use capabilities connected to the Admin CLI.

To start a session:

Open your AI agent's interface
Point your AI agent to your working folder. This is the directory where your Admin CLI and instance data live.
Authenticate to connect to your Gainsight org. The agent runs the login commands, and a browser window opens for OAuth authentication.
Talk to your AI agent in plain English. Ask questions, propose processes, or request changes. The agent translates your intent into CLI commands, runs them, and reports back.

Example Prompts to Get Started:

Audit this tenant and summarize the scorecard configuration
Which rules update the Health Score field?
I want opportunity pains to become customer goals, with a CTA to the AE if they are missing. What would that configuration look like?
Create a custom object called Support Escalation with fields for Account, Priority, and Status.