Skip to main content

GuanVis User Guide

What Is GuanVis

GuanVis is a visualization resource generation tool for Guandata BI. It belongs to the GuanCLI tool ecosystem, but is installed separately from GuanCLI:

  • GuanCLI handles BI queries, data troubleshooting, resource management, and login authentication.
  • GuanVis focuses on generating and publishing BI dashboards from natural language.

GuanCLI is the general BI toolbox; GuanVis is the dashboard generation tool. GuanVis reuses the GuanCLI login state when generating and publishing dashboards, so install and log in to GuanCLI first.

With an AI Agent, users can describe the desired dashboard in natural language, such as "Generate a sales operations analysis dashboard based on sales order data." The AI reads dataset structures, designs charts, creates filters and pages, and publishes the page to a specified BI folder.

GuanVis is suitable for quickly drafting operations, sales, customer, and product analysis dashboards, and for presales, implementation, customer trials, and internal validation.

Use GuanVis in a test environment, demo environment, or personal test folder first. Before publishing to a production folder or important customer dashboard, confirm metric definitions, page content, and destination folder.

Note

The product is currently in public beta. All features are free during beta. After beta, commercial authorization is required. To continue using it, contact Guandata sales or your customer success manager.

Prerequisites

Before installing GuanVis, make sure Node.js, npm, and GuanCLI are installed, and guancli auth login has been completed. See GuanCLI User Guide for GuanCLI installation and login.

Install GuanVis

Option 1: Install Globally with npm

npm install -g @guandata/guanvis
guanvis install-skill

To update:

npm update -g @guandata/guanvis
guanvis install-skill
Note

guanvis install-skill installs GuanVis tool instructions for AI Agents, so AI knows when to call GuanVis to generate dashboards. It does not replace GuanCLI login. Page publishing still reuses GuanCLI authentication.

After installation, you can ask in Codex, Cursor, Claude Code, and similar AI tools:

Generate a sales operations analysis dashboard based on the Sales Order Details dataset, and publish it to the test folder first.

Verify installation:

guanvis version

If the command is not found after successful installation, the npm global command directory is usually not in system PATH:

npm prefix -g

Add the corresponding directory to PATH and reopen the terminal.

Option 2: Ask an Agent to Install

Send this prompt to an AI Agent:

Follow the official installation guide to install and check GuanCLI and GuanVis:
https://www.guandata.com/guancli-and-guanvis-installation-guide.md

Log In to BI

GuanVis uses GuanCLI authentication. After guancli auth login succeeds, GuanVis automatically reuses the current authentication when querying datasets and publishing pages. See Log In to GuanCLI.

Generate Dashboards with GuanVis

Users usually do not need to run every GuanVis command manually. The recommended method is to describe business requirements in an AI Agent and let AI complete dataset query, dashboard design, generation, validation, and publishing.

Step 1: Let AI Understand the Dataset

Inspect the Sales Order Details dataset and explain what business analyses it is suitable for.

AI usually summarizes date fields, amount fields, quantity fields, region fields, product fields, customer fields, and suitable metrics and charts.

Step 2: Provide Dashboard Requirements

Generate a Sales Operations Analysis dashboard based on the Sales Order Details dataset.

The target users are sales managers. Focus on monthly sales amount, order count, regional contribution, product ranking, and customer structure.
Sales amount is quantity * unit_price.
Add filters for date, region, category, and order status.
Use a clean and restrained style suitable for daily business review.
Publish to the test folder first.

After generation, tell me the page name, page ID, main charts, and metric definitions that require manual confirmation.

Step 3: Review and Give Feedback

After generation, open the target BI folder and check:

  • Page name, page ID, and folder.
  • Metric definitions.
  • Field selection and business meaning.
  • Chart types.
  • Filters for common analysis dimensions.
  • Correct environment and folder.
  • Layout and visual style.

If something is wrong, tell AI exactly what to change:

Change the regional sales contribution chart to show provinces.
Change the customer structure chart to show sales amount by customer tier.
Add order status and payment method to the order detail table.

By default, ask AI to publish as a new version instead of overwriting the original page directly.

Suggestions

  • State the business goal clearly; do not only say "make a dashboard".
  • Prefer datasets with clear field meanings, such as order, sales, customer, product, store, and inventory details.
  • Specify core metrics and definitions, such as sales amount, order count, customer count, and profit margin.
  • Specify required filters, such as date, region, category, store, customer tier, and order status.
  • For first trials, publish to a test or personal folder.
  • Always review generated results, especially metric definitions and page content.
  • Before external delivery, have a business or project owner confirm the page content.
  • Keep the requirement prompt and generation result for future iteration.

Troubleshooting

GuanVis Command Not Found

npm list -g @guandata/guanvis
npm prefix -g

Windows global commands are usually in %AppData%\npm; macOS/Linux usually use $(npm prefix -g)/bin. Add the directory to PATH and reopen the terminal.

AI Does Not Use GuanVis Automatically

Say explicitly:

Use GuanVis to generate the dashboard.

or:

Follow the GuanVis workflow: read dataset structure first, then generate and publish the dashboard.

If it still does not call GuanVis, confirm:

guanvis install-skill

Not Logged In or Authentication Failed

guancli auth status
guancli auth login
guancli auth list
guancli auth use <profile>

AI Cannot Find the Dataset

Possible causes:

  • Wrong BI environment.
  • Dataset name is incomplete.
  • Dataset is in another folder or environment.
  • Current user has no permission.

Ask AI first:

Confirm the current GuanCLI login environment and search datasets containing "sales".

Generated Fields or Metrics Are Wrong

Tell AI the correct fields or definitions:

Sales amount is not unit_price. It should be quantity * unit_price.
Customer count should be distinct count of customer_id.
Order count should be distinct count of order_id.