Zite

Create a new empty workspace — a database plus everything built on it. Add tables with create_table, then call create_sandbox with this workspaceId to build apps.

create_workspace

Delete a field (column) from a table. This will permanently remove the field and all its data from every record. When describing this action to users, refer to databases, tables, and fields by their human-readable names, not their IDs.

delete_field

Delete a record from a table. When describing this action to users, refer to databases and tables by their human-readable names, not their IDs.

delete_record

Delete a table from a database. This will permanently remove the table and all its records. When describing this action to users, refer to databases and tables by their human-readable names, not their IDs.

delete_table

Replace an exact text snippet in a file — the primary way to change code. oldText needs to match the current file content exactly and occur exactly once; include enough surrounding lines to make it unique. Prefer this over write_file for changes to existing files.

edit_file

Run a read-only PostgreSQL SELECT against a database, using the human-readable table and field names visible in the UI. Reach for SQL when query_records isn't expressive enough — counts, multi-table joins, traversing linked records, arbitrary aggregations, window functions, CTEs. Call get_database_schema first to discover table names, field names, link tables, and select-field options. Identifiers: - Quote names containing spaces: SELECT "Order Number" FROM "Orders". Names match case-insensitively against the UI. - System columns are always available: id (uuid), created_at and updated_at (timestamptz), created_by and updated_by (nullable zite_user ids), deleted_at (almost always null — see soft-delete below), autonumber_id (bigint), source_metadata (jsonb describing where the record was created from). Linked records: - Many-to-many relationships are exposed as link tables named <TableA>__<TableB>. Each link table has friendly id-column aliases (e.g. `ordersId`, `itemsId`) that get_database_schema returns under sourceTableIdColumn / targetTableIdColumn. The aliases are camelCase so they MUST be double-quoted in JOIN clauses (e.g. `JOIN "Items__Orders" l ON l."ordersId" = o.id`); Postgres folds unquoted `l.ordersId` to `l.ordersid` which doesn't exist. Use the friendly (quoted) aliases instead of source_record_id / target_record_id so the direction can't be wrong. Field-type semantics: - single_select fields: read returns the option label (e.g. "Electronics") AND filter/group/order accept the same label. `WHERE "Category" = 'Electronics'`, `GROUP BY "Category"`, `ORDER BY "Category"` all behave the way they read. (The rewriter wraps the column in a CASE that translates stored value → label, so read and filter operate in label-space.) - multiple_select fields: read returns an array of labels, and the JSONB operators (`@>`, `?`, `?|`) work in label-space too — e.g. `"Tags" @> '["Featured"]'::jsonb`, `"Tags" ? 'Featured'`, `"Tags" ?| array['Featured','Sale']`. Per-label aggregation uses `jsonb_array_elements_text` to unnest. Filtering on the raw option value no longer matches — always use the label. - Formula and lookup fields are stored as JSONB but the server unwraps and casts them to the field's resultType (number/text/date/boolean), so AVG(formula), WHERE lookup > 5, ORDER BY formula, COALESCE(lookup, 0), etc. all work as if the column were a native scalar. For lookup fields with a single linked target the server walks the link live (so values are current even if the cached lookup column is stale). - Array-typed formulas / lookups stay as raw JSONB so jsonb_array_length, ->, jsonb_array_elements, etc. apply directly. Soft-delete is automatic: every table reference is wrapped to exclude deleted_at IS NOT NULL rows. Don't add WHERE deleted_at IS NULL yourself — it's already applied. You also can't query soft-deleted rows via this tool. Parameter binding (use `params`, not interpolation): - Pass user-supplied values via `params` and reference them as $1, $2, … in the SQL — never interpolate them into the SQL string. pg keeps the query plan separate from the values, so user input can't change the query structure. - Examples: - { sql: 'SELECT * FROM "Orders" WHERE "Status" = $1', params: ['paid'] } - { sql: 'SELECT "Name" FROM "Customers" WHERE "Created at" >= $1', params: ['2024-01-01'] } - IN-list: { sql: 'SELECT * FROM "Orders" WHERE "Status" = ANY($1::text[])', params: [['paid', 'shipped']] } Supported query shapes: - WITH … AS (…) CTEs (single and multiple). Tip: alias projected columns inside the CTE if you want to reference them by a friendly name in the outer query — e.g. WITH t AS (SELECT "Email" AS email FROM "Customers") SELECT email FROM t. - Subselects in WHERE / SELECT / EXISTS / IN, including same-alias as outer (each subselect gets its own scope). - Self-references via subquery, LATERAL joins. - UNION / INTERSECT / EXCEPT, DISTINCT / DISTINCT ON, GROUP BY / HAVING, ORDER BY … NULLS FIRST/LAST. - Window functions: ROW_NUMBER() OVER (...), RANK(), LAG(), etc. - SQL-standard builtins: UPPER, LOWER, LENGTH, SUBSTRING, COALESCE, NULLIF, EXTRACT, ROUND, ABS — plus pg-specific to_char, date_trunc, jsonb_array_length, jsonb_typeof, etc. - Inline derived tables: FROM (VALUES (1)) v(x), FROM (SELECT 1 AS y) sub, FROM generate_series(1, 10) g(n). Qualified column refs against them (v.x, sub.y, g.n) pass through to pg. What does NOT work: - Writes (INSERT / UPDATE / DELETE / MERGE) — use the dedicated mutation tools. - Multi-statement queries (semicolon-chained). - Cross-base or cross-schema queries — execute_sql is bound to one baseId. - Functions that read the filesystem, sleep, or affect server state (pg_read_file, pg_sleep, pg_terminate_backend, dblink_*, lo_*, set_config, …). - Internal pseudo-columns ctid, xmin, tableoid. Result columns whose physical names map back to a field come back with the human field name; system columns and arbitrary expressions keep their pg-returned names. Restrictions: - Result rows capped at 2000; the response sets `truncated: true` when more rows existed. - Queries are subject to a statement timeout (default 10s). Examples: - SELECT "Email" FROM "Customers" WHERE "Name" = $1 // params: ['Alice'] - SELECT c."Name", COUNT(*) AS orders FROM "Customers" c JOIN "Customers__Orders" l ON l."customersId" = c.id GROUP BY c."Name"

