AsheeUI
CLI Reference

CLI Reference

AsheeUI ships a command-line interface for scaffolding, configuring, listing components, and diagnosing or repairing projects.

Installation

The CLI is published as @asheeui/cli and exposes the asheeui command. Add it as a dev dependency in your project, or run it on demand with npx:

pnpm add -D @asheeui/cli

Once installed, invoke it with npx:

bash
npx asheeui [command]

Command overview

CommandAliasesDescription
initiInitialize AsheeUI in your project (idempotent)
listls, lList all available AsheeUI components
doctordoc, drCheck your project for AsheeUI setup issues
fixfAutomatically repair issues found by doctor

Commands

init

Scaffolds AsheeUI in your project: creates the config file, installs dependencies, adds the style imports to your global CSS, and wraps your root layout.

This command is idempotent: running it multiple times safely checks for existing configuration before writing and will never duplicate code or imports.

bash
npx asheeui init
# Alias
npx asheeui i

Options

OptionTypeDescription
-t, --template <name>stringTemplate to use (default: "default")
--yesflagSkip interactive prompts and use defaults
-h, --helpflagShow help for command

Removed flag: The legacy --local flag (local monorepo workspace dependencies) was removed. Dependencies now resolve normally through your package manager.

What it does

  1. Detects your framework (Next.js, TanStack Start, or Vite + React)
  2. Checks for existing setup elements to prevent duplicate imports
  3. Creates asheeui.config.ts in your project root (skipped if one already exists)
  4. Safely appends @import "asheeui/styles" to your global CSS file if missing
  5. Wraps your root component with AsheeUIProvider and import the config
  6. Installs missing peer dependencies using your detected package manager (npm, pnpm, yarn, or bun)

Example

bash
# Interactive mode (default)
npx asheeui init

# Using the shorthand alias
npx asheeui i

# Skip all prompts
npx asheeui init --yes

list

Lists all available UI components directly from the asheeui library package (an installed copy, a local registry path, or the package source in this monorepo).

bash
npx asheeui list
# Aliases
npx asheeui ls
npx asheeui l

Options

OptionTypeDescription
-d, --dir <path>stringProject directory used to locate the asheeui package (default: current directory)
--path <path>stringPath to an asheeui package root or local registry folder
--jsonflagOutput the component list as JSON
-h, --helpflagShow help for command

Example

bash
npx asheeui ls

doctor

Checks your project for common AsheeUI configuration issues and provides diagnostic output.

bash
npx asheeui doctor
# Aliases
npx asheeui doc
npx asheeui dr

Options

OptionTypeDescription
-d, --dir <path>stringProject directory to scan (default: current directory)
-h, --helpflagShow help for command

What it checks

  • Config file existence (asheeui.config.ts or .js in the project root or src/)
  • Global CSS style import (@import "asheeui/styles")
  • Required peer dependencies (react, react-dom, tailwindcss, clsx, tailwind-merge)
  • AsheeUIProvider wrapping in the root entrypoint
  • Optional theme augmentation (AsheeThemeNameRegistry): informational

Example

bash
npx asheeui dr

fix

Automatically resolves and repairs setup issues detected by the doctor command.

bash
npx asheeui fix
# Alias
npx asheeui f

Options

OptionTypeDescription
-d, --dir <path>stringProject directory to fix (default: current directory)
--skip-installflagDo not run package-manager installs (only apply file changes)
-h, --helpflagShow help for command

What it fixes

  • Appends missing @import "asheeui/styles" to your global CSS (or creates src/index.css)
  • Generates a default asheeui.config.ts if missing
  • Wraps your root with AsheeUIProvider
  • Installs missing peer dependencies automatically with your detected package manager (--skip-install disables this)

Example

bash
npx asheeui f

Configuration file

The CLI creates asheeui.config.ts in your project root:

ts
import { type ExternalConfig } from "asheeui";


const config: ExternalConfig = {
  defaultTheme: "light",
  defaultVariant: "solid",
  defaultColor: "primary",
  components: {},
};


export default defineConfig(config);

See Configuration for all available options.

Troubleshooting

Running init multiple times

The CLI safely checks file contents and strings before applying changes. Running npx asheeui init multiple times will not duplicate CSS directives, plugin registrations, or configuration wrappers.

CLI fails to detect framework

Ensure you are running asheeui commands from your project root directory where package.json is located.

Configuration or style issues

If component styles are missing or provider errors occur:

  1. Run npx asheeui doctor to diagnose the issue.
  2. Run npx asheeui fix to automatically repair missing files or imports.
Previous

← Configuration

Next

Accordion →