whatalo init

Create a new plugin project interactively — scaffolds files, registers the plugin, and shows your credentials.

Syntax

whatalo init [options]

Options

Flag	Type	Description
`--portal-url <url>`	string	Developer Portal URL

Interactive Flow

whatalo init is a guided 7-step wizard. You do not need to be logged in before running it — authentication is handled inline if needed.

Step 1 — Auth check

If you are not logged in, an inline Device Flow runs automatically. The same browser-based authentication used by whatalo login runs without leaving the wizard.

Step 2 — Plugin name

You are prompted to enter a name for your plugin (3–50 characters). The CLI auto-generates a URL-safe slug from the name (lowercase, hyphens only).

Step 3 — Template

Select a project template. Currently available:

React + Vite — TypeScript, Vite 7, React 19, @whatalo/plugin-sdk

Step 4 — Create or link

Option	What happens
Create new plugin	Registers a new plugin via `POST /api/plugins`
Link existing	Lists your existing plugins — pick one to link

Step 5 — Scaffold

Template files are copied to a new directory named after the slug. Handlebars variables are replaced:

Variable	Value
`{name}`	Plugin name you entered
`{slug}`	Auto-generated slug
`{clientId}`	Plugin ID from the portal
`{sdkVersion}`	Current `@whatalo/plugin-sdk` version

Step 6 — Install dependencies

Runs pnpm install (or the detected package manager from npm_config_user_agent).

Step 7 — Show secret

If a new plugin was created, the client secret is displayed once. This is the only time you will ever see it — it is stored as a hash in the portal and cannot be retrieved again.

  WHATALO_CLIENT_SECRET=wsk_live_xxxxxxxxxxxxxxxx

  Save this now — it will not be shown again.

Generated File Tree

my-plugin/
├── .env.example              # WHATALO_CLIENT_ID, WHATALO_CLIENT_SECRET
├── .gitignore
├── whatalo.app.ts            # defineApp() — manifest (permissions, pages, URLs)
├── whatalo.app.toml          # Project config (name, slug, plugin_id, build, dev port)
├── package.json              # react 19, vite 7, @whatalo/plugin-sdk
├── tsconfig.json
├── vite.config.ts            # allowedHosts: true, CORS headers for iframe
├── index.html
├── README.md
└── src/
    ├── main.tsx
    ├── app.tsx               # Page routing via switch(context.currentPage)
    ├── styles.css
    ├── pages/
    │   └── settings.tsx      # Educational Settings page with guidance
    ├── webhooks/
    │   └── verify.ts         # HMAC-SHA256 webhook verifier with replay protection
    └── components/
        └── whatalo-ui/       # 17 pre-built UI components + 2 hooks

Starting Development

After whatalo init completes:

cd my-plugin

# Copy credentials to .env
cp .env.example .env
# Add your WHATALO_CLIENT_SECRET to .env

# Start development
whatalo dev

Error Messages

Message	Cause
`Authentication failed. Please run 'whatalo login' and try again.`	Device Flow was cancelled or failed
`Plugin name is required.`	Empty name submitted
`Name must be at least 3 characters.`	Name is too short
`Name must not exceed 50 characters.`	Name is too long
`Directory "{slug}" already exists. Choose a different name.`	A folder with that slug already exists locally
`Failed to create plugin. Check that the slug is unique.`	The portal already has a plugin with that slug

whatalo dev — Start local development
whatalo validate — Validate the scaffolded project

On this page