@expo/snapback-cli

Snapback is a complete application backend: declare a schema and server functions, generate typed clients, then run queries, mutations, live data, auth, and local-first behavior through one coherent development loop. It is designed to scale to zero for prototypes and back up for real applications.

Start a project

Install the CLI, scaffold an app, and install the generated dependencies:

npm install --global @expo/snapback-cli
snapback new my-app --template react
cd my-app
bun install

Use --template todo-contract for the Contract todo starter, or --template expo-chat for the golden-path Expo conversation starter (messages with image upload, live queries, the generated conversation surface, and typing presence).

The golden path

1. Declare tables, fields, indexes, and sync policy in snapback/schema.mjs.

2. Define queries and mutations in snapback/functions.mjs.

3. Generate the typed artifact graph:

   bun run generate

4. Start codegen, the backend, artifact loading, and file watching:

   bun run dev

5. In another terminal, run the starter's first query against the managed ready file:

   snapback run --ready-file .snapback/dev.ready.json listTodos

This anonymous public form sends no userId, session bearer, lease, or admin credential to the application query route. The ready-file admin token reaches host-ops first so the CLI can resolve the target, but it is not forwarded to the query route. On the default sessions scaffold the command succeeds only when the query admits an anonymous caller; authenticated queries remain fail-closed.

For an authenticated sessions-mode query, mint a local test session from a trusted terminal, then give the returned data.token to the first-party external-session client in trusted server/test code:

snapback session mint --ready-file .snapback/dev.ready.json \
  --email [email protected]

import { createExternalSessionClient } from '@expo/snapback-client/online';
import api from './snapback/generated/api.mjs';

const baseUrl = process.env.SNAPBACK_URL;
const bearerToken = process.env.SNAPBACK_SESSION_BEARER;
if (!baseUrl || !bearerToken) throw new Error('missing trusted test session');
const client = createExternalSessionClient(baseUrl, {
  bearerToken,
});
const result = await client.query(api.myAuthenticatedQuery, { args: {} });
await client.close();

Set SNAPBACK_URL from the readiness descriptor's serverUrl and SNAPBACK_SESSION_BEARER to the mint response's data.token. Keep both the mint result and bearer out of browser/native bundles and logs.

An optional-user operation can admit an anonymous caller and still require a user in its implementation. In particular, a query that dereferences authUserId() needs snapback session mint plus createExternalSessionClient; without that session it fails closed with SNAPBACK_AUTH_USER_MISSING.

snapback run --user <id> ... is only for an auth: { mode: 'dev' } backend. Sessions mode deliberately rejects that client-asserted identity; use the mint plus createExternalSessionClient path instead.

For ordinary completion, run bun run prove, the only done-oracle; it writes the authoritative aggregate snapback verify receipt (acceptance evidence, not formal proof). npm test runs the raw starter acceptance that prove wraps for debugging, while bun run test:static checks no-server source/generated coherence. Available bun run carry:* commands drive browser or simulator observation only after accepting the prove receipt; their artifacts are not proof authority.

Documentation outside a checkout

A running Snapback server serves the Guide compiled into that exact build. These links use the first default development port; use the origin printed by snapback dev or snapback start if yours differs.

• Read first: the start packets — the budgeted per-template first read (LLP 0259).
• Look up (do not linear-read) the capability index so you do not rebuild a feature that already exists.
• Follow your first backend or browse the Guide index.
• Fetch the complete agent-oriented projection at flat.md.
• Run snapback guide for these channels or snapback guide <query> to search the embedded Guide by section.
• Run snapback mcp to expose the same build-bound corpus as read-only MCP resources, starting at snapback-guide://manifest.

Operate it

snapback mcp serves read-only Guide resources; snapback mcp-control adds typed control tools with local admin authority. Preview control setup with snapback agent setup --print <client> --server mcp-control.