execute_sql

Get a description of a database's tables, fields, and link tables, intended for composing SQL queries via execute_sql. Use this BEFORE calling execute_sql so you know which tables exist, what their fields are called, and how they relate. Returns: - tables: each with name, primaryFieldName, and (optional) fields with type/postgresType, linksTo (when the field is a linked_record), and options (when the field is single_select / multiple_select). - linkTables: many-to-many join tables exposed as <TableA>__<TableB>. Each entry includes the friendly id-column aliases sourceTableIdColumn and targetTableIdColumn (e.g. "ordersId", "itemsId") — use those in JOIN clauses, not the raw source_record_id / target_record_id columns. Direction depends on which side the linked_record field was created on, so the friendly aliases are unambiguous. Pass `tables` to scope to a subset of tables (and their adjacent link tables). Pass `includeFields: false` for a cheap overview of just table names.

get_database_schema

Read an app's endpoint execution logs. Without runId: a list of run summaries — status, duration, error message, and per-run counts of console/SDK/fetch events. With runId (from a listed run): that run in full — console output, SDK calls with request/response data, external fetches, the run's input and output, and the error stack trace. So the loop is list first, then fetch the interesting run by id. Use this to debug runtime failures that check_app (compile-time) cannot see. Each run reports the `snapshotId` that executed it: live runs execute the app's published snapshot, preview runs its latest build. `publishedSnapshotId` is the app's live code and `latestSnapshotId` its newest build, so when those differ, live traffic is running older code than the current source until the app is published.

get_logs

Get a single record by its ID from a database table.

get_record

Get the schema (fields) for a specific table in a database.

get_table_schema

Get one workspace: its apps, forms, and (when a sandboxId is provided) the project overview.md. Excludes trashed apps.

get_workspace

Ripgrep-backed content search across the workspace. Returns matching lines with file:line prefixes and context. Respects .gitignore and skips node_modules, so results are the app's own code. Scope with path (e.g. "apps/todo") and filter with glob (e.g. "*.tsx") to keep results tight. Use this to find the right code before editing.

grep

List the files in the sandbox workspace. Apps live under apps/<dir>/, shared UI under packages/components/. Pass a filter (substring or *-glob) to narrow the list.

list_files

List the workspaces you have access to. A workspace is a database plus the apps built on it — the id works with both the build tools (workspaceId) and the data tools (baseId).

list_workspaces

Publish an app's latest built version so it goes live. External apps get a public live URL; internal apps are published for organization members only.

publish_app

Query records from a database table. Returns records with their field values. `returnedRecords` is the size of this page, not the row count — use `hasMore`/`offset` to page, or execute_sql with COUNT(*) for a real total.

query_records

Read a file from the sandbox workspace. Large files can be read in slices with offset/limit (line numbers).

read_file

Run a one-off TypeScript script in the same isolated runtime app endpoints use, with the workspace SDK and integration credentials injected — unlike bash, which runs in the build sandbox where no integration credentials exist. Use it for one-time data work (seed, backfill, import), integration checks ("list my Slack channels"), and verifying runtime behavior before wiring it into an endpoint. The script runs against the live database. Import what endpoints import (`zitejs/db`, or an integration's npm package) and end with a bare `return` — the returned value comes back as `output` (over 20KB is truncated). List every integration the script uses in serviceTypes: that declaration is what injects each service's credentials (e.g. ZITE_STRIPE_ACCESS_TOKEN); valid values are the workspace's connectableServiceTypes from create_sandbox, plus "databases" for the project database. Integrations declared in an app's own zite.config.json resolve only when appId names that app.

run_one_off_script

Report a Zite platform problem — broken tooling, a misleading error, a missing capability, behaviour the docs don't explain — or pass along feedback the user asks you to send (docs gaps, missing capabilities, praise: use severity 'other'). The Zite team reads these and ships fixes. Reach for it when the platform didn't behave the way its tools, errors, or docs said it would, or when you worked around something instead of using it as intended. Report it even when you can't tell whether the fault was yours: you have context the team doesn't. Name the tool, and paraphrase what you passed and what came back rather than pasting raw output, secrets, or the user's data.

send_feedback

The integration picture for a workspace: which third-party services (Stripe, Slack, Google Sheets, Airtable, Notion, email, ...) can be connected, which accounts the org already has (orgServices — attach those yourself by writing the config entry with the given connectionId; no user needed), and what is already attached. When the account does not exist yet, share connectUrl with the user — OAuth happens in their browser — then call this again after they confirm. The guide from create_sandbox has the config-entry format and usage.

setup_integration

Update a field's name, type, or template. Changing the field type may affect existing data. When describing this action to users, refer to databases, tables, and fields by their human-readable names, not their IDs.

update_field

Update an existing record. Only the fields you specify will be updated; other fields remain unchanged. Complex field types have specific value encodings documented in record. When describing this action to users, refer to databases and tables by their human-readable names, not their IDs.

update_record

Update a table's name. When describing this action to users, refer to databases and tables by their human-readable names, not their IDs.

update_table

Create a new file or fully rewrite an existing one. For changes to existing files, edit_file is usually the better tool.

write_file