> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/BintzGavin/helios/llms.txt
> Use this file to discover all available pages before exploring further.

# Component management

> Commands for managing Helios components

Helios provides a suite of commands for discovering, installing, and managing components from the component registry.

## Overview

The component management commands allow you to:

* **Browse** available components in the registry
* **Add** components to your project
* **List** installed components
* **Update** components to the latest version
* **Remove** components you no longer need
* **Diff** local changes against registry versions

## helios components

List and search available components in the registry.

### Usage

```bash theme={null}
helios components [query] [options]
```

### Arguments

<ParamField path="query" type="string" optional>
  Search query to filter components by name or description.
</ParamField>

### Options

<ParamField path="--framework" type="string">
  Filter by framework: `react`, `vue`, `svelte`, `solid`, or `vanilla`. Short form: `-f`.
</ParamField>

<ParamField path="--all" type="boolean">
  Show all components, ignoring project framework. Short form: `-a`.
</ParamField>

### Examples

**List all components for your framework:**

```bash theme={null}
helios components
```

Output:

```
Available components:
 - fade-in (component)
   Fade in animation effect
 - slide-in (component)
   Slide in from any direction
 - text-reveal (component)
   Animated text reveal effect
```

**Search for specific components:**

```bash theme={null}
helios components fade
```

Shows only components matching "fade".

**Show all components regardless of framework:**

```bash theme={null}
helios components --all
```

**Filter by specific framework:**

```bash theme={null}
helios components --framework vue
```

## helios add

Add a component to your project.

### Usage

```bash theme={null}
helios add <component> [options]
```

### Arguments

<ParamField path="component" type="string" required>
  Name of the component to install.
</ParamField>

### Options

<ParamField path="--no-install" type="boolean">
  Skip automatic dependency installation.
</ParamField>

### Examples

**Add a component:**

```bash theme={null}
helios add fade-in
```

Output:

```
Installing fade-in...
Copying files:
  ✓ src/components/helios/fade-in.tsx
  ✓ src/lib/utils.ts
Installing dependencies...
  + framer-motion@11.0.0
Successfully installed fade-in!
```

**Add without installing dependencies:**

```bash theme={null}
helios add slide-in --no-install
```

This copies component files but skips `npm install`.

### What happens when you add a component?

1. **Validation** - Checks if component exists in registry
2. **Framework check** - Verifies compatibility with your project
3. **File copying** - Downloads and copies component files to your project
4. **Dependency installation** - Installs required npm packages
5. **Config update** - Adds component to `helios.config.json`

## helios list

List components installed in your project.

### Usage

```bash theme={null}
helios list
```

### Examples

```bash theme={null}
helios list
```

Output:

```
Installed components:
 - fade-in
 - slide-in
 - text-reveal
```

If no components are installed:

```
No components installed yet. Use "helios add [component]" to install one.
```

## helios update

Update an installed component to the latest version.

### Usage

```bash theme={null}
helios update <component> [options]
```

### Arguments

<ParamField path="component" type="string" required>
  Name of the component to update.
</ParamField>

### Options

<ParamField path="--yes" type="boolean">
  Skip confirmation prompt. Short form: `-y`.
</ParamField>

<ParamField path="--no-install" type="boolean">
  Skip automatic dependency installation.
</ParamField>

### Examples

**Update a component:**

```bash theme={null}
helios update fade-in
```

Output:

```
This will overwrite changes in 'fade-in'. Continue? (y/N) y
Updating fade-in...
  ✓ Updated src/components/helios/fade-in.tsx
Successfully updated fade-in!
```

**Update without confirmation:**

```bash theme={null}
helios update fade-in --yes
```

### Warning

Updating overwrites local changes to the component. Use `helios diff` first to review changes.

## helios remove

Remove a component from your project.

### Usage

```bash theme={null}
helios remove <component> [options]
```

### Arguments

<ParamField path="component" type="string" required>
  Name of the component to remove.
</ParamField>

### Options

<ParamField path="--yes" type="boolean">
  Skip confirmation prompt. Short form: `-y`.
</ParamField>

<ParamField path="--keep-files" type="boolean">
  Remove from config but keep files on disk.
</ParamField>

### Examples

**Remove a component:**

```bash theme={null}
helios remove fade-in
```

Output:

```
The following files will be deleted:
- src/components/helios/fade-in.tsx

Are you sure you want to delete these files? (y/N) y
Removed fade-in from configuration
Deleted component files
```

**Remove from config only:**

```bash theme={null}
helios remove fade-in --keep-files
```

This removes the component from `helios.config.json` but leaves files untouched.

**Remove without confirmation:**

```bash theme={null}
helios remove fade-in --yes
```

## helios diff

Compare your local component files with the registry version.

### Usage

```bash theme={null}
helios diff <component>
```

### Arguments

<ParamField path="component" type="string" required>
  Name of the component to compare.
</ParamField>

### Examples

**Check for differences:**

```bash theme={null}
helios diff fade-in
```

If there are no changes:

```
No differences found.
```

If there are changes:

```diff theme={null}
--- fade-in.tsx	Registry
+++ fade-in.tsx	Local
@@ -10,7 +10,7 @@
   return (
-    <motion.div initial={{ opacity: 0 }} animate={{ opacity: 1 }}>
+    <motion.div initial={{ opacity: 0 }} animate={{ opacity: 1, scale: 1.1 }}>
       {children}
     </motion.div>
   );
```

### Use cases

**Before updating:**

```bash theme={null}
helios diff fade-in
helios update fade-in
```

**After customization:**

```bash theme={null}
helios diff fade-in  # See what you changed
```

## Component workflow

### Adding and using a component

```bash theme={null}
# Browse available components
helios components

# Add a component
helios add fade-in

# Verify installation
helios list
```

Then use in your composition:

```tsx theme={null}
import { FadeIn } from './components/helios/fade-in';

export function Composition() {
  return (
    <FadeIn duration={1000}>
      <h1>Hello World</h1>
    </FadeIn>
  );
}
```

### Keeping components up to date

```bash theme={null}
# Check for changes
helios diff fade-in

# Update if needed
helios update fade-in
```

### Managing customized components

If you've customized a component:

```bash theme={null}
# Review your changes
helios diff fade-in

# Keep your version (do nothing)
# OR merge updates manually
helios update fade-in  # This overwrites your changes
```

## Component ownership

Helios follows the Shadcn model:

* **Components are copied** into your project (not installed as npm packages)
* **You own the code** and can modify it freely
* **Updates are opt-in** - you control when to pull registry changes
* **No lock-in** - components are just source files in your repo

## Registry configuration

Customize the component registry in `helios.config.json`:

```json theme={null}
{
  "registry": "https://custom-registry.example.com",
  "framework": "react",
  "directories": {
    "components": "src/components/helios",
    "lib": "src/lib"
  },
  "components": ["fade-in", "slide-in"]
}
```

Components are installed to the directory specified in `directories.components`.

## See also

* [helios init](/api/cli-init) - Initialize a project with component support
* [helios studio](/api/cli-studio) - Visual component browser and installer