@meetploy/cli

The Ploy CLI for local development, type generation, and building workers with Cloudflare-compatible D1 and KV bindings.

Full Documentation · meetploy.com

Installation

npm install -g @meetploy/cli
# or as a dev dependency
npm install -D @meetploy/cli

Commands

ploy dev

Start the local development server with hot reloading. Automatically detects whether your project is a worker or a Next.js app.

ploy dev [options]

Options:

| Flag | Description | Default | | --------------------------- | --------------------- | ------------- | | -p, --port <number> | Server port | 3000 | | -h, --host <string> | Server host | localhost | | -c, --config <path> | Path to ploy.yaml | auto-detected | | --no-watch | Disable file watching | watch enabled | | -v, --verbose | Verbose output | false | | --dashboard-port <number> | Dev dashboard port | port + 1000 |

Worker projects — starts the local emulator with all Ploy services (database, queues, workflows, state, etc.):

ploy dev
# Worker running at http://localhost:3000
# Dashboard at http://localhost:4000

Database bindings are exposed as D1Database. State bindings keep their Ploy names while supporting the Cloudflare KVNamespace API.

Next.js projects — starts next dev alongside the Ploy mock server (auto-detected via kind: nextjs in ploy.yaml or the presence of next.config.*):

ploy dev -p 3000
# Next.js running at http://localhost:3000
# Ploy dashboard at http://localhost:4000

ploy types

Generate TypeScript type definitions from your ploy.yaml bindings. Creates an env.d.ts file and updates tsconfig.json.

ploy types [options]

Options:

| Flag | Description | Default | | --------------------- | ---------------- | ---------- | | -o, --output <path> | Output file path | env.d.ts |

Example output (env.d.ts):

declare module "@meetploy/nextjs" {
  interface PloyEnv {
    vars: { API_URL: string };
    DB: Database;
    STATE: StateBinding;
    QUEUE: QueueBinding;
    PLOY_AUTH: PloyAuth;
    AI: Ai;
  }
}

declare global {
  interface PloyEnv {
    vars: { API_URL: string };
    DB: Database;
    STATE: StateBinding;
    QUEUE: QueueBinding;
    PLOY_AUTH: PloyAuth;
    AI: Ai;
  }
}

export {};

When ai: true is enabled, the generated types include AI: Ai for env.AI.run(...) as the primary binding, plus PLOY_AI_URL and PLOY_AI_TOKEN for direct calls.

Run it whenever you change bindings in ploy.yaml:

ploy types
# or with a custom output path
ploy types -o src/env.d.ts

ploy build

Build your worker project using wrangler. Reads ploy.yaml to determine the entry point and compatibility settings.

ploy build [options]

Options:

| Flag | Description | Default | | --------------------- | ------------------- | ------------- | | -c, --config <path> | Path to ploy.yaml | auto-detected |

ploy auth

Manage authentication with the Ploy API.

ploy auth login    # Browser-based OAuth login
ploy auth logout   # Clear stored credentials

Credentials are stored in ~/.ploy/config.json. You can also set PLOY_API_TOKEN as an environment variable.

ploy api

Interact with the Ploy platform API (requires ploy auth login).

# Deployments
ploy api deployment list
ploy api deployment view <id>
ploy api deployment retry <id>
ploy api deployment logs <id>

# Databases
ploy api db list
ploy api db tables <database>
ploy api db analytics <database>

Deployment options: --project <id> (required for list), --branch <name>, --commit <sha>, --limit <n>

Database options: --org <id> (required), --project <id>, --period <24h|7d|30d>, --limit <n>, --schema

ploy.yaml Reference

The ploy.yaml file at the root of your project configures the Ploy runtime and CLI:

kind: worker # worker | nextjs | static
build: pnpm build # build command
out: dist # output directory

# Environment variables (exposed as vars: {} in PloyEnv)
env:
  API_URL: https://api.example.com

# Runtime bindings — format is BINDING_NAME: resource_name
db:
  DB: default

queue:
  QUEUE: tasks

workflow:
  FLOW: my_flow

state:
  STATE: default

fs:
  STORAGE: default

timer:
  TIMER: default

ai: true

auth:
  binding: PLOY_AUTH

After editing bindings, regenerate types with ploy types.

db bindings map to Database. state bindings map to StateBinding, which is compatible with the Cloudflare KV API while preserving Ploy's existing binding names.

Documentation

• CLI Reference
• Workers
• Ploy Start Framework
• Next.js Integration
• Full Docs