# Command line

The expo-svelte command, with init, doctor, push, android, ios, dev, build, sync and css.

Expo Svelte's command line is `expo-svelte`. Run it from your app's directory, through pnpm:

```sh
pnpm exec expo-svelte <command> [options]
```

`expo-svelte init` adds four scripts to `package.json`, so the common commands are shorter:

```json
/// file: package.json
{
	"scripts": {
		"native": "expo-svelte dev",
		"android": "expo-svelte android",
		"ios": "expo-svelte ios",
		"check-setup": "expo-svelte doctor"
	}
}
```

`pnpm android`, `pnpm ios`, `pnpm native` and `pnpm check-setup` run them. The web app's scripts (`dev`, `build`, `preview`, `check`) are left alone, so `pnpm dev` is still `vite dev`.

> **warning** Don't name a script `doctor`, and don't run `pnpm doctor`: that is pnpm's own command, which checks pnpm, not your app. Use `pnpm exec expo-svelte doctor` or `pnpm check-setup`.

`android`, `ios` and `dev` turn Expo's TypeScript setup off, and Expo prints a line saying it skipped it. That setup is for React apps: in an app without `@types/react`, it stops the first run to ask whether to install it. A Svelte app's TypeScript is SvelteKit's (`tsconfig.json` and `svelte-check`), and building or running the app doesn't need `@types/react`. To have Expo's setup anyway, set `EXPO_NO_TYPESCRIPT_SETUP=0` in your environment.

## init

```sh
pnpm exec expo-svelte init [options]
```

Turns a SvelteKit project (from `npx sv create`) into an Expo Svelte app. Run it after installing the library. It prints its plan, then:

- adds the dependencies, `main` and the scripts to `package.json`, and pins Svelte and SvelteKit to the builds Expo Svelte needs;
- adds pnpm's `overrides` and `patchedDependencies` to `pnpm-workspace.yaml`, and copies the patches into `patches/expo-svelte/`;
- creates `metro.config.cjs` and `app.json`, or adds the library's plugin to the `app.json` you have (an `expo-svelte/expo` entry, which no longer resolves, becomes the package's name);
- wraps SvelteKit's plugin in `vite.config.ts` with `expoSvelte()`;
- creates a first app if `src/routes` has no native routes: a root layout, a home screen, a details screen and `src/lib/theme.ts`;
- adds the generated folders to `.gitignore`;
- runs `pnpm install` and then `expo-svelte doctor`.

[Configuration](configuration.md) shows each of these changes.

| Option | Description |
| --- | --- |
| `--dry-run` | Print the plan and write nothing. |
| `--name <name>` | The app's display name. Default: the package name. |
| `--android-package <id>` | The Android application id. Default: `dev.example.<package name>`. |
| `--ios-bundle-id <id>` | The iOS bundle identifier. Default: the same as the Android one. |
| `--no-install` | Write the files, but don't run `pnpm install` and the doctor. |
| `--force` | Replace a `main` field that `init` would have written differently. |

`dev.example.…` is a placeholder: set your own identifiers before you publish the app.

