### Install and Build Power BI Visuals in CI/CD

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/overview.md

Install the powerbi-visuals-tools globally, install project dependencies, and run linting and packaging commands. Use flags like --no-minify and --verbose for detailed build processes.

```bash
# Install tools
npm install -g powerbi-visuals-tools

# Install project dependencies
npm install

# Run linting
pbiviz lint --fix

# Run validation
pbiviz lint

# Build package
pbiviz package \
  --no-minify \
  --no-stats \
  --verbose \
  --certification-audit
```

--------------------------------

### Build Power BI Visuals Tools from Source

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/MCP.md

Clone the repository, install dependencies, and build the project. Ensure Node.js is installed.

```bash
git clone https://github.com/Microsoft/PowerBI-visuals-tools.git
cd PowerBI-visuals-tools
npm install
npm run build
```

--------------------------------

### Start Development Server Command

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/README.md

Command to start the development server for a Power BI visual.

```bash
# Start development server
pbiviz start [--port=8080] [--drop] [--no-stats] [--skip-api] [--all-locales] [--pbiviz-file=pbiviz.json]
```

--------------------------------

### CommandManager.start

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/api-reference/CommandManager.md

Starts the development server with hot-reload capabilities for local development. It handles HTTPS setup, visual preparation, configuration validation, and webpack dev server initialization.

```APIDOC
## CommandManager.start

### Description
Starts the development server with hot-reload capabilities.

### Method
static async start(options: StartOptions, rootPath: string): Promise<void>

### Parameters
#### Path Parameters
- **rootPath** (string) - Required - Project root directory path

#### Options
- **options.port** (number) - Optional - Port number for dev server (Default: 8080)
- **options.stats** (boolean) - Optional - Generate statistics files (Default: true)
- **options.drop** (boolean) - Optional - Output files to drop folder (Default: false)
- **options.skipApi** (boolean) - Optional - Skip powerbi-visuals-api version checking (Default: false)
- **options.allLocales** (boolean) - Optional - Keep all locale files in package (Default: false)
- **options.pbivizFile** (string) - Optional - Path to visual config file (Default: `pbiviz.json`)

### Returns
Promise that resolves when server starts

### Description
Initializes webpack dev server with hot-reload for local development. Sets up https with certificate, prepares visual, validates configuration, and starts webpack dev server.

### Example
```typescript
import CommandManager from './CommandManager.js';

await CommandManager.start({
  port: 8080,
  stats: true,
  drop: false,
  skipApi: false,
  allLocales: false,
  pbivizFile: 'pbiviz.json'
}, process.cwd());
```
```

--------------------------------

### Install PowerBI Visuals Tools

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/README.md

Install the PowerBI visuals tools globally using npm. This command requires Node.js to be installed.

```bash
npm install -g powerbi-visuals-tools
```

--------------------------------

### Start Development Server Workflow

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/overview.md

Details the steps involved in starting the development server for a Power BI visual, including configuration loading, validation, and Webpack initialization.

```text
pbiviz start [--port] [--drop] [--skip-api]
    ↓
CommandManager.start()
    ↓
VisualManager.prepareVisual()
    ├─ Load pbiviz.json
    ├─ Load capabilities.json
    └─ Create Visual instance
    ↓
VisualManager.validateVisual()
    ├─ FeatureManager.validate(PreBuild)
    └─ Output errors/warnings
    ↓
VisualManager.initializeWebpack()
    ├─ WebPackWrap.generateWebpackConfig()
    ├─ Load tsconfig.json
    ├─ Validate API version
    ├─ Configure plugins, loaders
    └─ Create webpack compiler
    ↓
VisualManager.startWebpackServer()
    └─ Listen on https://localhost:port
```

--------------------------------

### Programmatic Usage: Create and Start Visuals Tools

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/README.md

Utilize the CommandManager for programmatic control over Power BI Visuals Tools. This example demonstrates creating a new visual project and starting the development server with specific configurations.

```typescript
import CommandManager from 'powerbi-visuals-tools/lib/CommandManager.js';

// Create visual
await CommandManager.new(
    { force: false, template: 'default' },
    'MyVisual',
    process.cwd()
);

// Start server
await CommandManager.start({
    port: 8080,
    stats: false,
    drop: false,
    skipApi: false,
    allLocales: false,
    pbivizFile: 'pbiviz.json'
}, process.cwd());
```

--------------------------------

### CommandManager.installCert

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/api-reference/CommandManager.md

Creates and installs a localhost SSL certificate for secure development environments.

```APIDOC
## CommandManager.installCert

### Description
Creates and installs a localhost SSL certificate for secure development environments. This is platform-specific, using openssl for Linux/macOS and PowerShell for Windows.

### Method Signature
`static async installCert(): Promise<void>`

### Parameters
None

### Returns
`Promise<void>` that resolves when certificate setup completes.

### Example
```typescript
await CommandManager.installCert();
```
```

--------------------------------

### Start Development Server with CommandManager

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/api-reference/CommandManager.md

Starts the development server with hot-reload capabilities. Use this to initiate a local development environment for PowerBI visuals. Ensure all required options are provided.

```typescript
import CommandManager from './CommandManager.js';

await CommandManager.start({
  port: 8080,
  stats: true,
  drop: false,
  skipApi: false,
  allLocales: false,
  pbivizFile: 'pbiviz.json'
}, process.cwd());
```

