whatalo dev

Start local development with a live tunnel — your plugin appears in the Whatalo admin sidebar instantly.

Syntax

whatalo dev [options]

Options

Flag	Short	Type	Default	Description
`--store <slug>`	`-s`	string	cached	Dev store to connect to
`--tunnel-url <url>`	—	string	—	Use your own tunnel URL instead of cloudflared
`--no-tunnel`	—	boolean	—	Use localhost directly (no tunnel)
`--port <number>`	`-p`	string	from config	Override the local dev port
`--reset`	—	boolean	—	Force re-selection of dev store
`--verbose`	`-v`	boolean	—	Show dev server stdout/stderr
`--portal-url <url>`	—	string	—	Developer Portal URL

Startup Sequence

When you run whatalo dev, the following steps execute in order:

Read config — Loads whatalo.app.toml from the current directory (required)
Authenticate — Verifies session; runs auto-login if needed
Load manifest — Reads whatalo.app.ts via esbuild to extract your plugin's pages, permissions, and URLs
Select dev store — Uses --store flag → cached store → auto-select → interactive prompt
Start app server — Spawns the command defined in build.dev_command in your whatalo.app.toml; that command must expose the iframe frontend, /api/*, and /webhooks/whatalo on the same local origin
Create tunnel — Downloads and starts cloudflared automatically (unless --tunnel-url or --no-tunnel is set); extracts the *.trycloudflare.com URL
Register dev session — Sends a POST /api/dev-sessions with your manifest and tunnel URL
Show dev console — Prints all URLs and keyboard shortcuts

--portal-url changes which Developer Portal receives the dev-session registration. It does not change the preview host printed by the CLI.

Dev Console

Once running, the console shows:

  Plugin:   My Plugin
  Store:    my-dev-store
  Local:    http://localhost:5173
  Tunnel:   https://xxx.trycloudflare.com

  Press p to open preview, r to restart, q to quit

Keyboard shortcuts (TTY only)

Key	Action
`p`	Open preview URL in browser
`r`	Restart the dev server
`q` or `Ctrl+C`	Stop everything and clean up

Background Processes

While whatalo dev is running, three background tasks keep the session alive and in sync:

Task	Interval	What it does
Heartbeat	Every 30 minutes	`PATCH /api/dev-sessions/{id}` to keep the session alive
Config watcher	On file change	Reloads `whatalo.app.toml` when you save it
Manifest watcher	On file change	Reloads `whatalo.app.ts` and syncs changes to the portal (hot-reload)

Dev Session Details

A temporary plugin installation is created for your dev store with status: 'development'. This makes your plugin visible in the admin sidebar immediately, without going through the review process.

Property	Value
Session duration	Up to 8 hours
Absolute lifetime	72 hours
Sidebar visibility	Yes (`pinned_to_sidebar: true`)
Manifest `appUrl`	Set to your tunnel URL automatically
Manifest `webhookUrl`	Set to `{tunnelUrl}/webhooks/whatalo` automatically

The dev session is removed when you quit whatalo dev, which also removes the plugin from the sidebar.

whatalo dev uses a single-origin development pattern. The tunneled URL serves the iframe frontend and keeps browser requests such as /api/orders and /webhooks/whatalo on that same origin.

Tunnel Modes

Default — cloudflared (recommended)

cloudflared is downloaded automatically to ~/.whatalo/bin/cloudflared on first use. Supported platforms:

macOS (Intel and Apple Silicon)
Linux (x86-64 and ARM64)

Custom tunnel (`--tunnel-url`)

Use your own tunnel provider (ngrok, localtunnel, or any HTTPS URL):

whatalo dev --tunnel-url https://your-tunnel.example.com

No tunnel (`--no-tunnel`)

Uses localhost directly. The plugin will load in your browser, but the Whatalo admin (running on a different domain) cannot reach your iframe unless both are on the same machine.

whatalo dev --no-tunnel

Examples

Start with a specific dev store:

whatalo dev --store my-store-slug

Use a custom port and show dev server output:

whatalo dev --port 3000 --verbose

Use your own ngrok tunnel:

whatalo dev --tunnel-url https://abcd-1234.ngrok.io

Force re-select the dev store:

whatalo dev --reset

Cleanup on Exit

When you press q or Ctrl+C, whatalo dev performs a clean shutdown in order:

Clears the heartbeat interval
Closes file watchers
Sends DELETE /api/dev-sessions/{id} (removes plugin from sidebar)
Kills the tunnel process
Kills the dev server process

Error Messages

Message	Cause
`No whatalo.app.toml found. Run 'whatalo init' first.`	Command run outside a plugin project directory
`Port {port} is already in use.`	Another process is using the configured port
`Plugin "{slug}" was not found in your account.`	The plugin_id in `whatalo.app.toml` does not match your account
`No development stores found. Create one at {link}`	Your account has no dev stores
`Local server did not start. Check your 'build.dev_command' in whatalo.app.toml`	Dev server did not become ready within 30 seconds
`Tunnel failed to start.`	cloudflared could not establish a connection
Data Bridge returns `Insufficient permissions` or empty scopes	Restart `whatalo dev` so the development installation re-syncs `granted_scopes` from your manifest

whatalo init — Create a project first
whatalo validate — Validate before running
whatalo logs — View webhook delivery logs during development

On this page