---
title: CLI | gluestack-ui | The Essential CLI Tool for UI Components
description: A powerful CLI tool for seamlessly adding gluestack-ui components to your React Native projects. Simplify your workflow with an intuitive CLI UI for fast development..
---
# CLI
The gluestack-ui CLI is a tool that simplifies integrating the gluestack-ui into your project. It provides commands for initialising and adding components to your project.
> Installation using gluestack-ui CLI in Expo projects supports for Expo SDK 50 and above. For Expo SDK < 49, please refer to the manual installation guide [here](https://gluestack.io/ui/docs/home/getting-started/installation).
- Currently we are working on support for Windows OS. For now, we recommend using the manual installation guide to avoid any issues.
## Init
Use init command to set up your project.
The init command adds the necessary `gluestack-ui.config.json` file, includes the `GluestackUIProvider` and essential components (`icon`, `overlay`, `toast`), installs dependencies, and configures above files for your project.
- `metro.config.js`
- `babel.config.js`
- `next.config.js` ( for Next.js)
- `tailwind.config.js`
- `global.css` (for Tailwind CSS)
- `ts.config.json`
- entry file (for your project)
> Note: If you wish to make changes to your project manually, you can refer to the [installation](/ui/docs/home/getting-started/installation) guide.
### Monorepo Example
Here's a complete workflow for setting up gluestack-ui in a monorepo:
```bash
# Navigate to your monorepo root
cd my-monorepo
# Initialize gluestack-ui in monorepo mode
npx gluestack-ui init --monorepo --path packages/ui
# The CLI will:
# 1. Prompt you to select a styling engine (NativeWind v5, UniWind, etc.)
# 2. Create GluestackUIProvider in packages/ui
# 3. Generate gluestack-ui.config.json at repo root:
# {
# "app": {
# "components": "packages/ui"
# }
# }
# 4. Install dependencies and update config files
# Later, add components
npx gluestack-ui add button --monorepo
# Or add all components
npx gluestack-ui add --all --monorepo
```
For non-interactive environments (CI/CD):
```bash
npx gluestack-ui init --monorepo --path packages/ui --nativewind-v5 -y
npx gluestack-ui add button --monorepo -y
```
### Options:
- `--path `: Specifies the directory path where you want to add the GluestackUIProvider component. By default, it creates the component in the `components/ui` directory within your project's root.
- `--monorepo`: When used in monorepo repositories, this flag switches the init flow to monorepo mode. In monorepo mode the CLI will treat the project as a shared component library (projectType: library) and will:
- Prompt to select or enter the components path where GluestackUIProvider and components should be written (e.g. `packages/ui`, `packages/components`, `apps/ui`).
- Generate a top-level `gluestack-ui.config.json` that points `app.components` to the chosen components path (relative to repo root).
- Add provider and core components into the chosen components path and update configs (tailwind, metro, tsconfig) appropriately.
- `--use-`: This flag specifies the package manager to use when initializing gluestack-ui. Supported options are npm (default), yarn, bun, and pnpm. Replace `` with your preferred package manager.
- `--nativewind`: Use NativeWind v4 (Tailwind CSS v3) as the styling engine. Useful for projects that need to stay on Tailwind v3.
- `--nativewind-v5`: Use NativeWind v5 (Tailwind CSS v4) as the styling engine. Note: NativeWind v5 is not yet web-compatible in monorepo mode; the CLI will fall back to NativeWind v4 in monorepo setups.
- `--uniwind`: Use UniWind (Tailwind CSS v4, Expo-only) as the styling engine. Note: UniWind is not supported for monorepo Next.js setups. In monorepo mode the CLI will fall back to NativeWind v4.
- `-y, --yes`: Answer yes to all prompts. Use this for non-interactive environments like CI/CD pipelines.
Path to add GluestackUIProvider, defaults to components/ui in the current directory. \n --monorepo Run init in monorepo/library mode and interactively choose components path. \n --use-npm Use npm as the package manager (default) \n --use-yarn Use yarn as the package manager \n --use-bun Use bun as the package manager \n --use-pnpm Use pnpm as the package manager \n --nativewind Use NativeWind v4 (Tailwind CSS v3) \n --nativewind-v5 Use NativeWind v5 (Tailwind CSS v4) \n --uniwind Use UniWind (Tailwind CSS v4, Expo-only) \n -y, --yes Answer yes to all prompts (non-interactive mode)`} language="bash" />
## Add
Use the `add` command to add components and their dependencies to your project:
### Options:
- `--all`: This flag can be used to add all available components from gluestack-ui to your project.
- `--path `: Specifies the directory path where you want to add the component. By default, it will add the component to the same directory where the GluestackUIProvider is located.
- `--monorepo`: When adding components into a monorepo, use --monorepo to enable monorepo-aware flows. With --monorepo the CLI will:
- Prompt you to select or enter the components path (e.g. `packages/ui`) if not provided via `--path`.
- Validate and write `gluestack-ui.config.json` at the repo root pointing to the selected components path.
- Ensure components are added into the chosen path rather than the repo root.
- `--use-`: Specifies the package manager to use. Supported options are npm (default), yarn, bun, and pnpm. Replace `` with your preferred package manager.
- `-y, --yes`: Answer yes to all prompts. Use this for non-interactive environments like CI/CD pipelines.
Path to add components, defaults to the directory where GluestackUIProvider is located. \n --monorepo Run add in monorepo mode and interactively choose components path. \n --use-npm Set npm as the project's package manager, default \n --use-yarn Set yarn as the project's package manager \n --use-bun Set bun as the project's package manager \n --use-pnpm Set pnpm as the project's package manager, currently not supported in react-native-cli projects. \n -y, --yes Answer yes to all prompts (non-interactive mode)`} language="bash" />
## Upgrade
Use the `upgrade` command to migrate your project's styling engine.
The upgrade command auto-detects your current gluestack-ui version and presents a prompt asking which styling engine you want to upgrade to:
```
◆ Which styling engine would you like to upgrade to?
│ ● NativeWind v5 (Tailwind CSS v4)
│ ○ UniWind (Tailwind CSS v4, Expo-only)
│ ○ Stay on current version
```
### NativeWind v5 upgrade path
Migrates from NativeWind v4 (Tailwind v3) to NativeWind v5 (Tailwind v4). The command will automatically:
1. Pin `lightningcss@1.30.1` in `package.json` overrides/resolutions
2. Replace `nativewind@^4.x` with `nativewind@^5.0.0-preview.4` and add `react-native-css`
3. Upgrade `tailwindcss` to v4 and add `@tailwindcss/postcss`
4. Rewrite `global.css` to Tailwind v4 format (with theme tokens)
5. Create `postcss.config.js`
6. Add `withNativewind` to `metro.config.js` (preserves existing options)
7. Prompt whether to delete `tailwind.config.js` (never auto-deleted — may contain custom tokens)
8. Create `react-native-css-env.d.ts`
> **After upgrading:** Re-add your components using `npx gluestack-ui@latest add ` to get the NativeWind v5 versions. Commit your changes first — re-adding will overwrite existing component files.
### UniWind upgrade path
Migrates from NativeWind v4 to UniWind (Tailwind v4, Expo-only). The command will automatically:
1. Replace `nativewind` with `uniwind`
2. Upgrade `tailwindcss` to v4
3. Rewrite `global.css` to UniWind / Tailwind v4 format
4. Update `metro.config.js` to use `withUniwindConfig`
5. Remove `nativewind/babel` entries from `babel.config.js`
6. Remove `tailwind.config.js` (Tailwind v4 is CSS-first)
7. Remove `nativewind-env.d.ts` and create `uniwind-types.d.ts`
> **After upgrading:** Re-add your components using `npx gluestack-ui@latest add ` to get the UniWind versions. Commit your changes first.
> **Note:** The upgrade command is not supported for Next.js projects.
## gluestack-ui.config.json
Configuration for your project.
The `gluestack-ui.config.json` file holds the configuration for your project. It helps the CLI understand how your project is set up and add components accordingly.
> Note : The gluestack-ui.config.json file is optional. It is only required if you use the CLI to add components to your project. If you prefer to manually copy and paste components, this file is not needed.
Manual creation of gluestack-ui.config.json file is not necessary. It will be automatically generated upon executing the following command:
### Monorepo Configuration
When using the `--monorepo` flag with `init` or `add` commands, the CLI generates a minimal configuration file at the repository root containing only the `app.components` field:
```json
{
"app": {
"components": "packages/ui"
}
}
```
This tells the CLI where to find and add components in your monorepo. Other configuration fields like `tailwind.config`, `tailwind.css`, and `app.entry` are not automatically generated in monorepo mode and should be added manually if needed.
## tailwind
### tailwind.config
Path to where your `tailwind.config.js` file is located.
```bash
{
"tailwind": {
"config": "tailwind.config.js",
}
}
```
### tailwind.css
Path to the CSS file (`global.css`) where Tailwind styles are likely imported into your project.
```bash
{
"tailwind": {
"css": "global.css"
}
}
```
## app
### app.entry
Path to your project's entry file
```bash
{
"app": {
"entry": "app/_layout.tsx",
}
}
```
### app.components
Specifies the directory path where the `GluestackUIProvider` component is located.
```bash
{
"app": {
"components": "components/ui",
}
}
```