# weir init — scaffold a new app in under a minute

`weir init` is the first command a new integration runs: give it an app id and a platform, and it
writes a valid `weir/app.json`, a working starter flow, and the flow's built baseline bundle. For
a delivery-backed integration, first export the supplied delivery origin and app token: init uses
them to write `weir.config.json` with that origin's manifest URL and pinned public key. Run it
right after [installing the toolkit](/docs/install/), before you hand-author anything.

It reuses `weir_app_scaffold`'s scaffold logic exactly (same files, same doctor-ready guarantee)
and is registered under both names; `weir init` is the discoverable "first five minutes" name.

## Invocation

### Delivery-backed app (React Native/Expo and production-like local stacks)

Export these values **before the first init**, then run init once. They are deliberately environment
variables rather than flow fields, so they cannot be committed with the app configuration:

```sh
export WEIR_API_URL="<the supplied local or delivery API URL>"
export WEIR_API_TOKEN="<the supplied app token>"
./node_modules/.bin/weir init --appId my-app --platform reactNative --appRoot . --acknowledgePrivateRuntime
```

For a delivered/private toolkit, invoke **only** the binary in this app's
installed kit: `./node_modules/.bin/weir`. Do not use a bare `weir` command
from your shell PATH; a globally installed toolkit can be older or a different
build and may silently write a different scaffold. The rest of this page uses
`weir` as shorthand for that local binary.

Confirm that both `weir/app.json` and `weir.config.json` now exist before editing the starter
flow. Do not run `weir init --force` after beginning integration: it overwrites the scaffold and
starter flow. If the first init was missing its delivery settings, restore the clean app checkout,
export both values, then run the single normal init again.

### Offline scaffold

For a source-only offline scaffold with no delivery origin, use the normal invocation below. It does
not create a deployment-pinned `weir.config.json`; add delivery credentials before a real publish.

As an MCP tool (from an agent host with the Weir MCP server registered — see
[Install the toolkit](/docs/install/)):

```
weir_init({ appId: "my-app", platform: "ios" })
```

As the CLI (identical behavior, same field names):

```
weir init --appId my-app --platform ios
```

## Arguments

| Field | Required | Default | Meaning |
|---|---|---|---|
| `appId` | yes | — | New app id. Used in `weir/app.json`, the feature-flag name, and (sanitized) the starter paywall's product id. |
| `appRoot` | no | current working directory | Root directory of the host app to scaffold `weir/` into. |
| `platform` | no | `"ios"` | `"ios"`, `"android"`, or `"reactNative"`. Only iOS has a public runtime; the other values are private design-partner contracts. |
| `appVersion` | no | `"1.0.0"` | The host app's semantic marketing version in exact `x.y.z` form, used for compatibility status. |
| `acknowledgePrivateRuntime` | no | `false` | Required for Android or React Native. Confirms you already understand that no public runtime can be acquired; it does not install or grant the private runtime. |
| `flowId` | no | `"onboarding"` | Id for the starter flow; also its spec file name (`weir/flows/<flowId>.json`). |
| `placement` | no | `"launch"` | Where this flow is presented from, e.g. `"launch"` or `"verdict_ready"`. |
| `force` | no | `false` | Overwrite an existing `weir/app.json` and starter flow spec. Without it, `weir init` refuses to run a second time over an existing scaffold. |

## What it writes

```
<appRoot>/
  weir/
    app.json                     # complete, valid weir/app.json — parses against weirAppConfigSchema
    flows/
      onboarding.json            # starter specVersion-4 flow: welcome -> paywall (stock screen types only)
    config/
      onboarding/
        config.json              # native v4 baseline config embedded by the host app
```

The starter flow already passes `@x/spec`'s `validate()`/`normalizeFlow()` and the full
`weir_conform` gate (a persona walk reaches `complete()`, the event stream matches the manifest,
perf budgets and native-feel checks hold). So `weir_app_doctor`, run immediately after `weir init`,
reports `sourceContractReady: true` with `readinessKind: "source-contract-only"` and zero failures. This is not a runtime or shipping verdict. No `integrationFile` is scaffolded — wiring
`Weir.configure`/`present` into the host app is deliberately left to you — so the doctor's
`native-adapter` check only warns ("integrationFile not declared") until you add one.

## Output and next steps

`weir init` prints a JSON result with `scaffolded: true`, the resolved `appId`/`platform`/
`flowId`, the paths it wrote, and a `next` array of agent-legible next steps:

1. **Wire the native SDK.** Add `integrationFile` inside that flow object in `weir/app.json` once you call the printed platform-specific SDK API; the doctor's `sdk-use` check fails the source contract if that file exists but never calls the SDK.
2. **Validate the contract:** `weir app-doctor --appRoot <app-root>`.
3. **Optional browser QA only:** `weir dev --specPath <app-root>/weir/flows/<flow-id>.json --serve`. This previews mocked native behavior; it does not validate native embedding.
4. **Learn the flow vocabulary before editing:** `weir schema` for all screen types and flow fields, or `weir schema <screenType>` for one type.
5. **Replace the starter screens.** Edit `weir/flows/<flow-id>.json`, rebuild `weir/config/<flow-id>/config.json` from the normalized v4 spec, then re-run `weir app-doctor`.
6. **Test the publish path with no account and no network:** `weir release --appRoot <app-root> --flowId <flow-id> --dryRun` (builds once, runs the full conform gate, never calls any API).
7. **View the flow in a real local dashboard:** `weir dashboard` starts a dev-mode local API and dashboard UI, signs you in automatically, and prints the URL to open. It requires Node.js 22+; other toolkit commands work on Node 18+.
8. **Publish for real** once you have a token: get one from the Weir dashboard, set `WEIR_API_TOKEN`, then run `weir release --appRoot <app-root> --flowId <flow-id>` (drop `--dryRun`).

## Re-running

`weir init` refuses to overwrite an existing `weir/app.json` or starter flow spec unless
`force: true` is passed — safe to run once per app id without silently clobbering hand-edited
files.

## See also

- [Install the Weir skill / MCP server](/docs/install/) — register the tools first.
- [Onboard an app](/docs/onboard-an-app/) — the full `weir/app.json` contract, monorepo
  `--appRoot` conventions, and Android SDK/wiring details.
- [Run everything locally](/docs/local/) — why every step above works with zero network and zero
  account.