--------------------------------

### Verify pbiviz Installation

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/README.md

Run the pbiviz command without any parameters to display the help screen and confirm successful installation.

```bash
pbiviz
```

--------------------------------

### Create and Start a New Power BI Visual Project

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/README.md

Use these commands to create a new Power BI visual project, navigate into its directory, and start the development server. The server automatically reloads changes made to your source files.

```bash
# Create new project
pbiviz new MyVisual

cd MyVisual

# Start dev server
pbiviz start

# Edit src/visual.ts
# Server auto-reloads on save

# Test in Power BI Desktop or cloud
# Changes reflected immediately

# When ready, lint
pbiviz lint --fix

# Build for testing
pbiviz package
```

--------------------------------

### Install Dependencies and Link Local Version

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/CONTRIBUTING.md

Installs project dependencies and links the locally cloned repository version of the powerbi-visuals-tools globally. Restart your terminal if `pbiviz` is not recognized globally after linking.

```bash
npm install
npm uninstall -g powerbi-visuals-tools
npm link
```

--------------------------------

### StartOptions Interface

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/api-reference/CommandManager.md

Defines options for the start command. Use to configure the development server port, enable stats, and control API and locale processing.

```typescript
interface StartOptions {
    port: number;
    stats: boolean;
    drop: boolean;
    skipApi: boolean;
    allLocales: boolean;
    pbivizFile: string;
}
```

--------------------------------

### Example pbiviz.json Configuration

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/configuration.md

This JSON file defines essential metadata for a Power BI visual, including its name, display name, version, unique identifier (GUID), author information, API version, and paths to its capabilities and dependencies files. It also includes optional support and repository URLs.

```json
{
  "name": "circleCard",
  "displayName": "Circle Card",
  "guid": "circleCard1234567890123456789012",
  "version": "1.0.0",
  "description": "Circle card visual displays a single metric in a circle.",
  "apiVersion": "4.1.0",
  "author": {
    "name": "John Doe",
    "email": "john@example.com"
  },
  "supportUrl": "https://github.com/microsoft/powerbi-visuals-circlecard",
  "repositoryUrl": "https://github.com/microsoft/powerbi-visuals-circlecard",
  "capabilities": "capabilities.json",
  "dependencies": "dependencies.json"
}
```

--------------------------------

### Install Certificate Command

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/configuration.md

Creates and installs a self-signed HTTPS certificate for development. This command is platform-specific and may require administrative privileges.

```bash
pbiviz install-cert
```

--------------------------------

### CLI Usage Example

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/overview.md

Demonstrates how to invoke the Power BI visuals CLI tool for commands and options. Can be used globally or via npx.

```bash
npx pbiviz <command> [options]
# or globally
pbiviz <command> [options]
```

--------------------------------

### TypeScript Example: Show Tooltip

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/MCP.md

Example of how to display a tooltip using the `host.tooltipService.show()` API. Ensure `tooltipData` and coordinates are correctly provided.

```typescript
host.tooltipService.show({
    dataItems: tooltipData,
    coordinates: [x, y]
});
```

--------------------------------

### Start Command Options for Development Server

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/configuration.md

Configures the development server for Power BI visuals. Use the --port option to specify a custom port and --drop to serve assets via drop folder middleware.

```bash
pbiviz start [options]
```

```bash
pbiviz start --port 8080 --drop
```

```bash
pbiviz start --skip-api --pbiviz-file pbiviz.mjs
```

--------------------------------

### Install npm Packages

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/api-reference/VisualManager.md

Installs npm dependencies for a visual project. Call this after creating a new visual project to ensure all necessary packages are installed.

```typescript
static installPackages(visualPath: string): Promise<void>
```

--------------------------------

### Start MCP Server

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/api-reference/CommandManager.md

Launches the Model Context Protocol (MCP) server, which provides tools for AI assistants to interact with Power BI visuals.

```typescript
await CommandManager.mcp(rootPath);
```

--------------------------------

### Programmatically Start Power BI Visuals Dev Server

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/overview.md

Use the CommandManager to start the development server for a Power BI visual. Configure options such as port, stats, and skip API checks. This operation is asynchronous.

```typescript
import CommandManager from 'powerbi-visuals-tools/lib/CommandManager.js';

// Or start dev server
await CommandManager.start(
    { port: 8080, stats: false, drop: false, skipApi: false, allLocales: false, pbivizFile: 'pbiviz.json' },
    process.cwd()
);
```

--------------------------------

### Install Power BI API Package

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/api-reference/WebPackWrap.md

Installs or updates the powerbi-visuals-api dependency. Returns true on success and false on failure. May throw if the API version is invalid.

```typescript
const installed = await webpackWrap.installAPIpackage();
if (!installed) {
    console.error('Failed to install API package');
}
```

--------------------------------

### installAPIpackage

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/api-reference/WebPackWrap.md

Installs or updates the powerbi-visuals-api dependency using npm, based on the version specified in pbiviz.json or 'latest'.

```APIDOC
## installAPIpackage

### Description
Installs or updates powerbi-visuals-api dependency.

### Method
`async installAPIpackage(): Promise<boolean>`

### Returns
Promise resolving to true on success, false on failure

### Throws
May throw if API version is invalid

### Example
```typescript
const installed = await webpackWrap.installAPIpackage();
if (!installed) {
    console.error('Failed to install API package');
}
```
```

