gs-admin Explorer

An interactive HTML wiki and an in-repo knowledge base for the
@gainsight/gs-admin-cli package —
the Gainsight Admin CLI & MCP server (gs-admin).

Everything here is generated from the installed CLI's own manifests, so it stays
accurate and is regenerable when the CLI is upgraded. No build dependencies — Node
built-ins only, no npm install to build or test (the npm run typecheck gate CI runs
installs two checker-only devDependencies; nothing runs from them).

Unaffiliated community project. This project is not affiliated with, endorsed by, or
supported by Gainsight, Inc. "Gainsight", gs-admin, and @gainsight/gs-admin-cli are
products and/or trademarks of Gainsight, Inc., named here only to describe what this
project documents and drives. It is not a copy of the CLI and does nothing on its own:
everything here works against the @gainsight/gs-admin-cli package that you install,
license, and authenticate, and the reference material is generated from that installed
package's own command manifests.

Support expectations. One maintainer, best-effort, no SLA. Issues and pull requests
are welcome, but this is not a support channel for Gainsight products: defects in the
CLI itself go to Gainsight, not here.

Currency. This document was last updated on 2026-09-08 (against
@gainsight/[email protected]) with reference to Gainsight's then-current pre-built and
generally available Admin CLI package. Gainsight may have updated its documentation and
available Admin CLI package since then. You can always find the latest version of
Gainsight's documentation and Admin CLI package at
support.gainsight.com.

Because this process wasn't built or endorsed by Gainsight, it's possible that a later
update to the Admin CLI package will interfere with the intended function set forth in
this document. You can always check support.gainsight.com
for the latest information and Admin CLI package.

What's inside

• wiki/index.html — a self-contained, offline, searchable explorer for all
  188 CLI commands / 182 MCP tools across 10 domains, with per-command flags, examples,
  MCP tool names, REST endpoints, plus guide pages and end-to-end workflows.
• reference/ — the same knowledge as markdown: concept docs (architecture, auth, MCP,
  Lane 2 runtime, output formats), generated per-domain command references
  (reference/domains/), task workflows (reference/workflows/), and a
  guide to choosing the gs-admin CLI + plugin vs M2M OAuth
  for giving an AI or automation access to your tenant (also generated as a shareable
  standalone page: wiki/comparison-guide.html).
• data/catalog.json — the normalized catalog that drives both of the above.
• plugins/gs-superadmin/ — a Claude Code plugin that turns any directory into a
  persistent, per-tenant Gainsight admin workspace (setup walkthrough below).
• CLAUDE.md — durable context for Claude Code sessions in this repo: what gs-admin
  is, where the knowledge lives, and the conventions that matter.

The gs-superadmin plugin (Claude Code)

The gs-superadmin plugin lets Claude Code operate your
Gainsight tenant through gs-admin: it indexes and documents every asset (rules, journeys,
scorecards, reports, connectors, …) into a local knowledge base, and guards every mutating
command behind a human approval prompt — reads run freely, writes always ask.

1. Prerequisites

npm i -g @gainsight/gs-admin-cli   # the CLI itself (Node ≥ 18)
gs-admin login                     # OAuth browser flow for your tenant
gs-admin whoami                    # confirm you're on the right tenant

2. Install the plugin

From this repo's marketplace:

claude plugin marketplace add BradleyDB/gs-admin-cli-docs
claude plugin install gs-superadmin@gs-admin-cli-docs

(Or interactively inside Claude Code: /plugin marketplace add BradleyDB/gs-admin-cli-docs,
then pick gs-superadmin from /plugin.)

The marketplace add clones this repo over git, so your machine needs GitHub access: for a
public repo that's automatic; while the repo is private, authenticate first (gh auth login,
or an SSH key on your GitHub account).

Then enable auto-update for the marketplace — /plugin → Marketplaces →
gs-admin-cli-docs. Third-party marketplaces default to auto-update off and there is no
new-version notification, so this is what makes fixes reach you; the
plugin README has the same step plus the
two commands for updating by hand.

3. First run — bootstrap a workspace

cd into the directory you want to work from (a new empty folder is fine), start Claude
Code, and run:

/gs-superadmin:setup

Setup verifies the CLI and your login, confirms a workspace name for the tenant (e.g.
acme-prod/), then indexes your assets and documents the first 25 of them. It creates:

• <slug>/ — the per-tenant knowledge base (git-ignored; contains real tenant metadata)
• .gs-superadmin/ — the operating model, build conventions, and command catalog
• a managed block in CLAUDE.md so every future session picks the workspace up automatically

Re-run to keep documenting in batches: /gs-superadmin:setup --budget 50 or
/gs-superadmin:setup --all.

4. Everyday use

• Just ask — "which rules write to the Company object?", "describe the renewal-risk
  journey", "find the rule named 'CS|Risk|Renewal|Alert'". Claude answers from the KB and
  verifies against the live CLI.
• /gs-superadmin:refresh — detect assets changed since the last run and mark them
  stale (add --document to re-document them immediately).
