API Reference

Complete reference for using shadcnai programmatically in your applications.

CLI Commands

`theme` Command

Generate a shadcn/ui theme based on a description.

shadcnai theme <description> [options]

Parameters

`<description>` (required)

Type: string
Description: Text description of the desired theme
Examples:
- "dark theme with purple accents"
- "professional banking app with trustworthy colors"
- "cyberpunk aesthetic with neon highlights"

Options

`--model`, `-m`

Type: string
Default: gemini-1.5-flash
Choices: See Models for complete list
Description: AI model to use for generation

shadcnai theme "ocean theme" --model gpt-4.1

`--temperature`, `-t`

Type: number
Default: 0.7
Range: 0.0 to 2.0
Description: Controls creativity vs consistency

shadcnai theme "creative theme" --temperature 1.2

`--save`, `--no-save`

Type: boolean
Default: true
Description: Whether to save generated files to disk

shadcnai theme "preview theme" --no-save

`--import`, `--no-import`

Type: boolean
Default: true
Description: Auto-import theme using shadcn CLI

shadcnai theme "test theme" --no-import

`--output`, `-o`

Type: string
Default: Current directory
Description: Output directory for saved files

shadcnai theme "custom theme" --output ./themes

`--packageManager`, `--pm`

Type: string
Default: npm
Choices: npm, yarn, pnpm, bun
Description: Package manager for auto-import

shadcnai theme "theme" --pm pnpm

Environment Variables

Required API Keys

Set API keys for the AI providers you want to use:

# Google AI (default model)
export GOOGLE_GENERATIVE_AI_API_KEY=your-key

# OpenAI
export OPENAI_API_KEY=your-key

# Anthropic
export ANTHROPIC_API_KEY=your-key

# xAI
export XAI_API_KEY=your-key

# DeepSeek
export DEEPSEEK_API_KEY=your-key

# Mistral
export MISTRAL_API_KEY=your-key

# Cerebras
export CEREBRAS_API_KEY=your-key

Optional Configuration

# Default model (overrides built-in default)
export SHADCNAI_DEFAULT_MODEL=claude-3-5-sonnet-20241022

# Default temperature
export SHADCNAI_DEFAULT_TEMPERATURE=0.8

# Default package manager
export SHADCNAI_DEFAULT_PM=pnpm

Output Format

Generated Files

When --save is enabled (default), shadcnai creates these files:

`theme.json`

Complete shadcn/ui theme configuration:

{
  "name": "ocean-sunset",
  "displayName": "Ocean Sunset",
  "colors": {
    "light": {
      "background": "0 0% 100%",
      "foreground": "224 71.4% 4.1%",
      "primary": "221.2 83.2% 53.3%",
      "primary-foreground": "210 40% 98%"
      // ... more color variables
    },
    "dark": {
      "background": "224 71.4% 4.1%",
      "foreground": "210 40% 98%",
      "primary": "217.2 91.2% 59.8%",
      "primary-foreground": "222.2 84% 4.9%"
      // ... more color variables
    }
  },
  "radius": "0.5rem",
  "shadows": {
    "shadowXs": "0 1px 2px 0 rgb(0 0 0 / 0.05)",
    "shadowSm": "0 1px 3px 0 rgb(0 0 0 / 0.1)"
    // ... more shadow definitions
  }
}

`theme.css`

Ready-to-use CSS variables:

@layer base {
  :root {
    --background: 0 0% 100%;
    --foreground: 224 71.4% 4.1%;
    --primary: 221.2 83.2% 53.3%;
    --primary-foreground: 210 40% 98%;
    /* ... more variables */
  }

  .dark {
    --background: 224 71.4% 4.1%;
    --foreground: 210 40% 98%;
    --primary: 217.2 91.2% 59.8%;
    --primary-foreground: 222.2 84% 4.9%;
    /* ... more variables */
  }
}

`README.md`

Theme documentation with usage instructions.

Terminal Output

When --no-save is used, themes are displayed in the terminal:

┌─────────────────────────────────────────────┐
│                Ocean Sunset                 │
├─────────────────────────────────────────────┤
│ Primary: #3b82f6 (Blue)                     │
│ Secondary: #f59e0b (Amber)                  │
│ Background: #ffffff (White)                 │
│ ... (formatted color palette)              │
└─────────────────────────────────────────────┘

Type Definitions

Theme Structure

interface Theme {
  name: string; // kebab-case identifier
  displayName: string; // human-readable name
  colors: {
    light: ColorVariables;
    dark: ColorVariables;
  };
  radius: string; // border radius (e.g., "0.5rem")
  shadows: ShadowsDefinition;
}

interface ColorVariables {
  background: string; // RGB format
  foreground: string;
  card: string;
  "card-foreground": string;
  popover: string;
  "popover-foreground": string;
  primary: string;
  "primary-foreground": string;
  secondary: string;
  "secondary-foreground": string;
  muted: string;
  "muted-foreground": string;
  accent: string;
  "accent-foreground": string;
  destructive: string;
  "destructive-foreground": string;
  border: string;
  input: string;
  ring: string;
  "chart-1": string;
  "chart-2": string;
  "chart-3": string;
  "chart-4": string;
  "chart-5": string;
  sidebar: string;
  "sidebar-foreground": string;
  "sidebar-primary": string;
  "sidebar-primary-foreground": string;
  "sidebar-accent": string;
  "sidebar-accent-foreground": string;
  "sidebar-border": string;
  "sidebar-ring": string;
}

