fluentui-cli

---
name: fluentui-cli
description: 'Guides working with @fluentui/cli — the internal Fluent UI command-line tool. Use when asked to add a new CLI command, modify an existing command, understand CLI architecture, debug CLI issues, or work with the CLI build/test workflow. Covers: architecture overview, yargs conventions, lazy-loading pattern, testing, and available Nx generators.'
---

# `@fluentui/cli`

The `@fluentui/cli` package (`tools/cli/`) is the internal Fluent UI command-line tool built with **yargs**. It uses a modular, lazy-loading architecture where each command lives in its own directory and is only loaded at runtime when invoked.

## Architecture

### File Structure

```
tools/cli/
├── bin/fluentui-cli.js              # Node entry point (requires compiled output)
├── src/
│   ├── cli.ts                       # Main yargs setup, registers all commands
│   ├── index.ts                     # Public API re-exports
│   ├── utils/
│   │   ├── index.ts                 # Barrel exports
│   │   └── types.ts                 # Shared CommandHandler type
│   └── commands/
│       ├── metadata/                # API metadata command
│       │   ├── index.ts             # CommandModule definition
│       │   ├── handler.ts           # Lazy-loaded handler
│       │   └── impl/                # Parsing and formatting
│       └── report/                  # Reporting command group
│           ├── index.ts             # Registers report subcommands
│           ├── commands/            # info and usage definitions
│           └── impl/                # Lazy-loaded report implementations
```

### Lazy Loading Pattern

Command definitions (name, description, options builder) are eagerly imported — they are lightweight. The actual handler logic is **lazy-loaded via dynamic `import()`** only when the command is invoked:

```typescript
// index.ts — always loaded (lightweight)
handler: async argv => {
  // handler.ts only loaded when this specific command runs
  const { handler } = await import('./handler');
  return handler(argv);
},
```

This keeps command implementations out of the startup path until the selected command runs.

### CommandHandler Type

All handlers use the shared `CommandHandler<T>` type from `src/utils/types.ts`:

```typescript
import type { ArgumentsCamelCase } from 'yargs';

export type CommandHandler<T = {}> = (argv: ArgumentsCamelCase<T>) => Promise<void>;
```

### Command Registration in cli.ts

Each command is imported and registered in `tools/cli/src/cli.ts`:

```typescript
import yargs from 'yargs';
import reportCommand from './commands/report';
import metadataCommand from './commands/metadata';

export async function main(argv: string[]): Promise<void> {
  await yargs(argv)
    .scriptName('fluentui-cli')
    .usage('$0 <command> [options]')
    .command(reportCommand)
    .command(metadataCommand)
    .demandCommand(1, 'You need to specify a command to run.')
    .help()
    .strict()
    .parse();
}
```

## Build & Test

```sh
# Build the CLI
yarn nx run cli:build

# Run tests
yarn nx run cli:test

# Test --help output
node tools/cli/bin/fluentui-cli.js --help
node tools/cli/bin/fluentui-cli.js <command-name> --help
```

## Conventions

- **Always use the Nx generator** to scaffold new commands — do not create command files manually. See the [adding commands](references/adding-commands.md) reference.
- Place shared utilities in `tools/cli/src/utils/` and export through the barrel file.
- Every command must support `--help` (handled by yargs `.help()` in the builder).
- Handler files must export a named `handler` constant typed with `CommandHandler<T>`.
- Tests live adjacent to handlers as `handler.spec.ts`.

## Common Patterns

### Subcommands (nested commands)

If a command needs subcommands, use yargs nested command pattern in the builder:

```typescript
builder: yargs =>
  yargs
    .command('summary', 'Generate a summary', subBuilder => subBuilder, summaryHandler)
    .command('details', 'Generate detailed output', subBuilder => subBuilder, detailsHandler)
    .demandCommand(1)
    .help(),
```

• SKILL.md 4 KB
• references/adding-commands.md 3 KB