agentleFS
xano-sdkxano-sdk/sdk/llms.txt

sdk

llms.txt1 starsChanged 32 days agoMITView on GitHub

TypeScript SDK that compiles a typed Xano workspace into the importable packageExport JSON bundle. Xano is one platform to build, run and govern AI-built software: one WORKSPACE serves a managed PostgreSQL database, HTTP APIs, background tasks, realtime websocket channels, AI agents, MCP servers, file storage and redis. This SDK authors it in TypeScript — typed def objects registered on a workspace(name) — compiled to one importable bundle by npx @xano/sdk export ./xano/index.ts, shipped live by deploy. Def modules execute at…

  • Reads credentials

The file

We split this llms.txt into the rules it gives an agent

5 rules. About 0 are common, 0 are distinctive, and 5 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Not authorable here: branch, market_item, realtime_channel (legacy.

    line 20
  2. Very specific:

    Before calling the work done: npm run typecheck, npx @xano/sdk export <entry> --strict, deploy <entry>, then test run-all against what …

    line 129
  3. Very specific:

    Every build freezes every guid + api-group/toolset canonical in a lock file beside the entry file (xano/xano.lock in the standard scaffold, …

    line 134
  4. Very specific:

    EVERY s.db.add into it 400s — at any column type, with or without a value — and the error names the column while complaining about the …

    line 295
  5. Very specific:

    Prefer a native typed input (input.email) over hand-rolled validation.

    line 397

≈ “Common” is an estimate: at least 1 in 5 of the 3,727 llms.txt files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
llms.txt
# xanosdk v1.0.21

> TypeScript SDK that compiles a typed Xano workspace into the importable packageExport JSON bundle.

Xano is one platform to build, run and govern AI-built software: one WORKSPACE
serves a managed PostgreSQL database, HTTP APIs, background tasks, realtime
websocket channels, AI agents, MCP servers, file storage and redis. This SDK
authors it in TypeScript — typed def objects registered on a
`workspace(name)` — compiled to one importable bundle by `npx @xano/sdk export
./xano/index.ts`, shipped live by `deploy`.

Def modules execute at BUILD time only: `s.*` factories return data, and the engine
runs the compiled stack per request — statements in order, a statement's `as:`
naming a runtime variable, `response` the HTTP body. Every dynamic operand is a
TAGGED value — `ref("x")` a stack variable, `inp("x")` an input, `auth("id")` the
caller, `c.*` a constant — resolved at request time; JS operators over them do not
compute (see Gotchas). Requests share no memory — state persists in tables or redis.

Authorable: statement surfaces 227/227, filters 246 (246 typed).
Not authorable here: branch, market_item, realtime_channel (legacy; author realtimeServer + realtimeChannel instead), tablemap — these cannot be authored and do not survive a pull; reasons in `coverage.objectKinds.unmodeled`.

Per-surface detail is in the topic files below: open the one whose condition matches the task.
Per-entry detail (a statement's field schema with engine defaults, a filter's full argument
list, the `storedName` mapping) is in the shipped `manifest.json` — do a TARGETED lookup;
it is ~80k tokens, so never read it whole. A program imports it as `@xano/sdk/manifest.json`
(Node ESM needs `with { type: "json" }`). Its top-level keys are `name`, `version`, `description`, `coverage`, `values`, `objectKinds`, `fieldTypes`, `statements`, `filters`, `cli`, `cliGlobalFlags`. `statements` and `filters` are ARRAYS, not maps — SELECT, do not index:
  jq '.statements[] | select(.sPath=="db.get")' manifest.json
  jq '.filters[]    | select(.name=="json_decode")' manifest.json
⚠ `fields` is null on the 66 `declarative: false` statements (`db.get`, …): typed wrappers whose arguments are the factory's `.d.ts` signature. Null ≠ missing.
Select a statement on `sPath` (the `s.*` path you write), NOT `surface` (the XanoScript term): 24 of 227 differ — `var`→`set_var`, `break`→`foreach_break`, `foreach.remove`→`foreach_remove`, and every `expect.*`.

## Topic files

Paths are relative to this file (`node_modules/@xano/sdk/` once installed), so a
plain file read resolves them at the version you have.
`llms-full.txt` is everything concatenated — one fetch for a reader that cannot open files.

- [Object kinds](llms/object-kinds.md): Read when deciding WHAT to build — every authorable primitive, what each is, and which factory + register method builds it. Also when `register*` will not typecheck an array built by `.flatMap()`/`.concat()`.
- [Core def shapes](llms/kinds-core.md): Read when authoring a function, query, api group, task, workflow test, middleware, tool, or addon — and for the `response` and `expr` shapes every one of them uses.
- [Consuming defs from a client](llms/client.md): Read when a frontend calls the deployed backend or imports a def — request types and zod schemas without the import, its cost, `window.XANO_HOST`, local dev, file URLs, a Node spot-check.
- [Toolchain modules](llms/toolchain.md): Read when `package.json` has a `"xanosdk"` block or you run `npx @xano/sdk marketplace`.
- [Error index](llms/errors.md): Read when a request, test, build, or pull fails with a message you did not write — the string, its cause, and where the fix is.
- [Saved unit tests, assertions, and mocks](llms/tests.md): Read when authoring a `workflowTest()` stack, when a query/function/middleware carries `tests`, when a statement needs a `mock`, or when running a deployed environment's tests.
- [Agent and MCP def shapes](llms/kinds-agent-mcp.md): Read when building an MCP server (tools, prompts, resources) or an `agent()`.
- [Knowledge def shape](llms/kinds-knowledge.md): Read when the workspace defines a `knowledge()` item.
- [Realtime def shapes](llms/kinds-realtime.md): Read when the workspace defines a `realtimeServer()`, `realtimeChannel()`, or `realtimeMessage()` handler.
- [Triggers](llms/triggers.md): Read when authoring any trigger. A trigger's `stack` is a callback rather than the plain array every other kind takes, so the shape does not carry over.
- [Array and database statements](llms/statements-data.md): Read when the stack reads or writes rows (`s.db.*`), or transforms an array in place (`s.array.map`, `s.array.union`).
- [Statement runtime behavior](llms/statements-runtime.md): Read when you need to know what a statement's `as:` output holds, or why a bound variable is not the shape expected.
- [Auth, cross-object calls, and microservices](llms/statements-calls.md): Read when the stack authenticates or verifies a webhook (recipes here), calls another object (`s.function.run`, `s.api.request`, `s.tool.call`), sends email (`s.util.send_email`), or reaches a microservice.
- [Value catalog](llms/values.md): Read when you need a literal, a reference, or a tag you have not used before — `c.*`, `ref`, `inp`, `auth`, `col`, and what each one encodes to.
- [Column and input types](llms/fields.md): Read when declaring a table column (`f.*`) or a function/query input (`input.*`) — a type's options and methods, and the `s.precondition` error/status contract. Also `table({ seed })` rows and `use_xdo`.
- [Filter catalog](llms/filters.md): Read when piping a value through `fl.*` — the full catalog with each filter's argument types.
- [Lambda bodies (JavaScript)](llms/lambda.md): Read when writing a JavaScript body, or weighing whether to reach for one at all — `lam.fn`, `fl.lambda`, `fl.reduce`, `s.lambda`; each surface binds a different set of identifiers.
- [Lock file](llms/lock.md): Read when a `xano.lock` exists or should — renaming/pruning/importing identities, seeding the lock programmatically, or asking which commands write it.
- [Legacy paradigms and retired statements](llms/legacy.md): Read when the code was PULLED from an existing Xano instance — how a codegen'd tree reads, the shapes in it that must not be "fixed", and any `raw({ name: "mvp:…" })`, `realtimeTrigger()`, or name the catalogs do not list.
- [Statement catalog](llms/statements-catalog.md): Read for the field signature of a specific statement — every surface but `s.ai.*`, grouped by `s.*` namespace.
- [AI statements](llms/statements-ai.md): Read when the stack calls `s.ai.*` (a Xano AI model, an external MCP server) or you choose where a Xano AI call runs.

## Quickstart

```ts
import { workspace, apiGroup, query, table, input, f, ref, inp, auth, s } from "@xano/sdk";

const users = table({
  name: "users",
  auth: true, // backs authentication
  // `id` (int PK) + `created_at` (epochms) are auto-injected — don't declare them.
  schema: {
    email: f.email({ required: true, methods: ["trim", "lower"] }), // a unique email index is CASE-SENSITIVE — lowercase it
    name: f.text(),
  },
  // Indexes: { type, fields: [{ name, op? }] }. `"unique"` is shorthand for `"btree|unique"`.
  // A DOTTED name indexes a key inside a column (`xdo.email`); only the part before the
  // first dot is checked against the schema.
  index: [{ type: "unique", fields: [{ name: "email" }] }],
});

const posts = table({
  name: "posts",
  schema: {
    author: f.tableRef(users), // foreign key → users (NOT `ref`)
    body: f.text({ required: true }),
  },
});

const api = apiGroup({ name: "blog", canonical: "blog" }); // canonical → the URL token

const createPost = query({
  name: "create_post", verb: "POST", apiGroup: api, auth: users, // the auth table
  input: { body: input.text({ required: true }) },
  stack: [
    s.db.add({ table: posts, row: { author: auth("id"), body: inp("body") }, as: "post" }),
  ],
  response: ref("post"),
});

const listPosts = query({
  name: "list_posts", verb: "GET", apiGroup: api,
  stack: [s.db.query({ table: posts, sort: [{ sortBy: "created_at", dir: "desc" }], as: "rows" })],
  response: ref("rows"),
});

export default workspace("my-blog")
  .registerTables([users, posts])
  .registerApiGroups([api])
  .registerQueries([createPost, listPosts]);
```

Compile: `npx @xano/sdk export ./index.ts --out bundle.json` (or `writeBundle(app, path)`
from `@xano/sdk/node` in code). The default export must be the `Xano` registry. The entry must be an
ES module (Xano SDK defs are ESM-only): set `"type": "module"` in the nearest
package.json or name the entry `.mts`. `npm init -y` writes `"type": "commonjs"`,
which fails with a "must be ES modules" error until you switch it to module.

Set `canonical` on every `apiGroup`. The engine mints the URL token server-side, so
without one `npx @xano/sdk routes` / `getPath()` cannot resolve the group's paths until a
lock exists (the export itself succeeds).
⚠ A canonical is unique across the whole INSTANCE, not per workspace; no flag shares one.
A canonical set in code is a PIN: a merge refuses (exit 2) when another workspace holds it.
One only the lock minted is not pinned: the instance may replace it with a random token,
and `--static` is refused when it does.

Build warnings: `export()` warns on shapes that deploy but misbehave (a `bulk.update`
zero-filling omitted columns, an `ignoreEmpty` on an empty operand, a `ref()` nothing
binds). In CI and agent builds pass `--strict` (`emitBundle(app, { strict: true })` /
`app.export({ strict: true })`): every warning becomes a hard failure. Same bundle bytes
either way.
Before calling the work done: `npm run typecheck`, `npx @xano/sdk export <entry> --strict`,
`deploy <entry>`, then `test run-all` against what deployed.

Identity: object guids derive from `(type, name)` (a query adds group + verb),
so renames change identity.
Every build freezes every guid + api-group/toolset canonical in a lock file beside the entry
file (`xano/xano.lock` in the standard scaffold, not the project root). Commit it
(`--no-lock` opts out; CI guard `--frozen-lock` fails instead of changing it).
To rename an object: rename in code, export (stderr prints the exact fix-up), run
`npx @xano/sdk lock rename <kind> <old> <new>`, export again — the original guid is emitted
under the new name, so the engine renames in place instead of delete+create. Taking
over an existing workspace: `npx @xano/sdk lock import <live-bundle.json>` first, then
export. Pruning, programmatic seeding, and which commands write the lock:
`llms/lock.md`.

## Deploy

Commands here run as `npx @xano/sdk <cmd>`: `init` → `deploy` → URL. A deploy runs the same compile pipeline as
`export` (honoring `xano.lock`), imports the result, and prints the URL.
⚠ Every deploy is a FULL REPLACE of its destination — objects AND records.

**Backends** — one grammar for every command that names a backend:

- Spellings: `workspace` | `ephemeral[:<name>]` | `local[:<name>]` (no credential) |
  `tenant:<name>` | `release:<name>` | a bundle path where a file fits.
- Reads `--from`, writes `--to`, `test --on`; positional on `deploy`/`pull`/`generate`/`tables`/
  `impersonate`.
- Omitted = the ephemeral or Xano Engine this project last deployed to, never
  workspace/tenant. Exceptions: bare `deploy` always targets the Xano Engine (`--ephemeral`: an
  ephemeral); `generate`/`init --from` need one.
- A backend a command cannot serve is refused, typed or tracked, with the reason and the valid
  spellings (`release create` refuses a Xano Engine).
- `release create --from` takes a run only: no bundle path, no `release:`, and a
  `tenant:` only if throwaway (`standard`/`run` refused).

**Destinations** — the Xano Engine by default, real only when you say so:

- `deploy [source]` → the Xano Engine on this machine (no account).
  - `--ephemeral` → a NAMED, auto-expiring ephemeral (~1h; `--expires-hours` 1–24), tracked in
    `./.xano/ephemeral.json`, so deploying again REFRESHES it at the same URL; if it expired or
    was swept, a fresh one is created and the new URL printed.
  - ⚠ Only the BACKEND URL survives a refresh: the replace clears static hosting, so
    `--static` publishes a NEW host every run and the previous URL stops serving.
  - Under `--keep-data`, which MERGES an env a deploy filled instead of replacing it, the static
    URL survives too: rows kept, no re-seed, removed objects deleted. ⚠ Limits: a rename loses values,
    a RETYPE reads unfit ones as null, env VALUES are not applied, a table trigger refuses it.
    `--reset` replaces and re-seeds.
- `release create <name>` cuts a release from a running source and LANDS it in your workspace.
  A release records that the source came up; it is the only thing `promote`/`tenant deploy` take.
  - Refused: a taken name, and one that addresses a LOCATION instead of naming (`/`, `\`, `:`,
    or a leading `.`). Every export derives its FILENAME from the name it is given, so
    `release|ephemeral|workspace export` refuse those same shapes unless `--path` names the file.
  - Carries EVERY table's SCHEMA either way; `--seed[=<guids>]` adds ROWS. Guids come from
    `tables <backend>`; a redeploy KEEPS them.
- `release transfer <name> --to-profile <profile>` copies a release to another
  workspace/instance by CONTENT (tar sha256): identical → reused; same name, other
  bytes → exit 2.
- `promote <release>` / `tenant deploy <tenant> <release>` land it.
  - `promote` adds a branch; ⚠ its TABLE edits hit live (`--allow-shared-schema-changes`).
  - `tenant deploy` REPLACES: DROPS tables it lacks, CONVERTS retypes (`--seed`: rows).
  - `promote` refuses a taken name/pinned slug (`SDK_IDENTITY_CONFLICT`), then EXITS NON-ZERO
    if a declared object did not arrive or a pinned slug is not served. `--set-live` switches
    only after that check passes; a failure leaves the previous branch serving. Extra objects
    are reported; a check missing an input reports `unverified`, exit 0.
  - `--expect-live <label>` (with `--set-live`) refuses if live moved; not atomic.
  - `--json` on every release write: `completed` yes|no|unknown; UNKNOWN exits 9 — run
    `resolveWith`, never retry blind.
  - Inspect a staged branch with `workspace export --branch <label>` or
    `workspace diff <entry> --branch <label>`.
- ⚠ The redis family, `s.lambda`, `s.db.direct_query`, `s.await`, async runs,
  `s.microservice.request`, `s.zip.*`, the raw-file readers, Datadog and Webflow need an
  INSTANCE CAPABILITY: they deploy clean and fail on the first request if the target lacks it.
  `export`/`deploy` list what the bundle needs — compare it to the target yourself.
- Backend SECRETS stay out of the repo: declare the NAME, value empty, in `workspaceConfig({ env })`
  passed to `registerWorkspace()`; the VALUE lives in `xano/.env` — gitignored, kept across a
  pull, read by every build. `--backend-env-file <path>` replaces that default (CI has
  no `xano/.env`), `--env-var KEY=VALUE` beats both, and `env pull` fills the file from
  a running backend — the only command that writes `xano/.env`.
  ⚠ A deploy REPLACES the env set: a declared name with NO value refuses the deploy rather
  than clearing the live one — `--allow-empty-env=NAME` clears it on purpose.
  ONE live value, no deploy: `env set NAME` (value on stdin) / `env unset NAME`.
  (`--static-env` is the other one — PUBLIC frontend config.)
- A DOCUMENTATION token is a secret too, in a SECOND ignored file: source declares only the
  gate — `documentation: { require_token: true }` on `workspaceConfig` or an `apiGroup` — and
  the value lives in `xano/.secrets.json`, keyed by the object it gates. A literal `token`
  FAILS the export. `pull` writes that file and every build reads it back;
  `secrets fill` MINTS one per gate that has none — a gate you AUTHORED has no value
  to pull. CI, which does not have the file, passes `--secrets-file <path>` or
  `--doc-token "<scope>=<value>"`
  (scope = `workspace`, or the group's NAME).
  ⚠ OMISSION IS OPPOSITE PER SCOPE: off `workspaceConfig` the target's gate is left alone;
  off an `apiGroup` it is CLEARED (an absent key there is written as the engine default). An
  unsupplied gate refuses a `deploy` and fails the export for a publishing group.
- `deploy --to workspace|tenant:<name>` skips the release flow to merge a LOCAL
  build in, keeping the checks that need one (`--dry-run`, `--prune`, loss warnings) and
  leaving nothing to roll back to. Prefer the release path.
  ⚠ Branches scope LOGIC: tables and microservices are shared by EVERY branch, so a
  schema change reaches production on any branch — refused without
  `--allow-shared-schema-changes` — and dropping a column destroys its data.
  ⚠ `--replace` CLEARS BY WORKSPACE, NOT BY BRANCH: every non-live branch goes, with the
  saved versions that would restore one — unrecoverable. Refused without
  `--allow-branch-deletion`; `--yes` does not imply it. The default merge leaves them alone.
- `workspace reset-tables <entry> --table <guid>` puts NAMED tables back to their
  compiled `table({ seed })` rows, touching no other table. Dry run unless `--write`.
  ⚠ ROWS BEFORE LOGIC: rows are workspace-shared like schema, so they reach production when
  applied, even while the logic reading them is staged. Reset rows FIRST, then `promote`.
- `pull` refreshes THIS project from a backend: rewrites decoded files,
  keeps yours, lists and confirms (`--yes`).
- `generate <source>`: the decoded tree ONLY, no project.
- `status` names the env this project last deployed to, its URL and its expiry.

**Frontend wiring.** `--static <dir>` (or `publish <dir>`) injects the env's backend URL as
`window.XANO_HOST` into EVERY html document in the build, before the app bundle runs,
so the frontend needs no rebuild to target an env. How to read it, local dev, verifying
the inject, and displaying a stored file: `llms/client.md`.
⚠ A static host serves its files verbatim, so everything injected is PUBLIC — base
URLs and publishable keys only, never secrets. Secrets go in backend env, read
server-side via `env(name)`.
⚠ `preflight` uses the deploy credential unless `XANO_VALIDATE_INSTANCE` /
`XANO_VALIDATE_TOKEN` (+ optional `XANO_VALIDATE_WORKSPACE_ID`) are set.

**Full CLI surface:** `npx @xano/sdk <command> --help` — every command, flag, default and accepted
backend; `manifest.json` carries the same in its `cli` array.
**Style:** reach statements through the `s` namespace (`s.db.add`, `s.math.add`, …).
The flat aliases (`dbAdd`, `setVar`, …) are identical in output; prefer `s.*`.

## Gotchas

Non-obvious authoring rules:

### Values and references

- **No callback builder.** Flat def-objects + `register*`, not
  `workspace(w => w.table(...))`. `workspace(name)` returns a named `new Xano()`;
  tables are `table({ schema: { col: f.text() } })`.
- **Foreign key is `f.tableRef(table)`, not `ref`.** `ref` = stack var (`as:` output),
  `inp` = input, `col` = table column (in `db.query` `where`), `auth("id")` = the caller,
  `c.*` = a constant; `f.tableRef` is the column constructor.
- **Tagged values are DATA — a JS template literal cannot compose them.** `${ref(...)}`
  (or `"a" + ref(...)`) stringifies the tag object at BUILD time: ``c.text(`Hi ${ref("u.name")}`)``
  type-checks and encodes the literal text `Hi [object Object]`, served verbatim.
  `export()` warns; `--strict` fails. Compose at RUNTIME:
  `withFilters(c.text("Hi "), fl.concat(ref("u.name")))`, an `obj({...})`/record member,
  or `c.expression('"Hi, " ~ $var.u.name')`.
- **Declare inputs with `input.<type>()`, read them with `inp("name")`.** `inp()`
  resolves ONLY against this def's own `input` block — a value produced earlier in
  the stack is `ref("var.field")`, not `inp("field")`. An undeclared name fails at
  runtime with `Unable to locate input` (`export()` warns).
- **`get_input`/`get_raw_input` read the whole payload**, not one named input
  (args are `{ as?, encoding?, excludeMiddleware? }` — no `name`). For a single
  input use `inp("name")`.
- **A `where` is a comparison, never a value.** To match every row, omit `where`. A value
  `where` — `c.bool(true)`, a text clause, or one built at run time (`inp("clause")`,
  `ref("built_where")`) — throws at build: the engine reads a filter only as a comparison
  tree and runs anything else over EVERY row. Bind run-time values as operands instead:
  `expr(col("status"), "=", inp("status"))`.

### Tables and columns

- **System columns are auto-injected.** `id` + `created_at` are prepended to
  every table (`system: true` by default); declaring them by hand is redundant.
  `id` is an `int` PK by default; pass `idType: "uuid"` on the table for a uuid key.
  Both are valid targets wherever a column name is accepted — `db.query` `sort`/
  `output`, a `db.get`/`edit`/`del` `fieldName`, etc. (the column-name type is
  `keyof schema | "id" | "created_at"`), and both appear in `InferRow<typeof table>`.
- **A column named `run` is reserved.** The table deploys and reads back fine, then
  EVERY `s.db.add` into it 400s — at any column type, with or without a value — and
  the error names the column while complaining about the VALUE. Use `run_id`. Exact,
  case-sensitive, one name: `Run`/`runs`/`run_id` are fine. `--strict` fails on it.
- **An input named `run` is reserved when a call passes it**: the callee gets
  defaults or a 400. HTTP binds it fine. `--strict` fails on it.
- **Numeric columns lose money quietly.** A normalized table's `f.decimal` reads
  `0.12345678` back as `0.12346`; `f.int` saturates at `9223372036854775807`
  instead of failing, both at HTTP 200. Hold money as a count of the smallest unit;
  exact bounds: `llms/fields.md`.
- **Self-referencing tables** need the bare-name form: inside `tweets`'s own
  schema, write `f.tableRef("tweets", { type: "int" })` — the `const tweets`
  handle isn't assigned yet, so the handle form throws "used before declaration".
- **Seed a table's starting rows with `table({ seed })`.** Rows typed against the
  schema, inline (`seed: [{ name: "…" }]`) or from a file (`seedFile("./seed.json",
  import.meta.url)`). Only `deploy` ships them, and a re-deploy re-seeds cleanly. Never
  put secrets in `seed`. Row shape, `id` pinning, and the file rules: `llms/fields.md`.
- **`f.password()` defaults to `access: "internal"`, so `db.get` does NOT return it.**
  A login stack that reads `ref("u.password")` after a plain `db.get` fails at runtime
  with `Unable to locate var: u.password` — the column is simply absent from the row.
  Name it in the read's `output` to pull it: `s.db.get({ table: users, fieldName: "email",
  fieldValue: inp("email"), output: ["id", "email", "password"], as: "u" })`, then
  `s.security.check_password`. `output` OVERRIDES column visibility — it is the only way to
  read an `internal` column, and `export()` warns when a stack reads one a `db.get` did not
  return.
- **Don't take a password through `input.password` on login — it double-hashes.**
  An `f.password()` column hashes on write, and `input.password` *also* hashes the
  submission on bind, so `s.security.check_password` compares two different hashes
  and a correct password always fails (`ok:false` on a found row). Take the submitted
  password as `input.text()` on both signup and login and pass the plaintext straight
  to `check_password` (which does the comparison hash itself). `export()` warns.

### Reading and writing rows

- **DB reads are field-match, not `where`-expr.** `db.get`/`db.edit`/`db.del`/
  `db.has`/`db.patch` match exactly ONE field: `{ fieldName, fieldValue }` (`fieldName`
  defaults to the PK `id`); there is no composite match. Only `db.query` takes a
  `where`/`additionalWhere` `expr(...)`; writes (`db.add`/`db.edit`/`db.add_or_edit`) take a
  `row`/`data`. For an `(a, b)` existence/fetch (e.g. dedupe a `(habit, date)` check-in), use
  `db.query({ where: [expr(col("habit"), "=", ...), expr(col("date"), "=", ...)], as })`
  (a `where` array is ANDed) and branch on the result. Signatures: `llms/statements-data.md`.
- **Drilling into a maybe-null `db.get` result 500s — use `ref(path, { safe: true })`.**
  `db.get` binds `null` on a no-match, but a nested `ref("owner.user_id")` raises a runtime
  "Unable to locate var" (HTTP 500) when `owner` is null — an ownership guard throws instead
  of failing cleanly (same for a `single` `db.query`; warns `stack.drill-maybe-null`). Two correct shapes:
  - Guard existence first — `guard.found("owner")` (a 404 precondition) — then drill WITHOUT `safe`.
  - Or drill null-safe inside an EXPRESSION or `obj()` operand:
    `expr(ref("owner.user_id", { safe: true }), "=", auth("id"))` yields `null` (the guard
    reads `false`) instead of 500ing. Works inside `obj({...})` too — no `s.set_var` hoist needed.
  ⚠ EXPRESSION and `obj()` operands ONLY — never a `db.*` match argument. `null` is not a
  legal `fieldValue`/`id`, so a chained get (fetch the child row, then its parent to check
  the owner) fails with HTTP 400 `Missing param: field_value` one statement BEFORE the guard.
  There guarding existence first is MANDATORY. `export()` warns on a safe ref in that position.
  ⚠ That is for a base that EXISTS and may be null. If the base binds nothing at all (a typo),
  `{ safe: true }` buries the bug as a silent `null` — `export()` warns with a did-you-mean;
  fix the name instead.
- **`output` selects from what the statement BINDS, and a PAGED `db.query` binds the
  envelope.** With `metadata: true` (the DEFAULT), the roots are `items.<column>` plus the
  counters you want kept: `output: ["itemsReceived", "curPage", "items.id", "items.title"]`.
  A bare column list there matches no envelope key, so ALL of them are dropped and the
  endpoint answers `[]` at HTTP 200 with no error — and a `response` reading
  `ref("rows.items")` then dies with `Unable to locate var: rows.items`. Prefix the columns,
  or set `metadata: false` inside `paging` to select the rows directly.
  `export()` warns; `--strict` fails.

### Stacks and calls

- **Block specials nest a `body`, not a `stack`.** `s.for`/`s.foreach`/
  `s.while`/`s.switch`/`s.try_catch`/`s.db.transaction`/`s.expect.to_throw`
  take their sub-stack as `body` (`try`/`catch`/`finally` for `try_catch`);
  `s.group(body)` and `s.util.post_process(body)` take it **positionally**.
  `s.for` is **count-bounded** (`{ as, count: <Value>, body }`), not from/to. See the
  authored signatures in `llms/statements-data.md`.
- **`s.api.call` / `s.task.call` / `s.trigger.call` / `s.workflow_test.call` are
  WORKFLOW-TEST ONLY.** Outside a `workflowTest({...})` stack the engine cannot reach
  the target, so one in a query/function/task deploys clean and then answers the first
  real request with `ERROR_FATAL: <Type> does not exist: <type>:<n>`. The failure is not per
  host kind: the same call inside a function that a query runs fails the same way.
  `export()` refuses them. `s.function.call`, `s.tool.call`, `s.middleware.call` and
  `s.addon.call` run anywhere, as does `s.function.run`. To share logic, put it in a
  `defineFunction` and `s.function.run` it — NOT `s.function.call`, which binds a failing
  target's error envelope instead of raising.
- **`expect.*` is a unit-test assertion; `s.expect.*` is a workflow-test statement.**
  A statement's `mock` is keyed by TEST NAME; an undeclared name throws. See `llms/tests.md`.
- **A helper returning `Statement[]` widens the stack and kills `InferResponse`.**
  Spreading `...requireX()` where the helper is typed `Statement[]` drops the stack's TUPLE
  type, so EVERY `ref()`/`as` in that stack — even ones after the spread — resolves to
  `unknown` and the response types as `StackTupleWidened`. Nothing fails at the helper; it
  surfaces where the response is consumed, often a frontend typecheck. Fix: return
  `statements(s.a(...), s.b(...))` — its tuple survives the spread. A helper that builds
  its array in a LOOP cannot be a tuple; declare `responseShape` on the query there.
- **Build regex-filter patterns with `c.regex(body, flags?)`, never `c.text`.**
  The regex filters (`regex_test`/`regex_match`/`regex_replace`/…) are PHP `preg_*`: the
  piped value is the PATTERN and must be delimiter-wrapped, and the ARGUMENT is the subject.
  Correct: `withFilters(c.regex(/^[a-z-]+$/i), fl.regex_test(inp("slug")))`.
  - A bare `c.text("^…$")` is an invalid pattern that matches *nothing* for every input, so
    a precondition on it rejects all values. `c.regex(body, "i")` (or a JS `RegExp`) wraps + escapes it.
  - Reversed (subject piped, pattern in the argument) type-checks and
    answers false for EVERY input, so an `if (matches) reject` guard admits what it refuses.
  - `withFilters` throws on both: a bare `c.text` pattern at ANY position in the chain (a
    normalizer in front does not add delimiters) and a pattern in the subject slot.
    `s.expect.to_match` is the same PATTERN slot, refused both ways. A `ref`/`inp` pattern is
    passed through untouched. `export()` warns on a reversed pair in stored bytes.
  - Prefer a native typed input (`input.email`) over hand-rolled validation.
- **An `auth()`-keyed limiter FAILS the request on any host with no caller identity —**
  **at every tier.** `s.redis.ratelimit({ key: withFilters(c.text("rl:"), fl.concat(auth("id"))), error: c.text("…") })`
  is the per-user form, and a public query, a task, or a function has no caller identity.
  It does not degrade to one shared bucket: on a public endpoint the FIRST call 403s,
  under `max`, and the host never runs. Key off `sys.remoteIp()` there. Attaching it
  at `apiGroup({ middleware })` or the workspace tier inherits the same failure onto
  every member endpoint. Export warns, naming the tier.

### Identity, build, and deploy

- **Same-name siblings collide — queries excepted: their identity carries group + verb.**
  Two functions (or tables, toolsets, …) sharing a name derive ONE guid and `export()`
  throws — give them DISTINCT names. A QUERY
  derives from `(api group, verb, name)`, the engine's own uniqueness: `GET items` +
  `POST items`, and `items` across two groups, coexist, and the lock keys the same
  composed identity (`query:blog|GET|items`) — changing a query's verb or group
  changes its identity. An explicit `guid` on a colliding pair clears the throw but
  is NOT a lasting fix: a lock entry cannot hold two guids, so `export --lock`
  refuses the pair (`export()` warns even unlocked); it is for pinning identity
  across a rename, not for sharing a name.
- **`export()` vs `emitBundle()` vs `writeBundle()`:** `export()` returns the object,
  `emitBundle()` the JSON, `writeBundle(app, path)` writes `export`'s file. All
  three run the SAME build-time checks, INCLUDING seed validation of a literal `seed: [...]`
  array (row shape, unknown column, coercion, enum membership, the all-or-nothing `id`
  rule). A DEFERRED seed — a thunk (`() => import("./seed.json")`) or `seedFile()` — is
  checked only by the `export`/`deploy` CLI path. Only `deploy` ships seed rows.
  - Entry points: the `node:fs` writers (`writeBundle`/`writeArtifact`) and lock-file I/O
    import from `@xano/sdk/node`, NOT the browser-safe `@xano/sdk` entry (a frontend
    imports from it; request types come from `routes.gen.ts`). `@xano/sdk/internal` is the
    compiler machinery, never needed to author. READING a bundle back is `@xano/sdk/bundle`
    — a statement walker (`2.if.0` paths), a structural hash, `mvp:*` catalog, `tableRefOf`.
- **Intra-workspace imports use `.js` specifiers** (`../tables/links.js`), not
  extensionless — the defs compile under `moduleResolution: bundler`. Add the `.js`.
- **Agents authenticate with env vars — never `npx @xano/sdk login`.** `login` blocks on a
  browser consent no agent can complete. Set all three of `$XANO_INSTANCE_URL`,
  `$XANO_WORKSPACE_ID`, `$XANO_META_TOKEN` and run `deploy`/`promote` directly: no disk, no
  rotation, so it survives repeated runs.
  - The triple outranks every other credential (`--config`, `$XANO_PROFILE` and
    `$XANO_REFRESH_TOKEN` included, each named on stderr when displaced). Setting SOME of the
    three is a hard error, so a misspelled secret cannot fall through to whatever credential
    the runner has. An explicit `--profile` against it is a hard error too, not a displacement.
  - On disk: `npx @xano/sdk profile add <name> --instance … --workspace-id <n>` reads the token
    from piped stdin, else PROMPTS (a flag would reach the process list); the instance must accept it.
    `auth.json` holds a map of named profiles, selected by `--profile <name>`.
    `$XANO_REFRESH_TOKEN` + `$XANO_CLIENT_ID` also authenticate, but the refresh token is single-use (it ROTATES).
- **Event-driven objects run once deployed.** A `task` (scheduled), an `mcpServer`, and
  every trigger — `tableTrigger` included — run on every deploy target, the Xano Engine and
  an ephemeral alike. Test an event-driven design (screen-on-insert, scheduled cleanup, MCP
  tool call) by deploying it and letting it run.

## Statements

Reachable through the `s` namespace: `s.<path>({...})`. Declarative statements
take one typed args object (field names match the engine); every surface's field
signature is in `llms/statements-catalog.md` (`s.ai.*`: `llms/statements-ai.md`). Specials (`[special]`) are
hand-authored: control flow is below, the rest are in the `llms/statements-*` topic files.
Fields marked `value` take a `Value` (`c.*`/`ref`/`inp`); `comparison` takes an
`expr(...)`. A `→ as: <type>` suffix names what the statement's `as:` output var
holds (curated, not exhaustive — absence means read the `[output]` flag and prose).
`ignored(...)` around an `input`-routed `value` field stores it but SKIPS it at runtime: the
engine records `<name>:ignore` and the parameter takes its default. Distinct from an empty
value and from omitting the field (no entry stored). Mostly seen on a pulled workspace. On a
`context`-routed field (the `s.math.*`/`s.text.append` mutation family) `ignored(...)` THROWS:
there is no slot for the flag.

### Specials — authored signatures

Control flow & blocks (each nests a sub-stack; block specials name it `body`):

- `s.set_var(name, value)` · `s.update_var(name, value)` · `s.return(value)` · `s.comment(text)` — positional.
- **Every** statement takes `disabled?`/`description?` — annotations on the stack item, not args: `disabled: true` is Xano's "disable step" (kept in the stack, skipped at runtime), `description` the note beside it. Inline on object-arg factories; a trailing object on the positional ones (`s.set_var("x", v, { disabled: true })`).
- **Statements with an `as`** also take `asFilters?` — `fl.*` filters on the RESULT as it binds, in order, same slot as `disabled`: `s.set_var("x", v, { asFilters: [fl.trim(), fl.lower()] })`. Saves a follow-up `set_var`. Throws without an `as`. The bound variable is RETYPED by the chain (`db.query` + `[fl.count()]` → `number`); filters whose result the engine declares as `any` (`get`, `set`, `json_decode`, …) fold to `unknown`.
- `s.conditional({ when, then, elif?, else? })` — if/elif/else. `when` is a condition (`expr`/`cmp`/`and`/`or`); `elif` is an ordered `[{ when, then }]` (each an else-if branch); `then`/`else` are `Statement[]`.
- `s.for({ as, count, body })` — **count-bounded** loop (`as` is the index), NOT from/to; `count` is a `Value`, not a bare number.
- `s.foreach({ as, list, body })` — iterate `list`; `as` is the current item.
- `s.while({ when, body })` — `when` is a condition (`expr`/`cmp`/`and`/`or`).
- `s.switch({ on, cases: [{ when, body, break? }], default? })` — multi-way branch on a subject `Value` `on`; each `case`'s `when` is a literal `Value` matched against `on` (NOT a comparison — use `s.conditional` for `<`/`>`/ranges). ⚠ **Omitting `break: true` FALLS THROUGH** — the matched case also runs every LATER case body. Type-checks clean; only `export --strict` catches it.
- `s.try_catch({ try, catch?, finally? })` — three `Statement[]` blocks.
- `s.group(body)` / `s.util.post_process(body)` — take a `Statement[]` **positionally**.
- `s.foreach_break()` / `s.foreach_continue()` / `s.foreach_remove()` — nullary loop control.
- `s.expect.to_throw({ body, exception? })` — `body` is the statements expected to raise; `exception` is a `Value`, not a bare string.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.