• /gs-superadmin:audit — check asset names against your naming convention and apply
  renames after you approve the list (setup offers an editable bundled standards pack, or
  bring your org's own).
• /gs-superadmin:deprecate — walk an asset through your deprecation checklist
  (date-prefix rename, description prefix, folder move, unschedule) plus the UI-only steps.
• /gs-superadmin:change-request — turn a change request (Jira ticket, request-event
  JSON, or pasted text) into a reviewable implementation plan: KB-cited impact analysis,
  convention-checked names, exact commands, verification, rollback. Nothing executes at
  drafting time.
• /gs-superadmin:email-report — read-only Journey Orchestrator reports: which emails
  mention a phrase, a program's full email inventory, a schedule audit of everything
  active, or object/field usage in participant sources. Also answers natural questions
  like "which emails mention the renewal reminder?".
• /gs-superadmin:deps-report — tenant-wide impact analysis: every documented asset
  (rules, journeys, reports, connector jobs, data designers, scorecards) that depends on
  a given object, field, or external connection. Also triggered by questions like "what
  breaks if I change this field?".
• /gs-superadmin:report-bug — capture a gs-admin CLI misbehavior as a vendor-ready
  bug report while the evidence is still in the session; never sent or committed anywhere
  by the skill.
• Note on invoking skills: most of these run only via their exact slash command —
  see the skill catalog in the plugin README
  for which ones also respond to natural language.
• Safety model — read-only by default. Every mutating gs-admin command (and MCP tool)
  triggers an approval prompt naming the command and the target tenant; unknown commands
  prompt too (fail-closed). Approved CLI mutations are journaled to
  <slug>/changes/JOURNAL.md (timestamp, operator, command, system area, source ticket)
  for a grep-able change history. Asset names containing | are caught by a shell-safety
  lint so they're never mangled into shell pipelines.

5. Two instances (Sandbox + Production)

Install once, then run gs-admin login --base-url <url> + /gs-superadmin:setup once per
instance — each tenant gets its own KB folder in the same working directory, and setup
records which one is production so write-approval prompts flag it. Switching, per-tenant
tokens, and the Journey-cache caveat are covered in the
plugin README.

Full details — folder layout, the mutation guard, regeneration after CLI upgrades — in the
plugin README.

View the wiki

It's a single self-contained file — no server required. Just open it in any browser:

wiki/index.html        # double-click, or open via file:// in your browser

Everything (the catalog, docs, CSS, and JS) is inlined, so it runs entirely offline from
the local file with no network and nothing to install or run.

Regenerate

Two different intents — don't mix them up:

Rebuild at the pinned version (verify your changes; what CI does). Install the exact
version the repo documents — it's recorded in data/catalog.json under meta.cliVersion:

npm i -g @gainsight/gs-admin-cli@"$(node -p "require('./data/catalog.json').meta.cliVersion")"
npm run build          # should reproduce the committed output byte-for-byte

Deliberately upgrade what the repo documents (a real change, not a rebuild):

npm i -g @gainsight/gs-admin-cli@latest
npm run build          # extract-catalog → build-reference → build-wiki →
                       # build-comparison-html → build-plugin-gs-superadmin → emit-reader-shapes

Expect large diffs across data/, reference/domains/, wiki/, and the plugin bundle —
that's the point. Then update the version/counts cited in hand-written docs;
node build/check-stale-facts.mjs (run by CI on every PR) lists every spot that needs it.

Steps can be run individually: npm run build:catalog, build:reference, build:wiki,
build:comparison, build:plugin:gs-superadmin, build:reader-shapes (the last needs no
CLI: it measures which payload keys the plugin's knowledge-base readers dereference, into
data/reader-shapes.json, the read-surface contract the gs-fortress CLI audit consumes).

The extractor locates the installed CLI via npm root -g (works out of the box when
gs-admin is installed globally). If it lives somewhere non-standard, override the path with
either the GS_ADMIN_PKG env var (bash: export GS_ADMIN_PKG=/path/to/package;
PowerShell: $env:GS_ADMIN_PKG = 'C:\path\to\package') or a local
gs-admin-explorer.config.json (copy
gs-admin-explorer.config.example.json — it's git-ignored, so it stays on your machine).

Contributing

See CONTRIBUTING.md. If you develop with an AI assistant (most
contributors do), load AGENTS.md into its context first — it's the terse
rules-of-record: which files are generated, the design tenets that look like bugs, and
the verification commands. Security issues (e.g. a guard-hook bypass) go through
SECURITY.md — privately, not as public issues.

Pull requests target dev, never main. From a fork, start from
this compare link — it
pre-selects dev as the base branch, which GitHub's own "Contribute" button does not.

Bug reports, documentation corrections, and feature asks each have their own issue form
under New issue; the doc form asks for your CLI version, because the reference here is
generated from one pinned version and a mismatch is often a version difference. Everyone
taking part is expected to follow the Code of Conduct.

Requirements

• Node.js ≥ 18 (developed against v24).
• @gainsight/gs-admin-cli installed globally (npm i -g @gainsight/gs-admin-cli) —
  this project reads its bundled manifests to generate the docs. It does not call the
  Gainsight API, so no login/tenant is needed just to build the wiki.

How it works

The CLI is artifact-driven: its commands and MCP tools are declared in 8 JSON manifests
inside the installed package. build/extract-catalog.mjs parses those (plus the 12 Lane-2
runtime verbs and 6 static auth commands) into data/catalog.json; build-reference.mjs
and build-wiki.mjs render the markdown and the HTML, build-comparison-html.mjs
renders the standalone comparison guide, build-plugin-gs-superadmin.mjs writes the
plugin's bundled reference, and emit-reader-shapes.mjs records which payload keys the
plugin's readers dereference (data/reader-shapes.json). See reference/architecture.md.