A new experimental CLI, @expo/agent-cli, gives coding agents exit codes, JSON, and the next command to run for every Expo task.
Imagine asking a coding agent to add a feature to your Expo app. It installs a native module, writes the code, and starts the development server. But when it tries to open the app in Expo Go, it hits a runtime error. The agent starts debugging, changing code, reinstalling packages, and restarting the server, without realizing that the new module requires a development build.
We've seen agents get stuck in situations like this. They can write Expo apps, but they don't always know when to use Expo Go, when to create a development build, or when to rebuild after changing native dependencies. These are things experienced Expo developers have learned over time, but agents often end up figuring them out through trial and error.
We could keep improving our documentation and writing more agent skills to teach these workflows. But we started wondering: what if we could prevent these mistakes by improving the tools themselves? That's why we're introducing @expo/agent-cli, a new experimental CLI built by agents and designed for agents.
Understand your project with status
Before running an Expo app, an agent needs to understand a few things. Can this project run in Expo Go? Does it need a development build? If dependencies have changed, does the app need to be rebuilt?
Today, agents can figure this out by reading the project's dependencies, checking configuration, and sometimes launching the app to see what fails. That's a lot of work just to decide what command to run next.
We took some inspiration from git status. When you work with Git, you don't have to inspect the repository yourself to figure out which files have changed. You run one command and get the information you need.
We wanted something similar for Expo:
The status command inspects your project and reports whether it's compatible with Expo Go, whether a native rebuild is needed, and what to do next.
It doesn't need to start the app to answer these questions. An agent can run it before making a decision, rather than waiting for an error and trying to recover afterward.
When in doubt, run status. It should tell the agent what to do next.
One command to start developing
If you've worked with web frameworks, you're probably used to running npm run dev and opening a browser. You don't need to think much about how the development environment gets ready.
Mobile development has a few more steps. Depending on the project, you might need to generate native projects, compile an app, install it on a simulator, and start the development server.
Expo already provides the tools for these steps, but agents still need to know which ones to run and in what order.
With @expo/agent-cli, we're bringing those steps together into a single dev command:
The command checks the project, decides whether Expo Go or a development build is appropriate, and works out what needs to happen to get the app running.
If a native build is needed, it takes care of the required steps. If the existing build can be reused, it avoids rebuilding unnecessarily. And when it finishes, it tells the agent what to do next.
You can also run dev --plan to inspect the steps before executing them.
We want starting an Expo app to feel closer to starting a web app, even when native compilation is involved. The agent should be able to ask for a running app without having to plan the entire build process by itself.
And because a successful build doesn't always mean the app actually works, we also added smoke:
Think of it as a quick check that your development environment is working. It starts or reuses the app, checks that it can load, looks for runtime errors, and reports the result.
This gives agents a way to verify that the app can actually run, rather than stopping as soon as the build succeeds.
Let the agent use the app
A running app is only half of the loop. The agent must also check that its change works: open the right screen, use the app, and read the errors. Agents can already do this with screenshots and ad-hoc scripts. @expo/agent-cli gives them commands that control the running app. For example, navigate opens a route on the device, and runtime:reload loads the latest code. There are other runtime:* commands which can, for example, read what is on screen.
Coding agent harnesses often run each agent in its own git worktree. @expo/agent-cli gives each worktree its own simulator or emulator (or its own Expo Simulators session with --eas), so parallel agents do not interfere with each other's app.
Introducing co-located skills
We already have the Expo agent plugin, which provides skills to help coding agents build Expo apps. But as we started adding more package-specific skills, we ran into a question: should every skill be included in the plugin?
For example, if your project doesn't use expo-sqlite, there's no reason to install its skill. Unnecessary skills clutter the agent's available choices and make it harder to keep guidance relevant to the packages a project actually uses.
With SDK 58, we're introducing co-located skills. Instead of putting every skill in the Expo plugin, packages can ship their own skills alongside their code. The skills are available when the package is installed, and package authors can maintain them alongside the APIs they describe.
This builds on an existing convention, not a new one invented by Expo. Anthony Fu's skills-npm introduced tooling to discover and link skills shipped inside npm packages, and that functionality is now being integrated into the broader skills CLI. We're bringing package-skill synchronization into @expo/agent-cli so agents can use it as part of their normal Expo workflow.
For example, when installing expo-sqlite:
The CLI installs the SDK-compatible package version and syncs its bundled skills into your agent's skills directory.
If you've already installed your dependencies, you can sync skills separately:
The idea is simple: your agent should have the skills for the packages your project actually uses. Keeping skills alongside their packages also makes it easier to keep instructions in sync with the code.
One CLI for local and cloud workflows
Expo developers are familiar with using Expo CLI for local development and EAS CLI for cloud services. But for coding agents, this distinction isn't always obvious. They need to figure out which CLI to use, which commands are available, and how the options differ.
We wanted to make that simpler. Whether an agent is running an app locally or using EAS, it should be able to follow a similar workflow.
For example, instead of switching between npx expo run:ios and npx eas-cli build -p ios, an agent can express where it wants to run the workflow using the same dev command:
We've been working toward this convention across different commands, using --eas to choose EAS, with local as the default. The goal isn't to hide the differences between local development and cloud services, but to give agents a consistent way to work with both.
There's also a practical reason to make this choice explicit: EAS builds and simulator sessions consume credits. We don't want an agent accidentally starting a cloud build just because it can't build locally. By default, the CLI won't switch to EAS on its own. You need to opt in with --eas or configure your project to use EAS.
Some of these workflows rely on Expo Simulators, which is currently in preview with a waitlist. We're still experimenting with how far we can take this approach.
Under the hood, @expo/agent-cli builds on Expo CLI, EAS CLI, and expo-doctor. It also provides structured output, meaningful exit codes, and clear next steps so agents can understand what happened and decide what to do next.
Try it out
To get started, run:
This helps set up your coding agent with Expo instructions and skills. Depending on your agent, it can install the Expo agent plugin or skills, sync skills from your project's dependencies, and download documentation for your Expo SDK for local use by agents. It also updates your project's AGENTS.md to recommend using @expo/agent-cli instead of calling Expo CLI or EAS CLI directly.
Ideally, coding agents should be able to discover and use @expo/agent-cli on their own. But we've noticed that agents still fall back to Expo CLI or EAS CLI sometimes, especially since our existing documentation and skills often recommend those commands. The agents:setup command tries to address this by adding more explicit instructions, though it's still a best-effort approach.
If you want to make sure your agent tries the new CLI, you can also include this instruction directly in your prompt:
For Expo development workflows, use @expo/agent-cli instead of calling Expo CLI or EAS CLI directly.
A few final notes
This is an experimental CLI, and we're still actively developing it. Commands and output may change as we improve the experience.
If you prefer a shorter package name, expo-agent-cli is also available as an alias. Thanks to Kazutoyo Tokai for transferring the package name to us.
Our goal isn't to teach agents every detail of the Expo toolchain. It's to make more of those details something the tools can handle for them.
Give it a try, and let us know where your agent gets stuck.
