> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/calcom/cal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# App Store CLI

> Command-line tools for building Cal.com apps

The App Store CLI provides tools for creating, editing, and managing Cal.com apps.

## Installation

The CLI is included in the Cal.com monorepo:

```bash theme={null}
cd packages/app-store-cli
yarn install
```

## Commands

### create

Create a new app in the app store.

```bash theme={null}
yarn cli create
```

#### Interactive Mode

Run without flags to use the interactive wizard:

```bash theme={null}
yarn cli create
```

You'll be prompted for:

* App name
* Description
* Category
* Publisher name
* Publisher email
* Template selection

#### Non-Interactive Mode

Provide all options as flags for automation:

```bash theme={null}
yarn cli create \
  --name "App Name" \
  --description "Short description" \
  --category <category> \
  --publisher "Your Name" \
  --email "email@example.com" \
  --template <template>
```

#### Options

<ParamField path="--name" type="string" required>
  App display name. The slug is automatically generated from this.
</ParamField>

<ParamField path="--description" type="string" required>
  Short description (recommended max 10 words). Longer descriptions go in `DESCRIPTION.md`.
</ParamField>

<ParamField path="--category" type="string" required>
  App category. Options:

  * `analytics` - Analytics and tracking
  * `automation` - AI & Automation
  * `calendar` - Calendar integrations
  * `conferencing` - Video conferencing
  * `crm` - CRM integrations
  * `messaging` - Messaging services
  * `payment` - Payment processing
  * `other` - Other apps
</ParamField>

<ParamField path="--publisher" type="string" default="Your Name">
  Publisher name or company
</ParamField>

<ParamField path="--email" type="string" default="email@example.com">
  Publisher contact email
</ParamField>

<ParamField path="--template" type="string" required>
  Template to use. Options:

  * `basic` - Minimal installable app
  * `event-type-app-card` - Event type configuration card
  * `booking-pages-tag` - Booking page tags/scripts
  * `event-type-location-video-static` - Static video location
  * `general-app-settings` - App settings interface
  * `link-as-an-app` - External link redirect
</ParamField>

<ParamField path="--external-link-url" type="string">
  Required when using `link-as-an-app` template. The external URL to redirect to.
</ParamField>

#### Example

```bash theme={null}
yarn cli create \
  --name "Acme CRM" \
  --description "Sync bookings with Acme CRM" \
  --category crm \
  --publisher "Acme Corp" \
  --email "support@acme.com" \
  --template basic
```

Output:

```
App created successfully!
Slug: acme-crm
App URL: http://localhost:3000/apps/acme-crm
Name: Acme CRM
Description: Sync bookings with Acme CRM
Category: crm

Next Step: Enable the app from http://localhost:3000/settings/admin/apps as an admin user.
```

### create-template

Create a new app template (for Cal.com core developers).

```bash theme={null}
yarn cli create-template
```

Templates are stored in `packages/app-store/templates/` and used as scaffolds for new apps.

<Info>
  Most developers should use `create`, not `create-template`. Templates are for creating reusable scaffolds.
</Info>

### edit

Edit an existing app's configuration.

```bash theme={null}
yarn cli edit --slug <app-slug>
```

#### Options

<ParamField path="--slug" type="string" required>
  The slug of the app to edit (matches the directory name)
</ParamField>

#### Example

```bash theme={null}
yarn cli edit --slug acme-crm
```

The interactive wizard will pre-fill existing values and allow you to modify:

* App name
* Description
* Category
* Publisher
* Email
* Template

<Warning>
  Changing the slug will rename the app directory. Ensure no other processes are accessing the app files.
</Warning>

### edit-template

Edit an existing template.

```bash theme={null}
yarn cli edit-template --slug <template-slug>
```

### delete

Delete an app from the app store.

```bash theme={null}
yarn cli delete --slug <app-slug>
```

<Warning>
  This permanently deletes the app directory and all its contents. This action cannot be undone.
</Warning>

#### Options

<ParamField path="--slug" type="string" required>
  The slug of the app to delete
</ParamField>

#### Example

```bash theme={null}
yarn cli delete --slug acme-crm
```

### delete-template

Delete a template.

```bash theme={null}
yarn cli delete-template --slug <template-slug>
```

## Build Commands

The CLI includes build commands for generating app registry files.

### build

Generate app registry files once:

```bash theme={null}
yarn build
```

This generates:

* `apps.metadata.generated.ts`
* `apps.schemas.generated.ts`
* `apps.server.generated.ts`
* `apps.browser.generated.tsx`
* `calendar.services.generated.ts`
* `crm.apps.generated.ts`
* `payment.services.generated.ts`
* `video.adapters.generated.ts`
* `analytics.services.generated.ts`
* `redirect-apps.generated.ts`

### watch

Watch for changes and regenerate files automatically:

```bash theme={null}
yarn watch
```

Useful during development. The CLI watches for:

* New app directories
* Changes to `config.json` files
* Deleted app directories

<Tip>
  Run `yarn watch` in a separate terminal during development to automatically regenerate registry files.
</Tip>

## Package.json Scripts

The CLI package defines these scripts:

```json theme={null}
{
  "scripts": {
    "build": "ts-node --transpile-only src/build.ts",
    "cli": "ts-node --transpile-only src/cli.tsx",
    "watch": "ts-node --transpile-only src/build.ts --watch",
    "generate": "ts-node --transpile-only src/build.ts",
    "post-install": "yarn build"
  }
}
```

* `yarn build` - Generate registry files
* `yarn cli <command>` - Run CLI commands
* `yarn watch` - Watch mode
* `yarn generate` - Alias for build

## Slug Generation

The CLI automatically generates slugs from app names:

* Converts to lowercase
* Replaces non-alphanumeric characters with hyphens
* Example: "My Custom App" → "my-custom-app"

The slug is used as:

* Directory name in `packages/app-store/`
* App URL path: `/apps/<slug>`
* Package name: `@calcom/<slug>`
* App identifier in the database

## File Generation

The build process scans all app directories and generates registry files that:

1. **Import app metadata** from `config.json` or `_metadata.ts`
2. **Export app schemas** from `zod.ts`
3. **Register API handlers** from `api/index.ts`
4. **Map UI components** from `components/`
5. **Register services** from `lib/` (Calendar, CRM, Payment, Video, Analytics)

### Generation Process

```typescript theme={null}
// For each app directory:
app-store/
├── my-app/
│   ├── config.json          → apps.metadata.generated.ts
│   ├── zod.ts              → apps.schemas.generated.ts
│   ├── api/index.ts        → apps.server.generated.ts
│   ├── components/         → apps.browser.generated.tsx
│   └── lib/
│       ├── CalendarService.ts  → calendar.services.generated.ts
│       ├── CrmService.ts       → crm.apps.generated.ts
│       ├── PaymentService.ts   → payment.services.generated.ts
│       └── VideoApiAdapter.ts  → video.adapters.generated.ts
```

### E2E Mode

In E2E test mode (`NEXT_PUBLIC_IS_E2E=1`), calendar, video, and analytics services are disabled:

```typescript theme={null}
export const CalendarServiceMap = process.env.NEXT_PUBLIC_IS_E2E === '1' ? {} : {
  // ... calendar services
};
```

## Validation

The CLI validates:

* **Category** must be one of the valid categories
* **Template** must exist in `packages/app-store/templates/`
* **External link URL** required for `link-as-an-app` template
* **Config.json** must be valid JSON and match `AppMetaSchema`

## Templates

Templates are located in `packages/app-store/templates/`:

```
templates/
├── basic/
├── event-type-app-card/
├── booking-pages-tag/
├── event-type-location-video-static/
├── general-app-settings/
└── link-as-an-app/
```

Each template includes:

* `config.json` - Template metadata
* `package.json` - Dependencies
* `index.ts` - Exports
* `zod.ts` - Schemas
* `api/` - API handlers
* `components/` - UI components (if applicable)
* `static/icon.svg` - Placeholder icon

## Cross-Platform Support

The CLI supports Windows, macOS, and Linux:

* **Windows**: Uses `xcopy`, `move`, `mkdir`, `rd` commands
* **Unix**: Uses `cp`, `mv`, `mkdir`, `rm` commands

Platform detection is automatic based on `os.platform()`.

## Troubleshooting

### Command Not Found

Ensure you're in the correct directory:

```bash theme={null}
cd packages/app-store-cli
yarn cli create
```

### Invalid Template

List available templates:

```bash theme={null}
ls packages/app-store/templates/
```

### Invalid Category

Valid categories:

* analytics
* automation
* calendar
* conferencing
* crm
* messaging
* payment
* other

### App Not Appearing

After creating an app:

1. Run `yarn build` to regenerate registry files
2. Restart the dev server
3. Enable the app in `/settings/admin/apps`

### Directory Already Exists

The CLI won't overwrite existing apps. Use `edit` to modify an existing app or `delete` to remove it first.

## Advanced Usage

### CI/CD Integration

Use non-interactive mode in CI pipelines:

```bash theme={null}
yarn cli create \
  --name "$APP_NAME" \
  --description "$APP_DESCRIPTION" \
  --category "$APP_CATEGORY" \
  --publisher "$PUBLISHER_NAME" \
  --email "$PUBLISHER_EMAIL" \
  --template "$TEMPLATE_NAME"
```

### Scripting

Create multiple apps with a script:

```bash theme={null}
#!/bin/bash

apps=(
  "App One:Description 1:crm"
  "App Two:Description 2:payment"
)

for app in "${apps[@]}"; do
  IFS=':' read -r name desc category <<< "$app"
  yarn cli create \
    --name "$name" \
    --description "$desc" \
    --category "$category" \
    --template basic
done
```

### Custom Templates

Create your own templates:

1. Use `yarn cli create-template` to create a template
2. Customize the scaffold files
3. Use it with `--template your-template-name`

## Next Steps

<CardGroup cols={2}>
  <Card title="Build an App" icon="hammer" href="/developers/apps/build-an-app">
    Complete guide to building your first app
  </Card>

  <Card title="App Types" icon="layer-group" href="/developers/apps/app-types">
    Learn about different app service types
  </Card>

  <Card title="Source Code" icon="github" href="https://github.com/calcom/cal.com/tree/main/packages/app-store-cli">
    View the CLI source code
  </Card>
</CardGroup>