CLI Basics

Learn how to use dial-cli to generate schemas from your TypeScript code.

Installation

npm install -g @vuer-ai/dial-cli

Basic Commands

Generate Schema from Single File

dial-cli MyComponent.tsx

This creates ./metadata/schema.dial by default.

Specify Output Directory

dial-cli MyComponent.tsx -o ./my-schemas

Process Multiple Files

# Multiple files
dial-cli Component1.tsx Component2.tsx Component3.tsx

# Using glob patterns
dial-cli src/components/**/*.tsx

Command Options

How It Works

1. Parse - The CLI parses your TypeScript files
2. Extract - Finds all @dial annotations in JSDoc comments
3. Generate - Creates schema objects for each component
4. Write - Saves schemas to .dial files

Example Workflow

1. Write Your Component

// Button.tsx
interface ButtonProps {
  /**
   * Button text
   * @dial content
   * @dial-dtype string
   */
  label: string;

  /**
   * Button size
   * @dial appearance
   * @dial-dtype select
   * @dial-options ["small", "medium", "large"]
   */
  size: string;

  /**
   * Primary style
   * @dial appearance
   * @dial-dtype boolean
   */
  primary: boolean;
}

export const Button: React.FC<ButtonProps> = (props) => {
  // Component implementation
};

2. Run the CLI

dial-cli Button.tsx -o ./schemas

3. Generated Schema

// schemas/schema.dial
[
  {
    "component": "Button",
    "schemas": [
      {
        "name": "label",
        "dtype": "string",
        "grouping": "content"
      },
      {
        "name": "size",
        "dtype": "select",
        "options": ["small", "medium", "large"],
        "grouping": "appearance"
      },
      {
        "name": "primary",
        "dtype": "boolean",
        "grouping": "appearance"
      }
    ],
    "groups": [
      { "name": "content" },
      { "name": "appearance" }
    ]
  }
]

4. Use in Your App

import schemas from './schemas/schema.dial';
import { DialProvider, DialPanel } from '@vuer-ai/vuer-uikit';

function App() {
  return (
    <DialProvider schemas={schemas[0].schemas}>
      <DialPanel schemas={schemas[0].schemas} />
    </DialProvider>
  );
}

Ignoring Properties

Using --ignore Flag

# Ignore specific properties
dial-cli Component.tsx --ignore "className,style,children"

# Ignore with patterns
dial-cli Component.tsx --ignore "on*,_*"

Using @dial-ignore Annotation

interface Props {
  /** @dial appearance */
  color: string;

  /** @dial-ignore */
  _internalState: any;  // Won't appear in schema
}

Type Support

The CLI supports:

• ✅ Basic types (boolean, number, string)
• ✅ Arrays and tuples
• ✅ Unions and enums
• ✅ Interface inheritance
• ✅ Type intersections
• ✅ Utility types (Pick, Omit, Partial)
• ✅ Cross-file imports

Debugging

Verbose Mode

dial-cli Component.tsx --verbose

Shows:

• Files being processed
• Types being resolved
• Annotations found
• Schema generation details

Debug Output

With --verbose, a debug file is created:

metadata/
├── schema.dial                    # Generated schema
└── ComponentName-debug.json       # Debug information (with --verbose)

The debug file contains:

• rawComponent - Phase 1 component parsing output
• properties - Phase 2 property processing output
• schema - Final generated schema

Common Patterns

NPM Scripts

Add to your package.json:

{
  "scripts": {
    "dial": "dial-cli src/**/*.tsx -o ./schemas",
    "dial:watch": "nodemon --watch src --ext tsx --exec 'npm run dial'",
    "dial:clean": "rm -rf ./schemas"
  }
}

CI/CD Integration

# GitHub Actions example
- name: Generate Dial Schemas
  run: |
    npm install -g @vuer-ai/dial-cli
    dial-cli src/**/*.tsx -o ./schemas --quiet

Pre-commit Hook

// package.json
{
  "husky": {
    "hooks": {
      "pre-commit": "dial-cli src/**/*.tsx -o ./schemas"
    }
  }
}

Performance Tips

1. Use --ignore to skip unnecessary properties
2. Process files in batches for large projects
3. Use --quiet in production builds
4. Cache schemas when possible

Troubleshooting

"Command not found"

# Check installation
npm list -g @vuer-ai/dial-cli

# Reinstall if needed
npm install -g @vuer-ai/dial-cli

Properties Missing

Ensure properties have at least one @dial annotation:

// ❌ Won't appear
/** Regular comment */
name: string;

// ✅ Will appear
/** @dial content */
name: string;

Wrong Types Inferred

Use explicit @dial-dtype:

/** @dial appearance @dial-dtype color */
backgroundColor: string;  // Ensures color picker, not text input

Next Steps