# How to Add SXOUI Components Using the sxo add Command

> Learn to add SXOUI components to your project using the sxo add command. Effortlessly integrate UI elements from the basecoat library into your local src components directory.

- Repository: [Víctor García/sxo](https://github.com/gc-victor/sxo)
- Tags: how-to-guide
- Published: 2026-03-02

---

**The `sxo add` command pulls SXOUI components from the basecoat library into your local `src/components` directory by resolving CLI flags, fetching files from GitHub or a local fallback, and writing them to the configured destination.**

The `sxo` CLI provides a streamlined workflow for integrating pre-built UI components into your projects. According to the gc-victor/sxo source code, the `sxo add` command automates downloading and installing SXOUI components from the basecoat library. This guide explains the internal mechanics of flag resolution, configuration merging, and component installation based on the actual implementation in [`src/js/cli/commands/add.js`](https://github.com/gc-victor/sxo/blob/main/src/js/cli/commands/add.js).

## Understanding the sxo add Command Workflow

The `sxo add` command processes component requests through three distinct stages defined in [`src/js/cli/commands/add.js`](https://github.com/gc-victor/sxo/blob/main/src/js/cli/commands/add.js). The entry point `handleAddCommand` (lines 84-103) orchestrates the workflow: resolving the project root, ensuring the destination directory exists, invoking `addComponent`, and setting the appropriate exit code based on success or failure.

### Stage 1: Flag Handling and Configuration Setup

First, the command invokes `prepareFlags` from [`src/js/cli/cli-helpers.js`](https://github.com/gc-victor/sxo/blob/main/src/js/cli/cli-helpers.js) (lines 55-66). This utility extracts only the flags relevant to the `add` sub-command, including `--verbose`, `--color`, and `--components-dir`. It returns a clean `flagsForConfig` object alongside a map indicating which flags were explicitly passed by the user.

### Stage 2: Configuration Resolution

Next, `resolveConfig` in [`src/js/config.js`](https://github.com/gc-victor/sxo/blob/main/src/js/config.js) (lines 30-39) merges multiple configuration sources to determine the final environment. It combines default values, environment variables, settings from an optional `sxo.config.*` file, and the explicit CLI flags processed earlier. This resolution yields the definitive `componentsDir` path, defaulting to `src/components` if no override is specified.

### Stage 3: Component Download and Installation

Finally, the `addComponent` function (lines 18-33) handles the actual file operations. For each requested component, it attempts to fetch three file types—`.jsx`, [`.client.js`](https://github.com/gc-victor/sxo/blob/main/.client.js), and `.css`—from a remote GitHub raw URL. If the network request fails, it falls back to the local copy stored in the repository's `components/src/components` directory. Successfully retrieved files are written to the resolved `componentsDir`, with progress logged via `log.info` (lines 64-68). If none of the requested files are found, the command exits with a non-zero status and prints an error via `log.error` (lines 97-100).

## Running the sxo add Command

You can invoke the command directly from your terminal or integrate it programmatically into build pipelines.

### Basic Component Installation

To add a single component to your project, specify the component name after the `add` keyword:

```bash
sxo add button

```

This creates [`src/components/button.jsx`](https://github.com/gc-victor/sxo/blob/main/src/components/button.jsx), [`src/components/button.client.js`](https://github.com/gc-victor/sxo/blob/main/src/components/button.client.js), and [`src/components/button.css`](https://github.com/gc-victor/sxo/blob/main/src/components/button.css) assuming the default configuration.

### Advanced CLI Options

Override default behavior using explicit flags. The `--components-dir` flag changes the destination folder, while `--verbose` and `--no-color` control output formatting:

```bash
sxo add modal --components-dir custom/ui --no-color --verbose

```

### Programmatic Integration

For custom build scripts or automated workflows, import `handleAddCommand` directly from the source:

```javascript
import { handleAddCommand } from "./src/js/cli/commands/add.js";

await handleAddCommand("card", { verbose: true });

```

## Summary

- The **`sxo add`** command installs SXOUI components by processing CLI flags through `prepareFlags` in [`src/js/cli/cli-helpers.js`](https://github.com/gc-victor/sxo/blob/main/src/js/cli/cli-helpers.js), resolving configuration via [`src/js/config.js`](https://github.com/gc-victor/sxo/blob/main/src/js/config.js), and downloading files via `addComponent` in [`src/js/cli/commands/add.js`](https://github.com/gc-victor/sxo/blob/main/src/js/cli/commands/add.js).
- Components are fetched from remote GitHub URLs first, with a local fallback to `components/src/components` in the repository if network requests fail.
- The default installation directory is `src/components`, configurable via the `--components-dir` flag or `sxo.config.*` files.
- The command exits with a non-zero status code if it cannot locate any of the requested component files.

## Frequently Asked Questions

### What flags does the sxo add command support?

The command recognizes `--verbose` for detailed logging, `--color` / `--no-color` to toggle ANSI color output, and `--components-dir` to specify a custom destination path. These flags are processed by `prepareFlags` in [`src/js/cli/cli-helpers.js`](https://github.com/gc-victor/sxo/blob/main/src/js/cli/cli-helpers.js) (lines 55-66) before configuration resolution begins.

### Where does sxo add download components from?

By default, `addComponent` attempts to fetch files from a remote GitHub raw URL corresponding to the basecoat library. If the network request fails, it automatically falls back to the local copy stored in the repository's `components/src/components` directory, as implemented in [`src/js/cli/commands/add.js`](https://github.com/gc-victor/sxo/blob/main/src/js/cli/commands/add.js) (lines 18-33).

### Can I use sxo add programmatically in my own scripts?

Yes. Import `handleAddCommand` from [`src/js/cli/commands/add.js`](https://github.com/gc-victor/sxo/blob/main/src/js/cli/commands/add.js) and await its execution with the component name and an options object. This allows integration into custom build pipelines or automated setup scripts without invoking the CLI directly.

### What happens if a component download fails?

If `addComponent` cannot retrieve any of the required files (`.jsx`, [`.client.js`](https://github.com/gc-victor/sxo/blob/main/.client.js), or `.css`) from either the remote source or local fallback, it logs an error via `log.error` and sets `process.exitCode` to a non-zero value, causing the command to fail visibly (lines 97-100).