# CLI Reference

All Frakment commands, flags, and registry format.

> For the complete documentation index, see [llms.txt](/llms.txt). Markdown variants are available by appending `.md` to any URL or sending an `Accept: text/markdown` header. An agent skill is available at [/.well-known/agent-skills/site-skill.md](/.well-known/agent-skills/site-skill.md).

Complete reference for the `frakment` CLI. New to Frakment? Start with [Installation](/docs/getting-started/installation) first — this page assumes the project is already bootstrapped.

## Commands [#commands]

| Command                | Description                                                                                                                                  |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `frakment init`        | Bootstrap the project: write `components.json`, inject the theme block into `globals.css`, create `lib/utils.ts`, install base dependencies. Pass `--expo` for an Expo + NativeWind project. |
| `frakment add <name…>` | Fetch one or more components (plus `registryDependencies` recursively), write files, install missing npm deps. Pass `--expo` to fetch from the Expo registry. |
| `frakment list`        | List all components exposed by the configured registry.                                                                                      |

## Flags [#flags]

### `frakment init` [#frakment-init]

<PropsTable rows={[{"name":"--expo","type":"boolean","defaultValue":"false","description":"Bootstrap an Expo + NativeWind project. Writes components.json with platform set to expo and registries.expo, copies lib/utils.ts and lib/theme.ts, and installs base dependencies with npx expo install."}]} />

### `frakment add` [#frakment-add]

<PropsTable rows={[{"name":"--dry-run","type":"boolean","defaultValue":"false","description":"Show planned files and dependencies without changing the project."},{"name":"--registry <url>","type":"string","defaultValue":"from components.json","description":"Override the registry URL for this run."},{"name":"--expo","type":"boolean","defaultValue":"false","description":"Fetch from registries.expo and install dependencies with npx expo install."},{"name":"--skip-dependencies","type":"boolean","defaultValue":"false","description":"Write component files without installing missing npm dependencies."},{"name":"--overwrite","type":"boolean","defaultValue":"false","description":"Overwrite existing files without prompting."}]} />

<Callout type="info" title="Multiple components">
Pass several names in one call — dependencies are deduplicated across the
batch. Example: `npx frakment@latest add button card badge`.
</Callout>

### `frakment list` [#frakment-list]

No flags. Reads `registry` from `components.json` and prints every available component name with a one-line description.

## Registry resolution [#registry-resolution]

During `init`, the CLI writes a `registry` field to `components.json`. `add` and `list` read from it by default.

### `registries.expo` [#registriesexpo]

`init --expo` writes a `registries` map that keeps web and Expo URLs side by side:

```json title="components.json"
{
  "registries": {
    "web": "https://www.arrafi.dev/frakment/r",
    "expo": "https://www.arrafi.dev/frakment/r/expo"
  }
}
```

`add --expo` reads `registries.expo`. `add` without the flag reads `registries.web`, falling back to `registry`. The `--registry <url>` flag overrides both.
### Registry entry format [#registry-entry-format]

Each component lives at `<registry-url>/r/<name>.json`:

```json title="r/button.json"
{
  "name": "button",
  "dependencies": ["class-variance-authority", "radix-ui"],
  "registryDependencies": [],
  "files": [{ "path": "components/ui/button.tsx", "content": "..." }]
}
```

`registryDependencies` are resolved recursively before any files are written. Install order: deepest dependency first.

## Idempotency [#idempotency]

`init` is safe to re-run. Existing `components.json` is preserved unless overwritten. The theme marker block (`/* ==== FRAKMENT THEME START/END ==== */`) is replaced in place — no duplicates. Legacy inline theme blocks are auto-migrated.

## Troubleshooting [#troubleshooting]

Specific errors (Tailwind v4 requirement, missing `globals.css`, `src/` layout) are documented in [Installation → Troubleshooting](/docs/getting-started/installation#troubleshooting).

## License [#license]

MIT licensed. Free for personal, educational, and commercial use.