# LiveStore CLI

The LiveStore CLI provides tools for creating new projects and integrating with AI assistants through MCP (Model Context Protocol).

:::caution[Experimental - Not Production Ready]
The LiveStore CLI is an experimental preview and not ready for production use. APIs, commands, and functionality may change significantly. Use for development and evaluation purposes only.
:::

## Installation

You can use the LiveStore CLI in several ways:

```bash
# Recommended: Use bunx (no installation needed)
bunx @livestore/cli --help

# Alternative options:
npm install -g @livestore/cli        # Global install
npm install -D @livestore/cli        # Project install
npx @livestore/cli --help            # Use with npx
```

## Commands

### `livestore new-project`
Create a new LiveStore project from available examples.

```bash
# Interactive selection
livestore new-project

# Specify example and path
livestore new-project --example web-todomvc my-project

# Use specific branch
livestore new-project --branch dev
```

### `livestore mcp`
MCP server tools for AI assistant integration. See [MCP Integration](/building-with-livestore/tools/mcp) for details.

```bash
# Start MCP server
livestore mcp

# Available subcommands
livestore mcp coach    # AI coaching assistant (requires API key env var)
livestore mcp tools    # Development tools server

# Coach command requires API key - check implementation for specific variable name
# Example: OPENAI_API_KEY=your_key livestore mcp coach
```

### `livestore sync`

Import and export events from the sync backend. Useful for backup, migration, and debugging.

#### Export

Export all events from the sync backend to a JSON file:

```bash
livestore sync export \
  --config livestore-cli.config.ts \
  --store-id my-store \
  events.json
```

**Example output:**

```
Exporting events from LiveStore...
   Config: livestore-cli.config.ts
   Store ID: my-store
   Output: events.json

Connecting to sync backend...
✓ Connected to sync backend: @livestore/cf-sync
Pulling events from sync backend...
Pulled 127 events
Exported 127 events to /path/to/events.json
```

**Options:**
- `--config, -c` (required) - Path to a config module that exports `schema` and `syncBackend`
- `--store-id, -i` (required) - Store identifier
- `--client-id` - Client identifier for the sync connection (default: `cli-export`)
- Large exports load data in memory; for very large stores run this on a machine with sufficient RAM.

#### Import

Import events from a JSON file to the sync backend:

```bash
livestore sync import \
  --config livestore-cli.config.ts \
  --store-id my-store \
  events.json
```

**Example output:**

```
Importing events to LiveStore...
   Config: livestore-cli.config.ts
   Store ID: my-store
   Input: events.json

Reading import file...
Found 127 events in export file
Checking for existing events...
Connecting to sync backend...
✓ Connected to sync backend: @livestore/cf-sync
Pushing events to sync backend...
  Pushed 100/127 events
  Pushed 127/127 events
Successfully imported 127 events
```

**Options:**
- `--config, -c` (required) - Path to a config module that exports `schema` and `syncBackend`
- `--store-id, -i` (required) - Store identifier
- `--client-id` - Client identifier for the sync connection (default: `cli-import`)
- `--force, -f` - Force import even if store ID in the file doesn't match
- `--dry-run` - Validate the import file without actually importing
- Large imports are memory-intensive because the JSON is loaded fully before validation/push.

**Note:** The sync backend must be empty when importing. The import will fail if events already exist.

### Config file

Both MCP and sync commands require a config file (conventionally named `livestore-cli.config.ts`) that exports:


## `reference/cli/config.ts`

```ts filename="reference/cli/config.ts"
import { makeWsSync } from '@livestore/sync-cf/client'

// Re-export your app's schema (adjust path to your project)
export { schema } from './schema.ts'

// Provide a sync backend constructor
export const syncBackend = makeWsSync({
  url: process.env.LIVESTORE_SYNC_URL ?? 'ws://localhost:8787',
})

// Optionally, pass an auth payload (must be JSON-serializable)
export const syncPayload = {
  authToken: process.env.LIVESTORE_SYNC_AUTH_TOKEN,
}
```

### `reference/cli/schema.ts`

```ts filename="reference/cli/schema.ts"
import { makeSchema, State } from '@livestore/livestore'

const events = {}

const tables = {
  todos: State.SQLite.table({
    name: 'todos',
    columns: {
      id: State.SQLite.text({ primaryKey: true }),
      text: State.SQLite.text(),
      completed: State.SQLite.boolean({ default: false }),
    },
  }),
}

const state = State.SQLite.makeState({ tables, materializers: {} })

export const schema = makeSchema({ events, state })
```

## Global options

- `--verbose` - Enable verbose logging
- `--help` - Show command help