--------------------------------

### Manage Certificate Command

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/README.md

Command to install the development certificate for Power BI visuals.

```bash
# Manage certificate
pbiviz install-cert
```

--------------------------------

### Install Localhost SSL Certificate

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/api-reference/CommandManager.md

Generates and installs a self-signed SSL certificate for the development server. This command handles platform-specific certificate generation using openssl or PowerShell.

```typescript
await CommandManager.installCert();
```

--------------------------------

### Run MCP Server Manually

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/MCP.md

Execute this command in your visual project's root directory to manually start the MCP server for testing. The server operates on STDIO and responds to MCP requests without visible output.

```bash
cd /path/to/your/visual-project
pbiviz mcp
```

--------------------------------

### TypeScript Example: Selection Manager

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/MCP.md

Demonstrates how to use the `selectionManager` to select items. Obtain the `selectionManager` instance using `host.createSelectionManager()` and then call `select()` with a `selectionId`.

```typescript
const selectionManager = host.createSelectionManager();
selectionManager.select(selectionId);
```

--------------------------------

### CommandManager.mcp

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/api-reference/CommandManager.md

Starts the MCP (Model Context Protocol) server, enabling AI integration for Power BI visuals.

```APIDOC
## CommandManager.mcp

### Description
Starts the MCP (Model Context Protocol) server, enabling AI integration for Power BI visuals. This server provides tools for AI assistants to analyze and modify Power BI visuals.

### Method Signature
`static async mcp(rootPath: string): Promise<void>`

### Parameters
#### rootPath (`string`)
- Required - Project root directory.

### Returns
`Promise<void>` that resolves when MCP server starts.

### Example
```typescript
await CommandManager.mcp(process.cwd());
```
```

--------------------------------

### installPackages

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/api-reference/VisualManager.md

Installs the npm dependencies required for a Power BI visual project. This is typically called after a project has been created or modified.

```APIDOC
## installPackages

### Description
Installs npm dependencies for a visual project. This method ensures that all necessary packages are downloaded and installed for the visual to function correctly.

### Method
`static installPackages(visualPath: string): Promise<void>`

### Parameters
#### Path Parameters
* None

#### Query Parameters
* None

#### Request Body
* None

### Parameters
#### Path Parameters
* `visualPath` (string) - Yes - Path to visual project

### Request Example
```typescript
VisualManager.installPackages('./my-visuals/MyAwesomeVisual')
```

### Response
#### Success Response
* Resolves when npm install completes successfully.

#### Response Example
```typescript
Promise<void>
```

### Throws
* Rejects with an error message if the npm installation fails.
```

--------------------------------

### Create New Visual Workflow

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/overview.md

Illustrates the sequence of operations for creating a new Power BI visual project using the CLI, including template fetching and package installation.

```text
pbiviz new <name> [--template] [--force]
    ↓
CommandManager.new()
    ↓
VisualManager.createVisual()
    ↓
├─ TemplateFetcher (downloads template)
├─ VisualGenerator (generates project structure)
├─ VisualManager.installPackages() (npm install)
└─ VisualManager (ready for development)
```

--------------------------------

### Implement a New Feature in Power BI Visuals Tools

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/features.md

This example demonstrates how to create a new feature by implementing the BaseFeature interface. It includes static properties for feature configuration and a static method to check if the feature is supported.

```typescript
import { Severity, Stage, VisualFeatureType } from "./FeatureTypes.js";
import BaseFeature from "./BaseFeature.js";

export default class YourFeature implements BaseFeature {
    public static featureName = "Your Feature"
    public static severity = Severity.Warning
    public static stage = Stage.PostBuild
    public static visualFeatureType = VisualFeatureType.NonSlicer
    public static errorMessage = "Your Feature not detected..."
    public static certificationRequired = false
    
    static isSupported(sourceInstance) {
        return sourceInstance.contain('.yourAPI');
    }
}
```

--------------------------------

### Start Webpack Development Server

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/api-reference/VisualManager.md

Launches the webpack development server with hot-reloading capabilities. The server runs in the background and can be configured to serve visual assets via drop file middleware.

```typescript
visualManager.startWebpackServer(false);
// Server listens, press Ctrl+C to stop
```

--------------------------------

### Skip TypeScript Type Checking for Faster Builds

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/configuration.md

Use the `--skip-api` flag with `pbiviz start` to reduce build times by skipping TypeScript type checking during development.

```bash
pbiviz start --skip-api  # Reduce build time
```

--------------------------------

### createVisual

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/api-reference/VisualManager.md

Creates a new Power BI visual project from a template. It scaffolds the project structure, installs npm dependencies, and can optionally overwrite existing files or use a specific template.

```APIDOC
## createVisual

### Description
Creates a new visual project from a template. This method scaffolds the project structure, installs npm packages, and can be configured with options for forcing overwrites or specifying a template.

### Method
`static async createVisual(rootPath: string, visualName: string, generateOptions: GenerateOptions): Promise<VisualManager | void>`

### Parameters
#### Path Parameters
* None

#### Query Parameters
* None

#### Request Body
* None

### Parameters
#### Path Parameters
* `rootPath` (string) - Yes - Parent directory for project
* `visualName` (string) - Yes - Name of visual
* `generateOptions` (GenerateOptions) - Yes - Template and force options
  * `force` (boolean) - No - Overwrite existing folder
  * `template` (string) - No - Template name

### Request Example
```typescript
VisualManager.createVisual('./my-visuals', 'MyAwesomeVisual', { force: true, template: 'basic' })
```

### Response
#### Success Response
* Resolves with a `VisualManager` instance or `void` if an external template fetcher is used.

#### Response Example
```typescript
// Example of a successful resolution (actual return value depends on implementation)
Promise<VisualManager | void>
```

### Throws
* Rejects with an error if the visual creation process fails.
```

