windmill-cli 1.700.0 → 1.700.2

package/esm/main.js

@@ -16752,7 +16752,7 @@ var init_OpenAPI = __esm(() => {
     PASSWORD: undefined,
     TOKEN: getEnv3("WM_TOKEN"),
     USERNAME: undefined,
-    VERSION: "1.700.0",
+    VERSION: "1.700.2",
     WITH_CREDENTIALS: true,
     interceptors: {
       request: new Interceptors,
@@ -84945,9 +84945,9 @@ name: raw-app
 description: MUST use when creating raw apps.
 ---
 
-# Windmill Raw Apps
+# Windmill Raw Apps — CLI workflow
 
-Raw apps let you build custom frontends with React, Svelte, or Vue that connect to Windmill backend runnables and datatables.
+This guide covers raw apps from the terminal: scaffolding via \`wmill app new\`, the on-disk layout, and the file-based conventions the CLI uses to represent backend runnables and data table configuration. The platform shape (how a raw app behaves at runtime — frontend bundling, runnable types, datatable SDK calls) is covered in the companion authoring guide.
 
 ## Creating a Raw App
 
@@ -85016,7 +85016,7 @@ wmill app new
 
 This is the wizard. It only works when run by a human in a real terminal. Don't call it this way from an agent.
 
-## App Structure
+## On-disk app layout
 
 \`\`\`
 my_app{{RAW_APP_SUFFIX}}/
@@ -85036,11 +85036,7 @@ my_app{{RAW_APP_SUFFIX}}/
     └── *.sql              # SQL files to apply via dev server
 \`\`\`
 
-## Backend Runnables
-
-Backend runnables are server-side scripts that your frontend can call. They live in the \`backend/\` folder.
-
-### Creating a Backend Runnable
+## Backend runnables on disk
 
 Add a code file to the \`backend/\` folder:
 
@@ -85050,7 +85046,7 @@ backend/<id>.<ext>
 
 The runnable ID is the filename without extension. For example, \`get_user.ts\` creates a runnable with ID \`get_user\`.
 
-### Supported Languages
+### Supported languages (extension-driven)
 
 | Language         | Extension    | Example          |
 |------------------|--------------|------------------|
@@ -85072,27 +85068,14 @@ The runnable ID is the filename without extension. For example, \`get_user.ts\`
 | C#               | \`.cs\`        | \`myFunc.cs\`      |
 | Java             | \`.java\`      | \`myFunc.java\`    |
 
-### Example Backend Runnable
-
-**backend/get_user.ts:**
-\`\`\`typescript
-import * as wmill from 'windmill-client';
-
-export async function main(user_id: string) {
-  const sql = wmill.datatable();
-  const user = await sql\`SELECT * FROM users WHERE id = \${user_id}\`.fetchOne();
-  return user;
-}
-\`\`\`
-
-After creating, tell the user they can generate lock files by running:
+After creating a runnable, tell the user they can generate lock files by running:
 \`\`\`bash
 wmill generate-metadata
 \`\`\`
 
-### Optional YAML Configuration
+### Optional YAML configuration
 
-Add a \`<id>.yaml\` file to configure fields or static values:
+Add a \`<id>.yaml\` file alongside the code to configure fields or static values:
 
 **backend/get_user.yaml:**
 \`\`\`yaml
@@ -85103,7 +85086,7 @@ fields:
     value: "default_user"
 \`\`\`
 
-### Referencing Existing Scripts
+### Referencing existing scripts
 
 To use an existing Windmill script instead of inline code:
 
@@ -85119,32 +85102,9 @@ type: flow
 path: f/my_folder/my_flow
 \`\`\`
 
-### Calling Backend from Frontend
-
-Import from the auto-generated \`wmill.ts\`:
+## Data tables — \`raw_app.yaml\` config
 
-\`\`\`typescript
-import { backend } from './wmill';
-
-// Call a backend runnable
-const user = await backend.get_user({ user_id: '123' });
-\`\`\`
-
-The \`wmill.ts\` file provides type-safe access to all backend runnables.
-
-## Data Tables
-
-Raw apps can query Windmill datatables (PostgreSQL databases managed by Windmill).
-
-### Critical Rules
-
-1. **ONLY USE WHITELISTED TABLES**: You can ONLY query tables listed in \`raw_app.yaml\` → \`data.tables\`. Tables not in this list are NOT accessible.
-
-2. **ADD TABLES BEFORE USING**: To use a new table, first add it to \`data.tables\` in \`raw_app.yaml\`.
-
-3. **USE CONFIGURED DATATABLE/SCHEMA**: Check the app's \`raw_app.yaml\` for the default datatable and schema.
-
-### Configuration in raw_app.yaml
+The \`data\` block in \`raw_app.yaml\` controls which tables the app can query.
 
 \`\`\`yaml
 data:
@@ -85156,48 +85116,9 @@ data:
 \`\`\`
 
 **Table reference formats:**
-- \`<datatable>\` - All tables in the datatable
-- \`<datatable>/<table>\` - Specific table in public schema
-- \`<datatable>/<schema>:<table>\` - Table in specific schema
-
-### Querying in TypeScript (Bun/Deno)
-
-\`\`\`typescript
-import * as wmill from 'windmill-client';
-
-export async function main(user_id: string) {
-  const sql = wmill.datatable();  // Or: wmill.datatable('other_datatable')
-
-  // Parameterized queries (safe from SQL injection)
-  const user = await sql\`SELECT * FROM users WHERE id = \${user_id}\`.fetchOne();
-  const users = await sql\`SELECT * FROM users WHERE active = \${true}\`.fetch();
-
-  // Insert/Update
-  await sql\`INSERT INTO users (name, email) VALUES (\${name}, \${email})\`;
-  await sql\`UPDATE users SET name = \${newName} WHERE id = \${user_id}\`;
-
-  return user;
-}
-\`\`\`
-
-### Querying in Python
-
-\`\`\`python
-import wmill
-
-def main(user_id: str):
-    db = wmill.datatable()  # Or: wmill.datatable('other_datatable')
-
-    # Use $1, $2, etc. for parameters
-    user = db.query('SELECT * FROM users WHERE id = $1', user_id).fetch_one()
-    users = db.query('SELECT * FROM users WHERE active = $1', True).fetch()
-
-    # Insert/Update
-    db.query('INSERT INTO users (name, email) VALUES ($1, $2)', name, email)
-    db.query('UPDATE users SET name = $1 WHERE id = $2', new_name, user_id)
-
-    return user
-\`\`\`
+- \`<datatable>\` — All tables in the datatable
+- \`<datatable>/<table>\` — Specific table in public schema
+- \`<datatable>/<schema>:<table>\` — Table in specific schema
 
 ## SQL Migrations (sql_to_apply/)
 
@@ -85206,11 +85127,11 @@ The \`sql_to_apply/\` folder is for creating/modifying database tables during de
 ### Workflow
 
 1. Create \`.sql\` files in \`sql_to_apply/\`
-2. Run \`wmill app dev\` - the dev server watches this folder
+2. Run \`wmill app dev\` — the dev server watches this folder
 3. When SQL files change, a modal appears in the browser to confirm execution
 4. After creating tables, **add them to \`data.tables\`** in \`raw_app.yaml\`
 
-### Example Migration
+### Example migration
 
 **sql_to_apply/001_create_users.sql:**
 \`\`\`sql
@@ -85229,12 +85150,12 @@ data:
     - main/users
 \`\`\`
 
-### Migration Best Practices
+### Migration best practices
 
 - **Use idempotent SQL**: \`CREATE TABLE IF NOT EXISTS\`, etc.
 - **Number files**: \`001_\`, \`002_\` for ordering
 - **Always whitelist tables** after creation
-- This folder is NOT synced - it's for local development only
+- This folder is NOT synced — it's for local development only
 
 ## CLI Commands
 
@@ -85250,14 +85171,145 @@ For everything else, tell the user which command fits their intent and let them
 | \`wmill sync push\` | Deploy app to Windmill |
 | \`wmill sync pull\` | Pull latest from Windmill |
 
+
+
+# Windmill Raw Apps
+
+Raw apps let you build custom frontends with React, Svelte, or Vue that connect to Windmill backend runnables and datatables.
+
+## App shape
+
+A raw app has three logical parts:
+
+- **Frontend** — bundled with esbuild from \`index.tsx\` as the entrypoint. Files include the entrypoint, components (\`App.tsx\`), styles, etc.
+- **Backend runnables** — server-side scripts the frontend calls, each addressed by a unique key.
+- **Data** — optional whitelisted datatables (managed PostgreSQL) that the backend runnables can query. The frontend never queries the database directly; backend runnables are the only bridge.
+
+## Frontend
+
+### Entrypoint
+
+\`index.tsx\` is the bundling entrypoint. It typically renders a top-level \`App\` component. The bundler is esbuild.
+
+### Generated bindings (\`wmill.d.ts\` / \`wmill.ts\`)
+
+The frontend imports a generated module that mirrors the backend runnables. **Never write to it directly** — it gets regenerated whenever backend runnables change. Modifying it by hand will be overwritten.
+
+### Calling backend runnables
+
+Import the generated bindings and call the runnable like a function:
+
+\`\`\`typescript
+import { backend } from './wmill';
+
+// Call a backend runnable
+const user = await backend.get_user({ user_id: '123' });
+\`\`\`
+
+The frontend cannot reach datatables, workspace items, or external services on its own — it goes through \`backend.<key>(args)\` for everything server-side.
+
+## Backend runnables
+
+Each runnable has a unique key (used to call it from the frontend) and one of four types:
+
+| Type | What it is |
+|---|---|
+| \`inline\` | Custom code stored on the app itself. Most common for app-specific logic. |
+| \`script\` | Reference to an existing workspace script by path. |
+| \`flow\` | Reference to an existing workspace flow by path. |
+| \`hubscript\` | Reference to a hub script by path. |
+
+### Inline runnables
+
+Inline runnables carry their own source code. For file-based raw apps, the runnable language is determined by the backend file extension. The script must expose a \`main\` function as its entrypoint.
+
+**TypeScript example** (\`backend/get_user.ts\`):
+
+\`\`\`typescript
+import * as wmill from 'windmill-client';
+
+export async function main(user_id: string) {
+  const sql = wmill.datatable();
+  const user = await sql\`SELECT * FROM users WHERE id = \${user_id}\`.fetchOne();
+  return user;
+}
+\`\`\`
+
+**Python example** (\`backend/get_user.py\`):
+
+\`\`\`python
+import wmill
+
+def main(user_id: str):
+    db = wmill.datatable()
+    user = db.query('SELECT * FROM users WHERE id = $1', user_id).fetch_one()
+    return user
+\`\`\`
+
+### Path runnables (script / flow / hubscript)
+
+When \`type\` is \`script\`, \`flow\`, or \`hubscript\`, the runnable just stores a \`path\` to an existing workspace or hub item — no inline code. The referenced item's input/output schema becomes the runnable's surface.
+
+### Static inputs
+
+\`staticInputs\` is an optional \`Record<string, any>\` for arguments not overridable from the frontend. Useful with path runnables to pre-fill some args while leaving the rest to the frontend caller.
+
+## Data Tables
+
+Data tables are PostgreSQL databases managed by Windmill. Backend runnables query them via the \`wmill\` client; the frontend never queries them directly.
+
+### Critical rules
+
+1. **Whitelisted tables only**: a runnable can only query tables listed in the app's \`data.tables\` config. Tables not in this list are not accessible.
+2. **Add tables before using**: queries against unlisted tables fail at runtime. When you introduce a new table, register it in \`data.tables\` first.
+3. **Use the configured datatable/schema**: the app's \`data\` config sets the default datatable and schema; reference them consistently across runnables.
+
+### Querying in TypeScript (Bun/Deno)
+
+\`\`\`typescript
+import * as wmill from 'windmill-client';
+
+export async function main(user_id: string) {
+  const sql = wmill.datatable();  // Or: wmill.datatable('other_datatable')
+
+  // Parameterized queries (safe from SQL injection)
+  const user = await sql\`SELECT * FROM users WHERE id = \${user_id}\`.fetchOne();
+  const users = await sql\`SELECT * FROM users WHERE active = \${true}\`.fetch();
+
+  // Insert/Update
+  await sql\`INSERT INTO users (name, email) VALUES (\${name}, \${email})\`;
+  await sql\`UPDATE users SET name = \${newName} WHERE id = \${user_id}\`;
+
+  return user;
+}
+\`\`\`
+
+### Querying in Python
+
+\`\`\`python
+import wmill
+
+def main(user_id: str):
+    db = wmill.datatable()  # Or: wmill.datatable('other_datatable')
+
+    # Use $1, $2, etc. for parameters
+    user = db.query('SELECT * FROM users WHERE id = $1', user_id).fetch_one()
+    users = db.query('SELECT * FROM users WHERE active = $1', True).fetch()
+
+    # Insert/Update
+    db.query('INSERT INTO users (name, email) VALUES ($1, $2)', name, email)
+    db.query('UPDATE users SET name = $1 WHERE id = $2', new_name, user_id)
+
+    return user
+\`\`\`
+
 ## Best Practices
 
-1. **Check DATATABLES.md** for existing tables before creating new ones
-2. **Use parameterized queries** - never concatenate user input into SQL
-3. **Keep runnables focused** - one function per file
-4. **Use descriptive IDs** - \`get_user.ts\` not \`a.ts\`
-5. **Always whitelist tables** - add to \`data.tables\` before querying
-6. **Generate locks** - tell the user to run \`wmill generate-metadata\` after adding/modifying backend runnables
+1. **Check existing tables** before creating new ones — reuse beats schema growth.
+2. **Use parameterized queries** — never concatenate user input into SQL.
+3. **Keep runnables focused** — one function per runnable; small surface area.
+4. **Use descriptive keys** — \`get_user\`, not \`a\`.
+5. **Always whitelist tables** — adding a runnable that queries a new table requires the table to be in \`data.tables\` first.
 `,
   triggers: `---
 name: triggers
@@ -89624,7 +89676,7 @@ var config_default = command35;
 
 // src/main.ts
 await init_context();
-var VERSION = "1.700.0";
+var VERSION = "1.700.2";
 async function checkVersionSafe(cmd) {
   const mainCommand = cmd.getMainCommand();
   const upgradeCommand = mainCommand.getCommand("upgrade");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "windmill-cli",
-  "version": "1.700.0",
+  "version": "1.700.2",
   "description": "CLI for Windmill",
   "license": "Apache 2.0",
   "type": "module",