CLI Overview

Install and authenticate the Whatalo CLI — 14 commands for the full plugin development lifecycle.

Installation

Install the CLI globally with pnpm:

pnpm add -g @whatalo/cli

Or run a single command without a global install:

npx @whatalo/cli whatalo login

Verify the installation:

whatalo --version

Authentication

The CLI uses the RFC 8628 Device Authorization Grant flow. You never type your password into the terminal.

How it works

Run whatalo login
The CLI contacts the Developer Portal and receives a device code
Your browser opens automatically with a verification page
Approve the request in the browser
The CLI polls every 5 seconds until you approve
On success, tokens are saved to ~/.whatalo/session.json

Token lifecycle

Token	TTL	Behavior
Access token	1 hour	Auto-refreshed silently before expiry
Refresh token	30 days	Single-use rotation — a new refresh token is issued on every refresh

Session file permissions are enforced automatically: directory 700, file 600.

Portal URL Resolution

Every command resolves the Developer Portal URL in this priority order:

Priority	Source
1 (highest)	`--portal-url <url>` flag
2	`WHATALO_DEVELOPER_PORTAL_URL` environment variable
3 (default)	`http://localhost:3002`

Configuration Files

File	Location	Purpose
`whatalo.app.toml`	Project root	Project config — name, slug, build commands, dev port
`whatalo.app.ts`	Project root	Plugin manifest — permissions, URLs, admin pages
`~/.whatalo/session.json`	Home directory	Auth tokens (auto-managed, never edit manually)
`.whatalo/dev-store.json`	Project root	Cached dev store selection

On every command invocation the CLI checks npm for a newer version of @whatalo/cli. Results are cached for 24 hours at ~/.whatalo/version-check.json. If a newer version is available, a notification is printed to stderr — it never blocks the running command.

All Commands

Command	Description
`whatalo login`	Authenticate via browser Device Flow
`whatalo logout`	Sign out and revoke session
`whatalo whoami`	Show current developer info
`whatalo init`	Create a new plugin project interactively
`whatalo dev`	Start local development with live tunnel
`whatalo deploy`	Build and deploy a new plugin version
`whatalo validate`	Validate project config and manifest
`whatalo logs`	View and stream webhook delivery logs
`whatalo env pull`	Download environment variables to `.env`
`whatalo env show`	Display environment variables (read-only)
`whatalo webhook trigger`	Send a test webhook event to your plugin
`whatalo info`	Show project and environment info
`whatalo doctor`	Check your development environment
`whatalo upgrade`	Check for CLI updates

Global Flags

These flags are accepted by every command:

Flag	Description
`--portal-url <url>`	Override the Developer Portal URL
`--help`	Show command help
`--version`	Show CLI version