--------------------------------

### Display Visual Project Information

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/api-reference/VisualManager.md

Prints the visual project's configuration information, such as name, display name, GUID, version, and API version, to the console in a formatted table.

```typescript
visualManager.displayInfo();
// Outputs: Name, Display Name, GUID, Version, API Version, etc.
```

--------------------------------

### Create Visual Project

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/api-reference/VisualManager.md

Creates a new visual project from a template. Use this to scaffold a new Power BI visual. It handles template selection, package installation, and generator calls.

```typescript
static async createVisual(rootPath: string, visualName: string, generateOptions: GenerateOptions): Promise<VisualManager | void>
```

--------------------------------

### getRootPath

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/api-reference/utilities.md

Gets the root directory of the PowerBI tools installation using import.meta.url for ES module compatibility.

```APIDOC
## getRootPath

### Description
Gets the root directory of the PowerBI tools installation.

### Method
```typescript
function getRootPath(): string
```

### Returns
`string` - Absolute path to tools root directory

### Description
Uses import.meta.url to locate tools package root. Works with ES modules.

### Example
```typescript
import { getRootPath } from './utils.js';

const toolsRoot = getRootPath();
// Returns: /usr/local/lib/node_modules/powerbi-visuals-tools
```
```

--------------------------------

### prepareFoldersAndFiles

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/api-reference/WebPackWrap.md

Creates necessary build directories (.tmp, precompile, drop, package) and a visualPlugin.ts stub file.

```APIDOC
## prepareFoldersAndFiles

### Description
Creates necessary build directories and files.

### Method
`static async prepareFoldersAndFiles(visualPackage: VisualManager): Promise<void>`

### Parameters
#### Path Parameters
- **visualPackage** (`VisualManager`) - Visual manager instance

### Returns
Promise that resolves when directories are created
```

--------------------------------

### Create Project Structure with Utilities

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/api-reference/utilities.md

Demonstrates creating a visual directory and downloading a template ZIP using utility functions.

```typescript
import { createFolder, download } from './utils.js';

// Create visual directory
const visualPath = createFolder('my-visual');

// Download template
await download(templateUrl, visualPath + '/template.zip');
```

--------------------------------

### Get PowerBI Tools Root Path

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/api-reference/utilities.md

Retrieves the absolute path to the root directory of the PowerBI tools installation using import.meta.url. This method is compatible with ES modules.

```typescript
import { getRootPath } from './utils.js';

const toolsRoot = getRootPath();
// Returns: /usr/local/lib/node_modules/powerbi-visuals-tools
```

--------------------------------

### Configuration Loading Flow

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/overview.md

Illustrates the process of loading configuration files like pbiviz.json and capabilities.json during visual instance creation and validation.

```plaintext
pbiviz.json (visual metadata)
        ↓
readJsonFromVisual("pbiviz.json")
        ↓
Visual instance (feature type detection)
        ↓
FeatureManager (pre-build validation)

capabilities.json (data view mappings)
        ↓
readJsonFromVisual("capabilities.json")
        ↓
Visual instance (slicer/matrix detection)
        ↓
Package instance (post-build validation)
```

--------------------------------

### startWebpackServer

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/api-reference/VisualManager.md

Launches the webpack development server with hot-reloading capabilities and optional middleware for serving visual assets.

```APIDOC
## startWebpackServer

### Description
Starts an HTTPS webpack dev server with hot-reloading. If `generateDropFiles` is true, configures middleware to serve visual.js, visual.css, and pbiviz.json at specific routes.

### Method
`startWebpackServer(generateDropFiles: boolean = false): void`

### Parameters
#### Query Parameters
- **generateDropFiles** (boolean) - Optional - Default: `false` - Set up drop file middleware

### Returns
void (server runs in background)

### Example
```typescript
visualManager.startWebpackServer(false);
// Server listens, press Ctrl+C to stop
```
```

--------------------------------

### configureDevServer

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/api-reference/WebPackWrap.md

Sets up the webpack dev server with HTTPS, configuring certificate files, static directory, and asset routes.

```APIDOC
## configureDevServer

### Description
Sets up webpack dev server with HTTPS.

### Method
`async configureDevServer(visualPackage: VisualManager, port: number = 8080): Promise<void>`

### Parameters
#### Path Parameters
- **visualPackage** (`VisualManager`) - Required - Visual manager instance
- **port** (`number`) - Optional - Server port (Default: 8080)

### Returns
Promise that resolves when configuration is applied

### Example
```typescript
const webpackWrap = new WebPackWrap();
await webpackWrap.configureDevServer(visualManager, 8080);
// Server now configured for https://localhost:8080 with self-signed cert
```
```

--------------------------------

### CommandManager.mcpInit

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/api-reference/CommandManager.md

Initializes MCP configuration in the current project by creating the necessary configuration file.