interface ShadowsDefinition {
  shadow2xs: string;
  shadowXs: string;
  shadowSm: string;
  shadow: string;
  shadowMd: string;
  shadowLg: string;
  shadowXl: string;
  shadow2xl: string;
}

Exit Codes

shadcnai returns different exit codes for different scenarios:

0: Success
1: General error (invalid input, API failure, etc.)
2: Missing API key for selected model
3: Invalid model specified
4: File system error (permissions, disk space, etc.)
5: Network error (API unavailable)

Error Handling

Common Errors

Missing API Key

Error: Missing API key for model 'gpt-4.1'
Please set OPENAI_API_KEY environment variable

Solution: Set the required environment variable

Invalid Model

Error: Invalid model "invalid-model"
Supported models: gemini-1.5-flash, gpt-4.1, claude-3-5-sonnet-20241022, ...

Solution: Use a valid model from the supported list

API Rate Limiting

Error: API rate limit exceeded. Please try again later.

Solution: Wait and retry, or switch to a different model

Network Issues

Error: Network error - unable to reach AI provider

Solution: Check internet connection and API service status

Manual Import on Auto-Import Failure

If auto-import fails, shadcnai provides manual instructions:

Auto-import failed. To manually import this theme:

1. Copy the theme.json file to your project
2. Run: npx shadcn@latest add ./theme.json
3. Update your CSS variables as needed

Programmatic Usage

While shadcnai is primarily a CLI tool, you can integrate it into scripts:

Shell Scripts

#!/bin/bash
# Generate multiple themes for A/B testing

themes=(
  "professional finance app"
  "modern fintech startup"
  "traditional banking interface"
)

for theme in "${themes[@]}"; do
  mkdir -p "./themes/$(echo $theme | tr ' ' '-')"
  shadcnai theme "$theme" --no-import --output "./themes/$(echo $theme | tr ' ' '-')"
done

Node.js Integration

const { exec } = require("child_process");
const util = require("util");
const execAsync = util.promisify(exec);

async function generateTheme(description, options = {}) {
  const {
    model = "gemini-1.5-flash",
    temperature = 0.7,
    output = ".",
    save = true,
    autoImport = false,
  } = options;

  const cmd = [
    "shadcnai theme",
    `"${description}"`,
    `--model ${model}`,
    `--temperature ${temperature}`,
    `--output ${output}`,
    save ? "--save" : "--no-save",
    autoImport ? "--import" : "--no-import",
  ].join(" ");

  try {
    const { stdout, stderr } = await execAsync(cmd);
    return { success: true, output: stdout };
  } catch (error) {
    return { success: false, error: error.message };
  }
}

// Usage
generateTheme("dark theme with purple accents", {
  model: "gpt-4.1",
  output: "./themes",
  autoImport: false,
}).then((result) => {
  if (result.success) {
    console.log("Theme generated successfully");
  } else {
    console.error("Theme generation failed:", result.error);
  }
});

Python Integration

import subprocess
import json
import os

def generate_theme(description, **options):
    """Generate a theme using shadcnai CLI"""

    cmd = ['shadcnai', 'theme', description]

    # Add options
    if 'model' in options:
        cmd.extend(['--model', options['model']])
    if 'temperature' in options:
        cmd.extend(['--temperature', str(options['temperature'])])
    if 'output' in options:
        cmd.extend(['--output', options['output']])
    if not options.get('save', True):
        cmd.append('--no-save')
    if not options.get('auto_import', True):
        cmd.append('--no-import')

    try:
        result = subprocess.run(cmd,
                              capture_output=True,
                              text=True,
                              check=True)
        return {'success': True, 'output': result.stdout}
    except subprocess.CalledProcessError as e:
        return {'success': False, 'error': e.stderr}

# Usage
result = generate_theme(
    'ocean sunset theme',
    model='claude-3-5-sonnet-20241022',
    temperature=0.8,
    output='./themes',
    auto_import=False
)

if result['success']:
    print('Theme generated successfully')
else:
    print(f'Error: {result["error"]}')

Rate Limiting and Best Practices

API Rate Limits

Different providers have different rate limits:

Google AI: 60 requests per minute
OpenAI: Varies by plan
Anthropic: 60 requests per minute
Others: Check provider documentation

Best Practices

Batch Operations: Generate multiple themes in sequence with delays
Error Handling: Always handle API failures gracefully
Caching: Save generated themes to avoid regeneration
Model Selection: Choose appropriate models for your use case
Temperature Settings: Use consistent temperature for similar results

Next Steps

Ready to implement shadcnai in your workflow? Check out the Development guide for contributing to the project, or return to Usage for practical examples.