Run `init` again whenever you like. In a project that's set up it prints `Nothing to change`. After an upgrade of Expo Svelte it copies the new patches and versions in. It never overwrites a change of yours without saying so: when a file has a shape it can't edit safely (a `vite.config.ts` that isn't what `sv` writes, an `app.config.ts`), it leaves the file alone, prints the exact change for you to make, and exits with status 1.

`init` also works in an existing Expo app, without SvelteKit: see [Adding to an existing Expo app](adding-to-an-existing-expo-app.md).

## doctor

```sh
pnpm exec expo-svelte doctor [--json]
pnpm exec expo-svelte doctor --server [--app <bundle id>] [--json]
```

Checks that the app is set up as Expo Svelte needs, and changes nothing. It prints one line per check, grouped:

```
expo-svelte doctor: /home/you/my-app

environment
  pass  node 24.18.1 (needs ^22.17.0 || ^24.3.0 || >=26.0.0)
  pass  pnpm 12.3.4 (needs >=12.3.4)

svelte
  pass  svelte 5.56.7 has the ./renderer export and the customRenderer compiler option

peer dependencies
  pass  react-native 0.86.3 satisfies 0.86.3
  …
  FAIL  react 19.2.6 does not satisfy 19.2.7
        fix: pnpm add react@19.2.7

vendored packages
  pass  react-native-mmkv 4.3.1 comes with expo-svelte (vendor/react-native-mmkv); the app does not list it
  …
  pass  libraries turned on: expo-image, react-native-maps; the others are not linked, and Metro stubs them

patches
  pass  expo-modules-core@57.0.23 applied: Expo modules register lazily and the common ones are prewarmed (Android start)
  …

build integration
  pass  expo-svelte 0.4.0-rc.10 is a dependency of the app
  pass  metro.config.cjs uses withExpoSvelte
  pass  app.json lists the expo-svelte plugin

21 passed, 1 failed, 0 could not tell, 1 skipped
```

| Status | Meaning |
| --- | --- |
| `pass` | The check passed. |
| `FAIL` | The check failed. The line below it says how to fix it. |
| `skip` | Nothing to check, such as an optional package you haven't installed. |
| `????` | It couldn't tell, such as a Metro config that applies the library from another file. |

It checks Node and pnpm; that Svelte is the custom-renderer build; the versions of the peer dependencies; that each patch is applied to the installed package (not just declared); that the packages Expo Svelte carries are all there and patched, that the app doesn't list one of them, and which of the optional libraries its config turns on; that Metro and Expo are wired up; and, for an app that has push, its push setup (below). It exits with status 1 when a check failed, and 0 otherwise. `--json` prints the same checks as JSON.

Run it after an install that went wrong, after an upgrade, and before you report a bug. [Troubleshooting](troubleshooting.md) explains the failures you're likely to see.

### The push section

An app has push when its `app.json` turns `capabilities.push` on, or, for an app whose config is code, when the last prebuild turned push on (the flags it writes in the Android manifest and the iOS `Info.plist`). For any other app the doctor prints no push lines at all. The section reads files and runs nothing, like the rest of the doctor:

```
push
  pass  no other push library (expo-notifications, @react-native-firebase/messaging) is installed
  pass  app.json turns capabilities.push on (android, ios)
  pass  google-services.json is JSON and holds no server secret (Firebase project my-app)
  pass  google-services.json has a client for the app's package "dev.example.app"
  pass  ios/App/App.entitlements has aps-environment production
  pass  ios/App/Info.plist lists remote-notification in UIBackgroundModes
  pass  the last prebuild turned push on for android: android/app/src/main/AndroidManifest.xml (expo.modules.sveltepush.enabled)
  pass  the last prebuild turned push on for ios: ios/…/Info.plist (SveltePushEnabled)
```

| Check | Fails when |
| --- | --- |
| One push library | `expo-notifications` or `@react-native-firebase/messaging` is installed while `capabilities.push` is on. |
| The capability | `capabilities.push` in `app.json` is what the config plugin refuses (a secret, no platform named, a malformed `android` or `ios`), with the plugin's own message; `????` when an `app.config.*` may change it. |
| The Google services file | It's a server secret (`"type": "service_account"`, a `private_key`, a PEM key): the fix says to delete it, revoke the key, and keep it in the server's environment. Or it isn't JSON, or isn't where the config says. |
| Its client | It has no client for the app's Android package (`android.package` in `app.json`, else `applicationId` in `android/app/build.gradle` after a prebuild). |
| The entitlement | After a prebuild (an `ios/` folder), the app's `.entitlements` has no `aps-environment`, or has another mode from `capabilities.push.ios.mode`: the prebuild is older than the config. |
| The background mode | After a prebuild, `Info.plist` has no `remote-notification` in `UIBackgroundModes`. |
| The prebuild | A platform `capabilities.push` names whose native project the last prebuild wrote without push (no `expo.modules.sveltepush.enabled` in the Android manifest, or no `SveltePushEnabled` in `Info.plist`): prebuild again. |

The doctor can't run `app.config.ts`. It finds the Google services file the way it can: the one `app.json` names (`capabilities.push.android.googleServicesFile`, or `android.googleServicesFile`), else a `google-services*.json` in the app's directory, else the prebuild's copy in `android/app/`. When the config is code and there is no such file, the line is `????` (it couldn't tell) with the fix. With no `ios/` folder yet, the iOS checks are `skip`.

### doctor --server

```sh
pnpm exec expo-svelte doctor --server [--app <bundle id>] [--json]
```

Checks the push sender's environment on the machine you run it on, which is normally the server (or a shell with the server's variables). It checks only that, not the app: run it without `--server` for the app. It reads the variables `createPush` is given in the guide's example, and then makes one real request to each provider you've set up:

| Variable | What it is |
| --- | --- |
| `FCM_SERVICE_ACCOUNT` | The service account key's JSON, or the path of its file. It needs `project_id`, `client_email` and an RSA `private_key`. |
| `APNS_KEY` | The `.p8` key's PEM, or the path of its file. A PEM with its line breaks written as `\n` is accepted. It must be a P-256 key. |
| `APNS_KEY_ID` | The key's id: 10 letters and digits. |
| `APNS_TEAM_ID` | The Apple Developer team's id: 10 letters and digits. |
| `FCM_BASE_URL`, `FCM_TOKEN_URL`, `APNS_PRODUCTION_URL`, `APNS_SANDBOX_URL` | Optional. Replace the provider's endpoint, as the sender's `baseUrl`, `tokenUrl`, `productionUrl` and `sandboxUrl` options do (tests and proxies). |

