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

helios components [query] [options]

Arguments

query · string

Search query to filter components by name or description.

Options

--framework · string

Filter by framework: react, vue, svelte, solid, or vanilla. Short form: -f.

--all · boolean

Show all components, ignoring project framework. Short form: -a.

Examples

List all components for your framework:

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:

helios components fade

Shows only components matching “fade”.

Show all components regardless of framework:

helios components --all

Filter by specific framework:

helios components --framework vue

helios add

Add a component to your project.

Usage

helios add <component> [options]

Arguments

component · string · required

Name of the component to install.

Options

--no-install · boolean

Skip automatic dependency installation.

Examples

Add a component:

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:

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

helios list

Examples

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

helios update <component> [options]

Arguments

component · string · required

Name of the component to update.

Options

--yes · boolean

Skip confirmation prompt. Short form: -y.

--no-install · boolean

Skip automatic dependency installation.

Examples

Update a component:

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:

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

helios remove <component> [options]

Arguments

component · string · required

Name of the component to remove.

Options

--yes · boolean

Skip confirmation prompt. Short form: -y.

--keep-files · boolean

Remove from config but keep files on disk.

Examples

Remove a component:

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:

helios remove fade-in --keep-files

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

Remove without confirmation:

helios remove fade-in --yes

helios diff

Compare your local component files with the registry version.

Usage

helios diff <component>

Arguments

component · string · required

Name of the component to compare.

Examples

Check for differences:

helios diff fade-in

If there are no changes:

No differences found.

If there are changes:

--- 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:

helios diff fade-in
helios update fade-in

After customization:

helios diff fade-in  # See what you changed

Component workflow

Adding and using a component

# Browse available components
helios components

# Add a component
helios add fade-in

# Verify installation
helios list

Then use in your composition:

import { FadeIn } from './components/helios/fade-in';

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

Keeping components up to date

# Check for changes
helios diff fade-in

# Update if needed
helios update fade-in

Managing customized components

If you’ve customized a component:

# 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:

{
  "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 - Initialize a project with component support
• helios studio - Visual component browser and installer