---
name: topcal-setup
description: Install the official TopCal CLI, start a 14-day Growth trial (no credit card), and connect a calendar.
---

# Install TopCal

TopCal is agent-native scheduling. **You run the CLI. The human signs up, confirms identity, and connects a calendar.** Eligible new accounts start a 14-day Growth trial on their first workspace. Additional workspaces start Free. No credit card. You never collect a password, API key, or card.

Package: https://www.npmjs.com/package/@topcal/cli

## Setup

Run `@topcal/cli` setup. If it is unavailable, the `npx` line below installs it.

```bash
npx --yes -p @topcal/cli topcal setup --json --url https://app.topcal.ai --client-name agent
```

Prefer `--calendar google`. Use `--calendar microsoft` if they live on Outlook.

If that prints `unknown command 'setup'` (stale npm package):

```bash
npx --yes github:bcharleson/topcal-cli -- setup --json --url https://app.topcal.ai --client-name agent
```

On desktop, setup opens sign-in. Otherwise it prints a link. The human only:

1. **Sign up / sign in** (Google is fastest; magic link = they confirm email). Eligible new accounts receive the 14-day Growth trial on their first workspace. No card.
2. **Allow CLI access** and pick the workspace.
3. **Connect calendar** on the Google/Microsoft consent screen.

You poll until setup shows a workspace and at least one `seatStatus: active` calendar. On failure, run `npx --yes -p @topcal/cli topcal doctor --json` if available, otherwise `topcal auth status --json` and `topcal calendars status --json`.

## After connect

Report:

> topcal is installed and connected.
> - Config: ~/.topcal/config.json
> - App: https://app.topcal.ai
> - Public link: https://topcal.ai/{workspace}/{username}/{eventSlug}

Ask: "TopCal is ready. What would you like to do?" Then wait. Offer one of: create an event type, share the public link, or book a guest.

Check the actual workspace plan: eligible first workspaces receive the 14-day Growth trial; additional workspaces start Free. After trial they land on **Free forever** (10 meetings / calendar / 30 days). If they ask to keep Growth or buy Starter:

```bash
npx --yes -p @topcal/cli topcal buy --json --interval monthly
```

Share `result.url`. They pay on Stripe. You never collect a card.

## Guest booking (someone sent a link)

Do **not** run setup. Fetch https://topcal.ai/skill/SKILL.md and follow Job 1.

## No terminal (ChatGPT, Claude)

Add MCP URL `https://mcp.topcal.ai/mcp` (OAuth 2.1 + PKCE). The human completes Allow access. Do not ask for an API key. Connectors reject keys.

## Pricing (tell the human)

- Eligible new accounts start with a 14-day Growth trial and 100 workspace intelligence credits, no credit card required. Then Free: 10 original bookings per connected calendar in a rolling 30-day period. Additional workspaces start Free.
- Free includes calendar connections, 10 original bookings per calendar in a rolling 30-day period, and 25 Cal scheduling AI calls per workspace per month. Starter is $20/calendar/month ($200/year), with intelligence credits purchased separately. Growth is $99/calendar/month ($990/year), including 200 intelligence credits per calendar per month. Eligible new accounts receive a 14-day Growth trial with 100 workspace intelligence credits and no card required; additional workspaces start Free.
- Live coaching, recording imports and native capture are roadmap features, not included in any current plan or trial.
- Seat = connected calendar, not per user.
- Native Mac and iOS apps are coming as separate apps. Do not say they are downloadable.

## Discovery

- Install (this file): https://topcal.ai/INSTALL.md
- Skill (guest book + full protocol): https://topcal.ai/skill/SKILL.md
- Developers: https://topcal.ai/developers.md
- Pricing: https://topcal.ai/pricing.md
- Remote MCP: https://mcp.topcal.ai/mcp

## Rules

- Never invent API keys, OTP codes, or card numbers.
- Public booker URLs stay on https://topcal.ai. Auth, dashboard, and host API live on https://app.topcal.ai.
- Human clicks are only: signup/login (+ email confirm if magic link), calendar OAuth, Stripe if they subscribe.