```APIDOC
## CommandManager.mcpInit

### Description
Initializes MCP configuration in the current project by creating the necessary configuration file (`.vscode/mcp.json`) for MCP server integration.

### Method Signature
`static async mcpInit(rootPath: string): Promise<void>`

### Parameters
#### rootPath (`string`)
- Required - Project root directory.

### Returns
`Promise<void>` that resolves when configuration is created.

### Example
```typescript
await CommandManager.mcpInit(process.cwd());
```
```

--------------------------------

### CommandManager.new

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/api-reference/CommandManager.md

Creates a new visual project from a template. This method generates the project structure, copies template files, and sets up the initial configuration.

```APIDOC
## CommandManager.new

### Description
Creates a new visual project from a template. This method generates the project structure, copies template files, and sets up the initial configuration.

### Method Signature
`static new(options: NewOptions, name: string, rootPath: string): void`

### Parameters
#### options (`NewOptions`)
- **force** (`boolean`) - Optional - Overwrite if folder exists. Defaults to `false`.
- **template** (`string`) - Optional - Template name: 'default', 'table', 'slicer', 'rvisual', 'rhtml', 'circlecard'. Defaults to `'default'`.

#### name (`string`)
- Required - Name of new visual.

#### rootPath (`string`)
- Required - Directory to create project in.

### Returns
`void` (performs side effects)

### Example
```typescript
CommandManager.new({
  force: false,
  template: 'default'
}, 'MyVisual', process.cwd());
```
```

--------------------------------

### generateWebpackConfig

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/api-reference/WebPackWrap.md

The main entry point for generating the webpack configuration. It orchestrates the entire webpack setup process.

```APIDOC
## generateWebpackConfig

### Description
Main entry point for generating webpack configuration.

### Method Signature
```typescript
async generateWebpackConfig(visualPackage: VisualManager, options?: WebpackOptions): Promise<object>
```

### Parameters
- **visualPackage** (`VisualManager`): Visual manager instance (Required).
- **options** (`WebpackOptions`, Optional): Build options (uses defaults).

### Returns
- `Promise<object>`: A promise resolving to the webpack configuration object.

### Description
Orchestrates complete webpack setup: loads tsconfig and pbiviz.json, validates API package, configures folders, plugins, loaders, dev server, and returns ready-to-use webpack config.

### Example
```typescript
const webpackWrap = new WebPackWrap();
const config = await webpackWrap.generateWebpackConfig(visualManager, {
    devMode: true,
    generateResources: true,
    generatePbiviz: false,
    minifyJS: false,
    minify: false,
    devServerPort: 8080,
    stats: true,
    skipApiCheck: false,
    allLocales: false,
    pbivizFile: 'pbiviz.json'
});

// config ready for webpack(config).run() or webpack-dev-server
```
```

--------------------------------

### New Command Options for Creating Visuals

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/configuration.md

Creates a new Power BI visual project. Specify a template like 'default' or 'table', and use --force to overwrite an existing directory.

```bash
pbiviz new <name> [options]
```

```bash
pbiviz new MyVisual --template default
```

```bash
pbiviz new MyVisual --template table --force
```

--------------------------------

### initializeWebpack

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/api-reference/VisualManager.md

Prepares the webpack configuration for compilation, allowing customization of build options like mode, minification, and resource generation.

```APIDOC
## initializeWebpack

### Description
Generates webpack configuration from a template, applies options (dev/prod mode, minification, plugins), and initializes the compiler. Validates API version and capabilities.

### Method
`async initializeWebpack(webpackOptions: WebpackOptions): Promise<this>`

### Parameters
#### Request Body
- **webpackOptions** (WebpackOptions) - Required - Webpack build configuration
  - **devMode** (boolean) - Optional - Enables development mode
  - **devtool** (string) - Optional - Specifies source map generation
  - **generateResources** (boolean) - Optional - Generates resource files
  - **generatePbiviz** (boolean) - Optional - Generates .pbiviz package
  - **minifyJS** (boolean) - Optional - Minifies JavaScript output
  - **minify** (boolean) - Optional - Minifies all output
  - **devServerPort** (number) - Optional - Port for the development server
  - **stats** (boolean) - Optional - Enables webpack stats output
  - **skipApiCheck** (boolean) - Optional - Skips API version check
  - **allLocales** (boolean) - Optional - Includes all locales
  - **pbivizFile** (string) - Optional - Path to pbiviz.json

### Returns
Promise resolving to `this` for method chaining.

### Example
```typescript
await visualManager.initializeWebpack({
  devMode: true,
  devtool: 'eval-source-map',
  generateResources: true,
  generatePbiviz: false,
  minifyJS: false,
  minify: false,
  devServerPort: 8080,
  stats: true,
  skipApiCheck: false,
  allLocales: false,
  pbivizFile: 'pbiviz.json'
});
```
```

--------------------------------

### Author Information JSON Configuration

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/features.md

Example JSON structure for defining author name and email in `pbiviz.json`. This is required for the AuthorInfo feature validation.

```json
"author": {
    "name": "John Doe",
    "email": "john@example.com"
}
```

--------------------------------

### prepareVisual

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/api-reference/VisualManager.md

Loads and parses visual configuration files, including pbiviz.json and capabilities.json. This method must be called before other operations.