```
expo-svelte doctor --server

push server
  pass  FCM_SERVICE_ACCOUNT is a service account key for project my-app (push@my-app.iam.gserviceaccount.com) with a private key that loads as RSA
        read from the variable's text
  pass  oauth2.googleapis.com gave an access token for push@my-app.iam.gserviceaccount.com (valid 3599 s): Google accepts the key
  pass  APNS_KEY loads as a P-256 key; key id ABC123DEFG, team id TEAM123456
        read from the variable's text
  pass  api.sandbox.push.apple.com accepted the credentials: it signed in the provider token and then answered BadDeviceToken to a device token that cannot exist
```

- **FCM:** the variable must parse as a service account key and its private key must load. Then the doctor makes the OAuth token request that every send starts with, to the key's `token_uri`. Google's refusal says why: `invalid_grant` is a key that was deleted or disabled, a service account that is gone, or a clock that is off, and the fix names which.
- **APNs:** the three variables must be set together and the key must load as an ES256 key. APNs has no token endpoint, so the doctor signs a provider token and sends one request to the sandbox host (`api.sandbox.push.apple.com`) with a device token that can't exist. `BadDeviceToken` means APNs accepted the credentials (it read the provider token before it judged the device). `InvalidProviderToken`, `ExpiredProviderToken` and the other 403s mean it didn't, and the fix says what to check. Nothing is delivered.
- `--app` is the app's bundle id, which is the request's APNs topic. Without it the topic is a placeholder, and if APNs answers `TopicDisallowed` or `BadTopic` the line is `????`, because it didn't get as far as the credentials. With `--app`, the same answer is a failure.
- A provider whose variables are unset is `skip`. If neither is set, the doctor fails: a server that can't send is not fine. A provider that can't be reached is a failure. A rate limit is `????`.
- A variable that is a path loads, but the sender in your server's code takes the contents, not the path (`createPush({ fcm: { serviceAccount: env.FCM_SERVICE_ACCOUNT } })`). The line says so: the server's own variable must hold the text.
- Nothing is written, and no key or token is printed in full. A line names a project, an email, an id or a host, and a variable that doesn't load is named, never quoted.

The exit status is 1 when a check failed, and 2 for an argument it doesn't know. `--json` prints `{ ok, server: true, checks }`.

## push

```sh
pnpm exec expo-svelte push send --token <token> [options]
```

Sends one message to one device with the server's credentials, to try a device before the server's own code does it. It's `createPush(...).send(...)` from `expo-svelte/push/server` and nothing else, and it prints what the provider answered. It needs no routes, and writes nothing into the app. Run it from any directory, with the variables of `doctor --server` set (the sender's endpoints included).

```sh
export FCM_SERVICE_ACCOUNT=./secrets/firebase-service-account.json
expo-svelte push send --token '{"provider":"fcm","token":"…","app":"dev.example.app"}' \
  --title "Order ready" --body "Pickup at gate 3" --url /orders/42
```

```
sent to fcm (dev.example.app): 0:1700000000%31bd1c96
```

The credentials come from the environment and never from the command line, so no key lands in a shell history. An FCM token needs `FCM_SERVICE_ACCOUNT`; an APNs token needs `APNS_KEY`, `APNS_KEY_ID` and `APNS_TEAM_ID`. They're read as `doctor --server` reads them, a path or the text. The variables of the other provider aren't looked at.

| Option | Description |
| --- | --- |
| `--token <token>` | The device. Either the JSON of a `PushToken` exactly as `push.subscribe`'s `save` received it, or a raw token string with the three options below. |
| `--provider fcm\|apns` | A raw token's provider. |
| `--app <id>` | A raw token's app: the Android package, or the iOS bundle id (the APNs topic). |
| `--environment development\|production` | A raw APNs token's environment, which picks the APNs host. It's needed for an APNs token: the other host answers `BadDeviceToken`. |
| `--title <text>`, `--body <text>` | The notification's text. It needs one of them, unless it is `--silent`. |
| `--url <link>` | The link a tap opens: a path of the app (`/orders/42`) or a full link. |
| `--data <key=value>` | A data entry. Repeat it for more. Strings only. |
| `--silent` | A data message: nothing is shown, the app's `background` hook gets it. It takes no title, body, badge, sound or channel. |
| `--badge <n>` | iOS: the badge number. |
| `--sound default\|none` | `none` sends no sound. |
| `--channel <id>` | Android: the notification channel's id. |
| `--collapse-key <key>` | A newer message with the same key replaces the older one. |
| `--priority high\|normal` | The provider's priority. |
| `--ttl <seconds>` | How long the provider keeps the message for a device that is offline. |
| `--json` | Print the result as JSON: `{ "ok": true, "id": … }`, or `{ "ok": false, "reason": …, "detail": …, "status": … }`. |

