[gwdp]

Why

Reuse simulator startup and setup without repeating a long command.

How

simulator:start --import <file> loads saved start options and follows normal startup. CLI flags override saved options. Once the session is ready, it prints the preview URL, then runs the imported actions with progress and output.

The saved session changes only after setup succeeds. If setup fails, the CLI tries to stop the new session and preserves the previous saved credentials. Android supports start options only.

Example: start a session with accessibility settings (simulator.json)

Start a 30-minute iPhone preview with dark mode, reduced motion and increased contrast.

{
  "version": 1,
  "start": {
    "platform": "ios",
    "type": "web-preview-only",
    "device": "iPhone 17 Pro",
    "name": "Accessibility QA",
    "max-duration-minutes": 30
  },
  "actions": [
    {
      "action": "appearance.set",
      "params": {
        "value": "dark"
      }
    },
    {
      "action": "reduceMotion.set",
      "params": {
        "value": "on"
      }
    },
    {
      "action": "increaseContrast.set",
      "params": {
        "value": "on"
      }
    }
  ]
}

Use the saved options, or override the session name:

eas simulator:start --import ./simulator.json
eas simulator:start --import ./simulator.json --name "Checkout QA"

With local egress, actions wait for the connection and require interactive mode. In scripts, connect with simulator:egress, then use simulator:control --import.

Test Plan

Codex ran 907 simulator/help tests, a clean build and typecheck on this rebased layer. Scoped lint, formatting and rendered-help checks pass. The final update changes the compact help examples and preserves their JSON indentation. Import and startup execution code is unchanged. Node 22/24 CI passes. Devin completed with no new findings. Codecov patch coverage is 96.90%; its report still flags a missing base comparison, while the coverage checks pass.

Earlier local and hosted iOS QA covered startup, saved options, preview output before actions, JSON, file readback, failure and cancellation. Hosted QA was not repeated after restacking. Regression tests for saved-session preservation and output-directory preflight failed on the previous code and pass with the fixes.

Earlier QA: terminal recordings and imported files

Start with local egress

Terminal video · Imported JSON · Uploaded text file

This file starts the session with local egress, then uploads a file, launches the app, waits with a gesture, reads back the network response and saves a screenshot. Its temporary artifact URLs are no longer served.

Preview URL before imported actions

Imported JSON · Capture and validation

This file runs appearance.get, tap and hardwareKeyboard.get after readiness.

Hosted QA and limits

Native Copy with the hardware keyboard off remains a recorded limitation. Camera, capture, Android and fleet acceptance were outside that run. Related control fixes #4681–#4684 remain separate.

Authorship and LLM use

Gabe asked to extend control import with existing start options in the same file and run actions after the ready preview URL. Codex implemented it and addressed reviewer findings around overrides, ordering and cleanup. After Gabe tested startup, Codex corrected the output order and checked it locally and on a fresh hosted session.

Gabe reviewed the final changes, including Devin's saved-session and output-directory fixes. Those reviews preceded this restack. Codex then moved the shared config reader into control import and kept startup options, preflight and post-readiness actions here. Szymon approved the reorganized layer at 3f8c11d. Gabe then approved the compact shared help example. Codex applied that help update, added --platform ios to the JSON-mode example and rebased onto current main; the new head follows those reviews.

— Codex

[gwdp]

Codex rebased this layer onto main 85c77cc8 and applied Gabe's approved compact help examples. The help formatter preserves JSON indentation for simulator command aliases; control example spacing stays unchanged. This layer passed 907 simulator/help tests, clean build and typecheck; scoped lint, formatting and rendered-help checks passed. Connection, import and startup execution code is unchanged by this update. Node 22/24 CI and Devin pass; no unresolved review threads remain. Existing GitHub approvals predate this help update.

— Codex

[codecov]

Codecov Report

❌ Patch coverage is 96.90265% with 7 lines in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (gwdp/control-import-first-20261018@a66f986). Learn more about missing BASE report.

Files with missing lines	Patch %	Lines
packages/eas-cli/src/commands/simulator/index.ts	95.95%	6 Missing ⚠️
packages/eas-cli/src/simulator/startConfig.ts	98.22%	1 Missing ⚠️

Additional details and impacted files

@@                          Coverage Diff                          @@
##             gwdp/control-import-first-20261018    #4687   +/-   ##
=====================================================================
  Coverage                                      ?   77.04%           
=====================================================================
  Files                                         ?     1114           
  Lines                                         ?    56637           
  Branches                                      ?    12572           
=====================================================================
  Hits                                          ?    43633           
  Misses                                        ?    12014           
  Partials                                      ?      990           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[github-actions]

Subscribed to pull request

File Patterns	Mentions
packages/eas-cli/**	@douglowder

Generated by CodeMention

Warning: The preamble and epilogue options in commentConfiguration are deprecated. Use template instead.

[linear-code]

ENG-28817

[github-actions]

✅ Thank you for adding a changeset!