feat(simulator): add exec command and config persistence via dotenv

[krystofwoldrich]

Goal

When testing the simulator:start I've noticed that agents correctly use the recommended agent-device envs, but because agents can't set envs for all child processes, they must include them in every agent-device call. This fogs up what is the agent doing, see the example below.

This PR proposes an option to save simulator session config to .env.eas-simulator, which can later be used by new exec command. This make working with the sim less verbose and also persist the config in case of agent cli crash, new sessions...

This PR also adds EAS_SIMULATOR_SESSION_ID env which is saved to the dotenv file for later reference to the session. This let's user call all simulator:* commands without specifying the --id.

Before

Because of the truncation it's not clear what command was executed.

After

Now it's clearly visible.

Considered alternative solutions

.env.eas-simulator currently implemented dedicated donenv file for the simulator session config. The benefit is isolation and easy of prune of the session, no parsing of the common .env files. It's used in the industry for example .env.sentry-sourcemaps.

.env.local already established file for ephemeral envs, contains other user's/project's envs would require parsing to clean up

.expo/.eas-simulator-config new specialized config file for simulator session. Seems like the best next option, but makes less transparent if someone would not want to use simulator:exec, .env.local is common for ephemeral vals.

dotenv agent-device <command> only works out of the box with .env not .env.local. Other eas command like convex use .env.local which is better as typically not committed file for tmp session envs.

./agent-device.json can have both url and token properties same as when using env, but it's unclear to me if this file is typically committed or not, there are no secrets, so my expectations are it's likely ment to be committed.

Summary

• add eas simulator:exec to run simulator commands with local .env files loaded
• make simulator:start write dotenv config by default, including agent-device envs and session id
• keep --out-config-type env for print-only shell exports

Test plan

• tests

New TUI example

Start command output

Interactions without --id

eas simulator:start # creates .env.eas-simulator
eas simulator:get # uses id from .env.eas-simulator
eas simulator:stop # uses id from .env.eas-simulator

eas simulator:start # overwrites .env.eas-simulator and logs out the previous id

Why start with --force by default? This minimizes the number of fails runs where user/agent haven't stopped the prev session and the env file have not cleaned up. It's possible to use --no-force if needed. We do only check the session id presence not the session state, to avoid extra network req on every start. This works well with the default force.

[codecov]

Codecov Report

❌ Patch coverage is 85.96491% with 16 lines in your changes missing coverage. Please review.
✅ Project coverage is 57.76%. Comparing base (2c1837f) to head (c5d3c1a).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
packages/eas-cli/src/commands/simulator/start.ts	80.65%	6 Missing ⚠️
packages/eas-cli/src/commands/simulator/exec.ts	79.17%	4 Missing and 1 partial ⚠️
packages/eas-cli/src/simulator/utils.ts	78.58%	3 Missing ⚠️
packages/eas-cli/src/commands/simulator/get.ts	88.89%	1 Missing ⚠️
packages/eas-cli/src/commands/simulator/stop.ts	90.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3777      +/-   ##
==========================================
+ Coverage   57.46%   57.76%   +0.30%     
==========================================
  Files         911      913       +2     
  Lines       39480    39581     +101     
  Branches     8271     8292      +21     
==========================================
+ Hits        22684    22859     +175     
+ Misses      15328    15266      -62     
+ Partials     1468     1456      -12     

☔ View full report in Codecov by Sentry.
📢 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
**/*	@douglowder

Generated by CodeMention

[szdziedzic]

awesome, I think this is useful and good idea overall

I have a few small comments/ideas

some of them we can add as follow ups to not block this PR

[Copilot]

Pull request overview

Adds a new hidden eas simulator:exec command and makes simulator:start persist its session config (session ID and agent-device credentials) to a dedicated .env.eas-simulator file by default, so subsequent simulator:get/stop/exec invocations can omit --id and so child processes can transparently pick up AGENT_DEVICE_DAEMON_* env vars. This makes agent-driven workflows less verbose and survives CLI crashes/new shells.

Changes:

• New simulator/env.ts (+tests) defines .env.eas-simulator plus load/write/reset helpers, and simulator:exec runs a user-supplied command with that env loaded.
• simulator:start gains --force (default true) and --out-config-type (default dotenv), writing the dotenv twice (session ID early, then with remote config) and resetting it on session end; existing session IDs trigger an overwrite warning or --no-force error.
• simulator:get/simulator:stop make --id optional, falling back to EAS_SIMULATOR_SESSION_ID loaded from the dotenv; formatRemoteSessionInstructions now takes a 'env' | 'dotenv' mode.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
packages/eas-cli/src/simulator/env.ts	New helpers for the .env.eas-simulator lifecycle.
packages/eas-cli/src/simulator/utils.ts	Adds getRemoteSessionEnvironmentVariables and configType to instructions formatter.
packages/eas-cli/src/commands/simulator/start.ts	Writes/resets dotenv, adds --force and --out-config-type, warns on existing session.
packages/eas-cli/src/commands/simulator/get.ts	Makes --id optional via env fallback; uses 'env' instructions mode.
packages/eas-cli/src/commands/simulator/stop.ts	Makes --id optional via env fallback; restructures JSON output path.
packages/eas-cli/src/commands/simulator/exec.ts	New hidden command that loads simulator env and spawns the given command.
packages/eas-cli/src/simulator/tests/env.test.ts	Tests for write/reset helpers including ENOENT handling.
packages/eas-cli/src/commands/simulator/tests/start.test.ts	New tests for dotenv writes, force/no-force, reset on end.
packages/eas-cli/src/commands/simulator/tests/get.test.ts	Adds env-fallback test and loadSimulatorEnvAsync mock.
packages/eas-cli/src/commands/simulator/tests/stop.test.ts	New tests for JSON output and env-fallback ID.
packages/eas-cli/src/commands/simulator/tests/exec.test.ts	Tests for env loading order and spawn passthrough.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[szdziedzic]

generally LGTM

[github-actions]

⏩ The changelog entry check has been skipped since the "no changelog" label is present.