# Ceraph Agent Hooks Can Now Run From Your Terminal

> Ceraph 1.2.0 adds ceraph hook run. The agent hooks your coding agent uses to set up a React Native or Expo development app can now be run by you, from your terminal, in the app you already have open.

- Author: Ike Studios LLC
- Published: 2026-11-08
- Canonical: https://ceraph.dev/blog/run-agent-hooks-from-terminal

---

Most screens worth checking in a React Native app need some state first. That might be a signed-in user, finished onboarding, a cart with items in it, or an account whose trial has ended. Getting there by hand means tapping through the same flow every time you reinstall, switch simulators or clear storage.

Ceraph [hooks](/blog/test-user-provisioning-react-native) handle this for coding agents. A hook is a file in your project. It registers a route and runs your own app code inside the live development app. While an agent tests a change, it calls the hook and starts from the state it needs.

Ceraph 1.2.0 lets you call the same hook from your terminal:

```sh
ceraph hook run /subscription/expire-trial
```

You write the setup once, and both you and the agent can use it.

## Checking the agent's work yourself

Say an agent has just built a "Your trial has ended" banner. To test it, the agent needed an account with an expired trial, so the project gained a hook:

```ts
// .ceraph/hooks/expire-trial.hook.ts
// These imports are your project's own dev helpers, not part of Ceraph.
import { expireTrialForCurrentUser } from "../../src/dev/subscriptions";
import { refreshSubscription } from "../../src/state/subscription";

export const route = "/subscription/expire-trial";
export const description = "End the signed-in test user's trial on the development backend";

export async function run() {
  const { trialEndedAt } = await expireTrialForCurrentUser();
  await refreshSubscription();
  return { ok: true, data: { trialEndedAt } };
}
```

The agent reports that the banner works, and now you want to see it yourself. You'll tighten the copy, check the layout on a small Android screen and tap the upgrade button to see where it goes. Each of those checks starts from an expired trial.

Until now, a Ceraph hook ran only when an agent called it. Repeating that setup meant asking for a model turn and an automation session just to run code already in your repo. Now you run the route in the app you have open, keep editing with Fast Refresh, and run it again whenever a check needs the trial expired again. The command calls no model, so it uses no AI tokens. It doesn't start device automation either, so there's no session to wait for.

You also don't have to rebuild the agent's setup from its summary. You run the same code it ran, against your own app and account. The agent's side doesn't change: it still calls hooks over MCP while it tests.

The hook also lives in the branch. A teammate reviewing the change can put their test account in that state with one command instead of following steps in the pull request description. They need Ceraph set up in their development app and access to the same development backend.

## Running a hook

The app must be open with Metro running. The command doesn't launch or reload the app for you. It prints the hook's result as one line of JSON and exits with `0` when the hook reports success and `1` otherwise:

```text
{"ok":true,"data":{"trialEndedAt":"2026-11-07T09:00:00.000Z"}}
```

Because of those exit codes, you can chain hooks. If expiring a trial needs a signed-in test user first, and your project has a hook for that, run them in order:

```sh
ceraph hook run /test-user/sign-in && ceraph hook run /subscription/expire-trial
```

Ceraph doesn't ship either route. You choose both and write the code behind them.

If more than one app instance is connected, such as an iOS simulator and an Android emulator, the command won't pick one for you. Run `ceraph hook list` to see their runtime IDs, then pass `--runtime <id>`. From a monorepo root, point at the app with `--project apps/mobile`. After you add or remove a hook, the command may ask you to restart Metro and reload the app before it runs anything. If a result comes back with `"outcome":"unconfirmed"`, the hook may still have run, so check the app before you try again.

Hook code runs inside your development app and can call your development backend, so its effects are real. Anything a hook returns in `data` is printed to your terminal. It stays in your scrollback and in any logs that capture the command. Use disposable, non-production accounts, and only return data you're fine seeing printed. `isAvailable` only controls which hooks agents are shown. The command can run any registered route, so put any checks a hook needs inside `run`.

For routes you run often, an npm script gives you a shorter command:

```json
{ "scripts": { "trial:expired": "ceraph hook run /subscription/expire-trial" } }
```

Then run `npm run trial:expired`.

## Getting started

Update Ceraph and your app's `@ceraph/react-native-mcp` dependency to 1.2.0, restart Metro and reload the development app. With the app open, run `ceraph hook run <route>` with any route your project registers. If you don't have any hooks yet, start with [test user provisioning](/blog/test-user-provisioning-react-native) and [get started](/docs/get-started).
