@meetploy/cli 1.20.0 → 1.22.0

package/README.md

@@ -0,0 +1,203 @@
+# @meetploy/cli
+
+The Ploy CLI for local development, type generation, and building workers.
+
+**[Full Documentation](https://docs.meetploy.com/cli)** · [meetploy.com](https://meetploy.com)
+
+## Installation
+
+```bash
+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.
+
+```bash
+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, cache, etc.):
+
+```bash
+ploy dev
+# Worker running at http://localhost:3000
+# Dashboard at http://localhost:4000
+```
+
+**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.*`):
+
+```bash
+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`.
+
+```bash
+ploy types [options]
+```
+
+**Options:**
+
+| Flag                  | Description      | Default    |
+| --------------------- | ---------------- | ---------- |
+| `-o, --output <path>` | Output file path | `env.d.ts` |
+
+**Example output** (`env.d.ts`):
+
+```typescript
+declare module "@meetploy/nextjs" {
+  interface PloyEnv {
+    vars: { API_URL: string };
+    DB: D1Database;
+    QUEUE: QueueBinding;
+    PLOY_AUTH: PloyAuth;
+  }
+}
+
+declare global {
+  interface PloyEnv {
+    vars: { API_URL: string };
+    DB: D1Database;
+    QUEUE: QueueBinding;
+    PLOY_AUTH: PloyAuth;
+  }
+}
+
+export {};
+```
+
+Run it whenever you change bindings in `ploy.yaml`:
+
+```bash
+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.
+
+```bash
+ploy build [options]
+```
+
+**Options:**
+
+| Flag                  | Description         | Default       |
+| --------------------- | ------------------- | ------------- |
+| `-c, --config <path>` | Path to `ploy.yaml` | auto-detected |
+
+---
+
+### `ploy auth`
+
+Manage authentication with the Ploy API.
+
+```bash
+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`).
+
+```bash
+# 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:
+
+```yaml
+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
+
+cache:
+  CACHE: default
+
+state:
+  STATE: default
+
+fs:
+  STORAGE: default
+
+timer:
+  TIMER: default
+
+ai: true
+
+auth:
+  binding: PLOY_AUTH
+```
+
+After editing bindings, regenerate types with `ploy types`.
+
+## Documentation
+
+- [CLI Reference](https://docs.meetploy.com/cli)
+- [Workers](https://docs.meetploy.com/features/workers)
+- [Ploy Start Framework](https://docs.meetploy.com/start)
+- [Next.js Integration](https://docs.meetploy.com/nextjs)
+- [Full Docs](https://docs.meetploy.com)