```APIDOC
## prepareVisual

### Description
Loads and parses visual configuration files (pbiviz.json, capabilities.json) and creates a Visual instance. This method must be called before other operations.

### Method
`async prepareVisual(pbivizFile: string = 'pbiviz.json'): Promise<this>`

### Parameters
#### Query Parameters
- **pbivizFile** (string) - Optional - Default: `pbiviz.json` - Config file name or path

### Returns
Promise resolving to `this` (VisualManager instance) for chaining.

### Throws
Exits process with code 1 if config file not found.

### Example
```typescript
const visualManager = new VisualManager(process.cwd());
await visualManager.prepareVisual('pbiviz.json');
```
```

--------------------------------

### Instantiate Package

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/api-reference/Package.md

Create a new Package instance with compiled source code, capabilities, and feature type flags.

```typescript
const package = new Package(sourceCode, capabilities, visualFeatureType);
```

--------------------------------

### Prepare Visual Configuration

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/api-reference/VisualManager.md

Loads and parses visual configuration files, including pbiviz.json and capabilities.json. Must be called before other operations. It returns a Promise resolving to the VisualManager instance for chaining.

```typescript
await visualManager.prepareVisual('pbiviz.json');
```

--------------------------------

### Initialize MCP Configuration

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/api-reference/CommandManager.md

Creates the necessary `.vscode/mcp.json` configuration file for MCP server integration within the current project.

```typescript
await CommandManager.mcpInit(rootPath);
```

--------------------------------

### ConsoleWriter.getLogoVisualization() - Get CLI Logo

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/api-reference/ConsoleWriter.md

Returns the PowerBI Visuals Tools logo as ASCII art string. This is used for display in CLI help text.

```typescript
static getLogoVisualization(): string
```

```typescript
const logo = ConsoleWriter.getLogoVisualization();
console.log(logo);
```

--------------------------------

### Run Lint Validation with Auto-Fix

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/api-reference/LintValidator.md

Example of initializing LintValidator with auto-fix enabled and running the validation process. This will attempt to fix linting errors and report on the process.

```typescript
const linter = new LintValidator({
    verbose: false,
    fix: true
});
await linter.runLintValidation();
// Console output:
// info  Lint fixing errors...
// info  Running lint check...
// info  Lint check completed.
```

--------------------------------

### Visual Constructor

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/api-reference/Visual.md

Initializes a new instance of the Visual class with parsed capabilities and configuration objects.

```APIDOC
## Constructor

```typescript
constructor(capabilities: object, config: object)
```

### Parameters

- **capabilities** (`object`) - Required - Parsed capabilities.json
- **config** (`object`) - Required - Parsed pbiviz.json
```

--------------------------------

### Recursively Get Source Files

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/api-reference/utilities.md

Finds all TypeScript/JavaScript files in a directory, recursively scanning subdirectories. It skips 'node_modules' and '.tmp' directories. Use this to gather all source files for processing.

```typescript
async function getSourceFiles(dir: string): Promise<string[]>
```

```typescript
import { getSourceFiles } from './utils.js';

const files = await getSourceFiles('./src');
console.log(files);
// Returns: ['./src/index.ts', './src/visual.ts', ...]
```

--------------------------------

### Power BI Visual Initialization and Feature Check

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/api-reference/Visual.md

Demonstrates initializing a Visual object with capabilities and config, then checking its API version, version format, author information, and computed feature type.

```typescript
import { Visual } from './Visual.js';

// Load visual config
const capabilities = {
    dataViewMappings: [{ table: {} }],
    objects: {
        general: {
            properties: {
                filter: { type: { filter: {} } }
            }
        }
    }
};

const config = {
    visual: { version: '1.0.0' },
    apiVersion: '4.1.0',
    author: {
        name: 'John Doe',
        email: 'john@example.com'
    }
};

const visual = new Visual(capabilities, config);

// Check features
console.log(visual.doesAPIVersionMatch('4.0.0')); // true
console.log(visual.isVisualVersionValid(3));      // true
console.log(visual.isAuthorDefined());            // true
console.log(visual.visualFeatureType);            // Slicer | Matrix
```

--------------------------------

### Package Command Options for Building Visuals

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/configuration.md

Generates a Power BI visual package. Use --resources to include resource folders, --minify to enable minification, and --compression to set ZIP compression level.

```bash
pbiviz package [options]
```

```bash
pbiviz package --resources --minify --compression 9
```

```bash
pbiviz package --certification-audit --verbose
```

--------------------------------

### VisualManager Constructor

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/api-reference/VisualManager.md

Initializes a new VisualManager instance. It requires the root path of the visual project.

```APIDOC
## VisualManager Constructor

### Description
Initializes a new VisualManager instance tied to a specific file path.

### Parameters
#### Path Parameters
- **rootPath** (string) - Required - File path to visual project root
```

--------------------------------

### displayInfo

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/api-reference/VisualManager.md

Prints visual project information, including configuration details like name, version, and API version, to the console.

```APIDOC
## displayInfo

### Description
Prints visual project information.

### Method Signature
```typescript
displayInfo(): void
```

### Returns
`void`

### Description
Outputs pbivizConfig as formatted table to console.

### Example
```typescript
visualManager.displayInfo();
// Outputs: Name, Display Name, GUID, Version, API Version, etc.
```
```

--------------------------------

### Implement Custom Console Output Formatting

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/overview.md

