# CLI

> Install the Composables CLI and add app template flows, screens and components to your project from your terminal or coding agent.

> [!WARNING] Experimental
> The CLI is new and may change. Tell us what works, what doesn't and what you'd like it to do at [support@composables.com](mailto:support@composables.com).

## What is the Composables CLI?

The Composables CLI adds the app templates to your Jetpack Compose or Compose Multiplatform project from your terminal. Coding agents such as Claude Code, Codex, Cursor and Junie can run it too, so you can ask your agent to build your app from Pairel, Vela and Tally flows, screens and components.

The CLI searches the catalogue and writes the Kotlin source for the flows, screens and components you choose straight into your module.

## Install the CLI

On **macOS or Linux**, run in a terminal:

```sh
curl -fsSL https://composables.com/cli/install.sh | sh
```

On **Windows**, run in PowerShell:

```text
irm https://composables.com/cli/install.ps1 | iex
```

The installer downloads the latest release for your computer, verifies its checksum, and installs `composables` into `~/.composables/bin` (`%USERPROFILE%\.composables\bin` on Windows). It adds that folder to your `PATH`; open a new terminal afterward, then check the installation:

```sh
composables --version
```

Run the install command again at any time to update to the latest release.

## Set up your project

From your Gradle project, run:

```sh
composables init
```

This sets up your Android or Compose Multiplatform project:

- **Chooses the module** downloads go into, and saves it in `.composables/config.yml` so later commands don't ask again. If your project has more than one module, it asks which one, or pass `--module composeApp`.
- **Adds the libraries every template uses** to that module: Compose Unstyled, Ripple Indication, Google Fonts, System Bars and Compose URI Painter. Versions you already declare are kept, and if your build uses a version catalog, the libraries are added to `gradle/libs.versions.toml`. Sync Gradle afterward.

> [!NOTE]
> Downloading flows, screens and components needs you to sign in. A license is required to download more; [buy one here](https://composables.com/pricing.md).

It is okay to commit the `.composables` folder to your version control.

## Find flows, screens and components

Search the catalogue, then list a collection to see the exact IDs you can download:

```sh
composables search "sign in"
composables search apps "habit tracker"
composables list "tally/flows"
composables list "tally/screens"
composables list "tally/components"
```

## Add a flow to your app

A flow is a complete journey, such as onboarding, signing in or upgrading, taken from one app template. List an app's flows, then download one:

```sh
composables list "vela/flows"
composables get "vela/flows/logging-in"
```

You get every screen of the flow with the components and theme they use. Then see how to connect it to your app:

```sh
composables guide "vela/flows/logging-in"
```

The guide tells you, or your coding agent, where each screen's callbacks lead, which ones leave the flow for your app's own screens, which inputs to pass, and how to style the screens with your app's theme instead of the template's.

The screens take their colors, text styles and shapes from their theme, so passing your app's values restyles them without changing the screens. If your app uses Material 3, the guide includes the mapping to use.

## Add source to your project

Download a screen or component by its ID:

```sh
composables get "tally/screens/home"
composables get "tally/components/button"
composables get "tally/components"
```

Screens include the components, theme and supporting source they need, and `composables guide` works for them too. The Kotlin files go into your module's `src/commonMain/kotlin` for Compose Multiplatform or `src/main/kotlin` for Android, keeping their packages. Files you have changed are never replaced unless you add `--overwrite`. Use `--output ./folder` to save the source to a separate folder instead.

`get` never changes your build files. Some templates use an extra library, such as kotlinx-datetime in Tally; when your module doesn't declare one, `get` prints the line to add.

## Use it with a coding agent

Install the CLI and run `composables init` in your project yourself, then ask your agent:

> Use the Composables CLI to add a sign-in flow to our app. Keep our app's theme.

Agents learn the commands from `composables --help` and follow `composables guide` to connect what they download.

## Commands

Run `composables --help`, or `composables <command> --help`, to see these in your terminal.

### init

Sets up your project: chooses the module downloads go into and adds the libraries every template uses.

```sh
composables init
```

**Options**

```text
--module       Module directory for downloads, such as app or composeApp
--icons        Object that icons attach to, such as com.example.ui.AppIcons
               (default: com.composables.icons.Icons)
--project-dir  Project directory (default: .)
```

### login

Signs in through your browser with your Composables account. You stay signed in between commands.

```sh
composables login
```

### logout

Signs out of Composables on this computer.

```sh
composables logout
```

### search

Searches the app templates, including their flows, and the icons. Add `apps` or `icons` to search only one of them. Start an icon search with a library, such as `"lucide/arrow left"`, to search only that library. Results are JSON with the IDs to use with `list` and `get`.

```sh
composables search "sign in"
composables search apps "habit tracker"
composables search icons "lucide/arrow left"
```

**Options**

```text
--limit  Maximum results, from 1 to 100 (default: 20)
```

### list

Lists an app's flows, screens or components, or the icon libraries.

```sh
composables list "vela/flows"
composables list libraries
```

**Options**

```text
--limit  Maximum results, from 1 to 100 (default: 20)
--page   Page of results (default: 1)
```

### get

Downloads a flow, a screen, an app's components or an icon by its ID. Source goes into the module chosen by `init`. Files you have changed are kept unless you add `--overwrite`.

Icons go into the same module as Compose code, as extensions of an icons object, so you use them as `Icons.ArrowLeft`. The object is `com.composables.icons.Icons` unless you choose your own with `composables init --icons`, and it's created if it doesn't exist. Each icon library's license is saved next to the icons. Use `--format` for SVG, Android XML or JSON instead.

```sh
composables get "vela/flows/logging-in"
composables get "lucide/arrow-left"
composables get "lucide/arrow-left" --format svg --output arrow.svg
```

**Options**

```text
--module       Module directory, such as app or composeApp
--project-dir  Gradle project directory (default: .)
-o, --output   Save to a separate file or folder instead of your module
--overwrite    Replace files that changed in your module
-f, --format   Icon format: compose, svg, android or json (default: compose)
--variant      Icon style ID returned by search
```

### guide

Shows how to connect a flow or screen to your app: where each callback leads, which inputs to pass, what to rebrand and how to match your app's theme.

```sh
composables guide "vela/flows/logging-in"
```