App Store CLI - Cal.com

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

Installation

The CLI is included in the Cal.com monorepo:

cd packages/app-store-cli
yarn install

Commands

create

Create a new app in the app store.

yarn cli create

Interactive Mode

Run without flags to use the interactive wizard:

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:

yarn cli create \
  --name "App Name" \
  --description "Short description" \
  --category <category> \
  --publisher "Your Name" \
  --email "email@example.com" \
  --template <template>

Options

--name

string

required

App display name. The slug is automatically generated from this.

--description

string

required

Short description (recommended max 10 words). Longer descriptions go in DESCRIPTION.md.

--category

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

--publisher

string

default:"Your Name"

Publisher name or company

--email

string

default:"email@example.com"

Publisher contact email

--template

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

--external-link-url

string

Required when using link-as-an-app template. The external URL to redirect to.

Example

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).

yarn cli create-template

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

Most developers should use create, not create-template. Templates are for creating reusable scaffolds.

edit

Edit an existing app’s configuration.

yarn cli edit --slug <app-slug>

Options

--slug

string

required

The slug of the app to edit (matches the directory name)

Example

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

Changing the slug will rename the app directory. Ensure no other processes are accessing the app files.

edit-template

Edit an existing template.

yarn cli edit-template --slug <template-slug>

delete

Delete an app from the app store.

yarn cli delete --slug <app-slug>

This permanently deletes the app directory and all its contents. This action cannot be undone.

Options

--slug

string

required

The slug of the app to delete

Example

yarn cli delete --slug acme-crm

delete-template

Delete a template.

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:

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:

yarn watch

Useful during development. The CLI watches for:

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

Run yarn watch in a separate terminal during development to automatically regenerate registry files.

Package.json Scripts

The CLI package defines these scripts:

{
  "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:

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

Generation Process

// 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:

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:

cd packages/app-store-cli
yarn cli create

Invalid Template

List available templates:

ls packages/app-store/templates/

Invalid Category

Valid categories:

analytics
automation
calendar
conferencing
crm
messaging
payment
other

App Not Appearing

After creating an app:

Run yarn build to regenerate registry files
Restart the dev server
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:

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:

#!/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:

Use yarn cli create-template to create a template
Customize the scaffold files
Use it with --template your-template-name

Next Steps

Build an App

Complete guide to building your first app

App Types

Learn about different app service types

Source Code

View the CLI source code

Platform API

API Reference

Building Apps

Contributing

​Installation

​Commands

​create

​Interactive Mode

​Non-Interactive Mode

​Options

​Example

​create-template

​edit

​Options

​Example

​edit-template

​delete

​Options

​Example

​delete-template

​Build Commands

​build

​watch

​Package.json Scripts

​Slug Generation

​File Generation

​Generation Process

​E2E Mode

​Validation

​Templates

​Cross-Platform Support

​Troubleshooting

​Command Not Found

​Invalid Template

​Invalid Category

​App Not Appearing

​Directory Already Exists

​Advanced Usage

​CI/CD Integration

​Scripting

​Custom Templates

​Next Steps

Build an App

App Types

Source Code

Installation

Commands

create

Interactive Mode

Non-Interactive Mode

Options

Example

create-template

edit

Options

Example

edit-template

delete

Options

Example

delete-template

Build Commands

build

watch

Package.json Scripts

Slug Generation

File Generation

Generation Process

E2E Mode

Validation

Templates

Cross-Platform Support

Troubleshooting

Command Not Found

Invalid Template

Invalid Category

App Not Appearing

Directory Already Exists

Advanced Usage

CI/CD Integration

Scripting

Custom Templates

Next Steps