Extend the ConsoleWriter class to add custom formatting for console messages. This example demonstrates adding a 'custom' tag with a blue background to log messages.

```typescript
static customTag(message) {
    const tag = preferredChalk.bgBlue(' custom ');
    console.info.apply(this, prependLogTag(tag, message));
}
```

--------------------------------

### Power BI Visuals Certification Workflow

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/README.md

Follow this workflow to audit your visual for certification readiness, review and fix issues, and perform final builds. The `--verbose` flag provides detailed output during the process.

```bash
# Audit for certification readiness
pbiviz package --certification-audit --verbose

# Review issues
# Fix issues in code

# Auto-fix where possible
pbiviz package --certification-fix

# Re-audit
pbiviz package --certification-audit --verbose

# Final build
pbiviz package --no-minify --verbose
```

--------------------------------

### Generate Webpack Configuration

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/api-reference/WebPackWrap.md

Main entry point for generating webpack configuration. Orchestrates the entire webpack setup process, from loading configuration files to returning a ready-to-use webpack config object.

```typescript
async generateWebpackConfig(visualPackage: VisualManager, options?: WebpackOptions): Promise<object>
```

```typescript
const webpackWrap = new WebPackWrap();
const config = await webpackWrap.generateWebpackConfig(visualManager, {
    devMode: true,
    generateResources: true,
    generatePbiviz: false,
    minifyJS: false,
    minify: false,
    devServerPort: 8080,
    stats: true,
    skipApiCheck: false,
    allLocales: false,
    pbivizFile: 'pbiviz.json'
});

// config ready for webpack(config).run() or webpack-dev-server
```

--------------------------------

### CI/CD Integration for Power BI Visuals

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/README.md

Integrate Power BI Visuals Tools into your CI pipeline by installing the tools, dependencies, linting with auto-fix, and building the package for deployment. The output is typically found in the dist/ directory.

```bash
# In CI pipeline
npm install -g powerbi-visuals-tools
npm install

# Lint with auto-fix
pbiviz lint --fix

# Build package
pbiviz package \
  --no-minify \
  --verbose \
  --certification-audit

# Output: dist/myvisual.pbiviz
```

--------------------------------

### Test MCP Server Locally

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/MCP.md

Run the pbiviz MCP server locally from your visual project directory. This requires the path to the cloned PowerBI-visuals-tools repository.

```bash
# In your visual project directory:
node /path/to/PowerBI-visuals-tools/bin/pbiviz.js mcp
```

--------------------------------

### CommandManager.info

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/api-reference/CommandManager.md

Displays visual project information by reading and formatting the pbiviz.json configuration file.

```APIDOC
## CommandManager.info

### Description
Displays visual project information by reading and formatting the pbiviz.json configuration file.

### Method Signature
`static async info(rootPath: string): Promise<void>`

### Parameters
#### rootPath (`string`)
- Required - Project root directory.

### Returns
`Promise<void>` that resolves when info is displayed.

### Example
```typescript
await CommandManager.info(process.cwd());
```
```

--------------------------------

### Package Constructor

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/api-reference/Package.md

Initializes a new instance of the Package class. It takes the compiled source code, parsed capabilities, and visual feature type as arguments.

```APIDOC
## Package Constructor

### Description
Initializes a new instance of the Package class.

### Parameters
#### Path Parameters
- **sourceCode** (string) - Required - Compiled visual.js source code
- **capabilities** (object) - Required - Parsed capabilities.json
- **visualFeatureType** (VisualFeatureType) - Required - Feature flags from Visual class
```

--------------------------------

### prepareWebPackConfig

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/api-reference/WebPackWrap.md

Prepares a complete webpack configuration by assembling it from a base template and applying all necessary configurations.

```APIDOC
## prepareWebPackConfig

### Description
Prepares complete webpack configuration.

### Method Signature
```typescript
async prepareWebPackConfig(visualPackage: VisualManager, options: WebpackOptions, tsconfig: object): Promise<object>
```

### Parameters
- **visualPackage** (`VisualManager`): Visual manager instance.
- **options** (`WebpackOptions`): Build options.
- **tsconfig** (`object`): TypeScript configuration.

### Returns
- `Promise<object>`: A promise resolving to the complete webpack config object.

### Description
Assembles webpack config from base template, applies all configurations (mode, plugins, loaders, dev server, optimization), and returns final config.
```

--------------------------------

### Configure Dev Server with WebPackWrap

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/api-reference/WebPackWrap.md

Sets up the webpack dev server with HTTPS configuration. Requires a VisualManager instance and an optional port number.

```typescript
const webpackWrap = new WebPackWrap();
await webpackWrap.configureDevServer(visualManager, 8080);
// Server now configured for https://localhost:8080 with self-signed cert
```

--------------------------------

### createFolder

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/api-reference/utilities.md

Creates a directory with automatic parent directory creation. It uses fs-extra.ensureDirSync() and is safe to call on existing directories.

```APIDOC
## createFolder

### Description
Creates directory with automatic parent creation.

### Method
```typescript
function createFolder(folderName: string): string
```

### Parameters
#### Path Parameters
- **folderName** (string) - Required - Folder name or relative path

### Returns
`string` - Full path to created folder

### Description
Uses fs-extra.ensureDirSync() to create directory and parents if needed. Safe to call on existing directories.

### Example
```typescript
import { createFolder } from './utils.js';