A flag takes its value as `--title "Order ready"` or `--title="Order ready"`; a value that starts with `--` needs the second form.

On a failure it prints the result's `reason` and `detail` with what to do about it (`gone`: delete the token; `auth`: run `doctor --server`; `rate-limited`: when to retry). The reasons are the sender's.

| Exit status | Meaning |
| --- | --- |
| 0 | The provider accepted the message. |
| 1 | The provider didn't: the result's `reason` says why (`gone`, `invalid-token`, `invalid-message`, `rate-limited`, `unavailable`, `auth` or `error`). |
| 2 | Nothing was sent, because the command or its environment isn't usable: an argument is wrong, the sender refuses the message (a notification with neither title nor body, a `--silent` message with a title, `url` also given in `--data`), or the credentials aren't set or don't load. |

## android

```sh
pnpm exec expo-svelte android [expo run:android options]
```

Builds the app and runs it on an Android device or emulator:

1. Regenerates `.expo-svelte/` (see [sync](#sync)).
2. Runs `expo run:android`, which prebuilds `android/` if it doesn't exist, compiles the app with Gradle, installs it, starts Metro and opens the app.

Every option goes to `expo run:android`. The useful ones:

| Option | Description |
| --- | --- |
| `--device [name]` | Pick a device. Without a name, it lists them. |
| `--variant release` | Build a release build, with the JavaScript inside. |
| `--port <port>` | Metro's port. Default 8081. |
| `--no-bundler` | Don't start Metro. |

It only prebuilds when `android/` is missing. After a change to native configuration, run `pnpm exec expo prebuild` yourself: see [Development builds](development-builds.md#when-to-run-expo-prebuild).

## ios

```sh
pnpm exec expo-svelte ios [expo run:ios options]
```

The same as `android`, for iOS, on a Mac with Xcode. Every option goes to `expo run:ios`: `--device [name]` picks a simulator or a connected iPhone, and `--configuration Release` makes a release build.

## dev

```sh
pnpm exec expo-svelte dev [expo start options]
```

Starts Metro, the development server, for an app that's already installed. Open the app and it loads its JavaScript from Metro. A save reloads the app.

`dev` regenerates `.expo-svelte/` first, and again whenever a `+mobile.svelte` or `+layout.mobile.svelte` file is added, removed or renamed, so new routes appear without a restart. Every option goes to `expo start`: `--port <port>` sets the port, and `--clear` starts with empty caches.

A phone on USB needs a tunnel to Metro's port: `adb reverse tcp:8081 tcp:8081`.

## build

```sh
pnpm exec expo-svelte build --platform android|ios
```

Bundles the app's JavaScript for release, as Hermes bytecode, without building the native app. The output goes to `.expo-svelte/dist/<platform>/`: `index.hbc`, its source map `index.hbc.map`, and the `assets/` folder. `--platform` defaults to `android`.

A release build made with Gradle or Xcode bundles the JavaScript itself, so you don't need this command for that. Use it to look at the bundle, or to check that it builds.

## sync

```sh
pnpm exec expo-svelte sync
```

Only regenerates `.expo-svelte/`:

- `entry.ts`, the app's entry point, which `main` in `package.json` names;
- `routes.app.ts`, the route table: every `+mobile.svelte` and `+layout.mobile.svelte` under `src/routes`, with the `presentation` and `navigator` they export.

The other commands, and Metro itself, do this for you. Run `sync` when a tool reads `.expo-svelte/` without going through them, such as a type check in CI. A route tree that breaks a rule (a page next to a navigator layout, a tab bar inside a tab bar, ...) fails here with the file's name.

## css

```sh
pnpm exec expo-svelte css src/global.css
```

Compiles the CSS file the way Metro's `css` option does (Tailwind 4, then React Native styles) and writes the class table to `.expo-svelte/classes.<variant>.ts`. Metro already runs it when it starts and when a file changes, so you need it only to see what a file compiles to.

| Option | What it does |
| --- | --- |
| `--variant <name>` | The variant to write the table for (`APP_VARIANT`; `app` when unset). |
| `--json` | Print what happened as JSON: the file written, whether it changed, the classes that aren't supported and the stylesheets read. The file is written either way. |
