Agent manual

You are helping a developer add offline-first sync to their app with SyncPilled. Each person's records sync across their devices; the latest edit of a record wins; files sync by content hash.

Get accessCopy Anchor Link

• Hosted: the developer runs syncpilled login and approves in the console. Never ask for their password.
• Self-hosted behind Cloudflare Access: the developer makes a management key in the console and gives it to you through a file or SYNCPILLED_KEY. Never print it.
• Check with syncpilled whoami --json.

Add an appCopy Anchor Link

1. Find the app's sign-in provider in its code (Firebase, Supabase, Auth0, Clerk, Sign in with Apple, or another issuer).
2. syncpilled apps create --name "<name>" --firebase <project id> --json (or --supabase, --auth0 <domain> --audience <api>, --clerk, --apple <bundle id>, --issuer <iss> --audience <aud> --jwks-url <url>).
3. Note the id it answers. Use separate apps for development and production builds.

Wire the iOS appCopy Anchor Link

1. Add the SyncPilled Swift package: the syncpilled-swift folder of the SyncPilled repository, as a local package.
2. Create SyncPilledClient(baseURL:appId:issuerToken:) with the deployment's API address, the app id, and a closure returning a fresh sign-in token.
3. Write a SyncDataSource: snapshot() returns every synced record as LocalRecord (collection, stable id, JSON data, updatedAt, files); apply(_:unchanged:) writes incoming records, calling unchanged for each in the same step as writing it, and returns the keys written.
4. Call engine.sync() at launch, on returning to the foreground, and after saves. On sign-out call try await engine.forget() and await client.resetSignIn().
5. On SyncPilledError.accountDeleted, forget and erase local data.

Rules to respectCopy Anchor Link

• Collections are lowercase letters, digits and underscores.
• A record is at most 256 KB of JSON by default; a file at most 10 MB. A larger record fails the whole push with 413, so keep records small.
• Do not set per-person limits or allowed collections until the shipped app uses Swift package 0.2 or later: older clients stop syncing at a refusal.
• Deleting an app or a person (--yes) erases data for good. Ask the developer first, every time.

Check it worksCopy Anchor Link

• syncpilled stats <app> --json: people and records rise after a device syncs.
• syncpilled people list <app> --json: the test account appears.

APICopy Anchor Link

Everything the CLI does is in the OpenAPI document at /openapi.json. Errors are { "error": { "code", "message" } }; 429 carries Retry-After.