const folder = createFolder('my-new-visual');
// Returns: ./my-new-visual
```
```

--------------------------------

### createVisualInstance

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/api-reference/VisualManager.md

Creates a Visual instance from the loaded configuration, used for feature type detection.

```APIDOC
## createVisualInstance

### Description
Reads capabilities.json and creates a Visual instance for feature type detection.

### Method
`async createVisualInstance(): Promise<void>`

### Returns
Promise that resolves when the instance is created.
```

--------------------------------

### Load Project Configuration Files

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/api-reference/utilities.md

Loads various configuration files for a Power BI visual project. Requires JSON files to be present in the root or visual directory.

```typescript
// Load tools config
const config = await readJsonFromRoot('config.json');

// Load visual config
const pbiviz = await readJsonFromVisual('pbiviz.json');
const capabilities = await readJsonFromVisual('capabilities.json');
const tsconfig = await readJsonFromVisual('tsconfig.json');
```

--------------------------------

### PowerBI Visuals Tools Architecture Diagram

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/overview.md

This diagram illustrates the layered architecture of the PowerBI Visuals Tools, showing the flow from the CLI entry point to the domain classes and tools.

```text
┌─────────────────────────────────────────────────┐
│          CLI Entry Point (pbiviz.js)             │
│          Commander.js Command Parser             │
└─────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────┐
│           CommandManager (Static)                │
│         Orchestrates all CLI commands            │
├─────────────────────────────────────────────────┤
│ start() | package() | lint() | new() | info()   │
│ installCert() | mcp() | mcpInit()               │
└─────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────┐
│            VisualManager (Instance)              │
│  Manages single visual project operations        │
├─────────────────────────────────────────────────┤
│ prepareVisual() | validateVisual() |            │
│ initializeWebpack() | startWebpackServer() |    │
│ generatePackage() | validatePackage()           │
└─────────────────────────────────────────────────┘
                        ↓
┌──────────────────────────────────────────────────────┐
│              Domain Classes & Tools                   │
├───────────────────────────────────────────────────────┤
│ Visual             - Configuration & metadata        │
│ Package            - Compiled code validation        │
│ FeatureManager     - Feature validation              │
│ WebPackWrap        - Webpack configuration           │
│ LintValidator      - ESLint integration              │
│ CertificateTools   - Certificate generation          │
│ ConsoleWriter      - Output formatting              │
│ VisualGenerator    - Project scaffolding              │
│ TemplateFetcher    - Template downloading            │
└───────────────────────────────────────────────────────┘
```

--------------------------------

### WebPackWrap Instance Methods

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/README.md

Instance methods for configuring and managing Webpack for Power BI visuals.

```typescript
WebPackWrap (instance methods)
├── generateWebpackConfig(visualPackage, options?) → Promise<object>
├── configureDevServer(visualPackage, port?) → Promise<void>
├── appendPlugins(options, visualPackage, tsconfig) → Promise<void>
├── configureLoaders(options) → Promise<void>
├── installAPIpackage() → Promise<boolean>
└── static prepareFoldersAndFiles(visualPackage) → Promise<void>
```

--------------------------------

### Initialize Webpack Configuration

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/api-reference/VisualManager.md

Prepares the webpack configuration for compilation, applying specified options such as development mode, source maps, and minification. It returns a Promise resolving to the VisualManager instance for chaining.

```typescript
await visualManager.initializeWebpack({
  devMode: true,
  devtool: 'eval-source-map',
  generateResources: true,
  generatePbiviz: false,
  minifyJS: false,
  minify: false,
  devServerPort: 8080,
  stats: true,
  skipApiCheck: false,
  allLocales: false,
  pbivizFile: 'pbiviz.json'
});
```

--------------------------------

### Build Pipeline Steps

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/overview.md

Details the build pipeline for Power BI visuals, from TypeScript source compilation to Webpack bundling and final artifact generation.

```plaintext
TypeScript source (src/*.ts)
        ↓
ts-loader (compiles to JS)
        ↓
Webpack bundling (combines modules)
        ↓
PowerBICustomVisualsWebpackPlugin
├─ Validates against API schema
├─ Generates visual.js
├─ Generates visual.css
├─ Generates pbiviz.json metadata
└─ Creates .pbiviz file
        ↓
drop/ folder (build artifacts)
        ↓
Package instance (post-build validation)
        ↓
Output: .pbiviz or resources folder
```

--------------------------------

### Package for Distribution Workflow

Source: https://github.com/microsoft/powerbi-visuals-tools/blob/main/_autodocs/overview.md

Outlines the process for packaging a Power BI visual for distribution, including linting, validation, Webpack configuration for production, and final package generation.

```text
pbiviz package [--minify] [--compression] [--certification-audit]
    ↓
CommandManager.package()
    ↓
VisualManager.prepareVisual()
    └─ Load configuration
    ↓
VisualManager.runLintValidation()
    └─ ESLint with auto-fix if enabled
    ↓
VisualManager.validateVisual()
    └─ Pre-build feature validation
    ↓
VisualManager.initializeWebpack()
    └─ Configure production build
    ↓
VisualManager.generatePackage()
    ├─ webpack compiler.run()
    ├─ Package.validate() (PostBuild)
    ├─ PowerBI webpack plugin generates pbiviz
    └─ Output drop/ folder or .pbiviz file
```