Troubleshooting

When an app misbehaves under Peach, the first questions are always “what am I running?” and “is there a newer build that fixes it?”. These commands answer both, and surface what just happened inside the running sim.

#Check what you’re running

peach version

Prints the CLI version and the active engine runtime version, and tells you when either has a newer release:

peach v0.1.172 · public beta
installed runtime v0.1.494 · stable
  ↑ CLI v0.1.176 available; run `peach upgrade`
  ↑ default runtime v0.1.498 available; run `peach upgrade`

The CLI and the engine runtime are versioned separately. Most fixes ship in the runtime, which updates independently of the CLI.

#Get the latest after a fix lands

If you reported an issue and were told it’s fixed in a newer runtime, pull it:

peach upgrade

This updates the CLI only when a newer CLI exists and downloads, installs, and activates the latest engine runtime from the CDN. It ends by printing the runtime release notes in the terminal. A running daemon checks for new runtimes on startup and hourly and hot-swaps automatically, so you often get a fix without doing anything. Successful interactive commands also refresh a cached CLI release check in the background. When the cache finds a newer CLI, Peach prints one short stderr notice without delaying the command or changing stdout. It stays silent for agents, CI, JSON, piped, and noninteractive use; set PEACH_UPDATE_CHECK=off to disable it. peach upgrade updates both parts now.

To update only the runtime:

peach runtime install            # latest on the default (stable) channel
peach runtime install 0.1.498    # a specific version
peach runtime install --channel beta

#Select a repo runtime or inspect installed runtimes

peach runtime list     # every runtime installed under ~/.peach/runtimes/
peach runtime which    # the active one
peach runtime use 0.1.494   # temporarily switch the machine default
peach runtime notes    # what changed / what a version fixes

To keep one app on a version, add an optional repo config:

// rnx.config.ts
export default { runtimeVersion: '0.1.494' }

This does not change the runtime used by other repos. Remove the field to follow the current stable runtime again.

peach runtime notes is where “fixed in runtime X” information lives. Check it when you’re verifying a reported issue is resolved.

#See what just went wrong

peach get diagnosis    # composed read for "what just went wrong?"
peach what-happened    # recent semantic events: toasts, keyboards, screens,
                         # alerts, fetches, errors

These read the live sim’s recent semantic events, so you can see the error, alert, or failed fetch that preceded the symptom without digging through raw logs.

#Still stuck?

If an app does not render correctly and it is not a version/runtime issue, it is a compatibility gap. Scan the project’s dependencies and report it:

peach compat     # classify each dependency's support level

Then send a report from inside the sim; see Reporting Issues for exactly what gets captured and how a fix reaches you.

#Related

• +
  Reporting Issues
• +
  Wrapping an Existing App
• +
  Compat overview