expo · Ubax · Feb 25, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -10,7 +10,7 @@ This is the log of notable changes to EAS CLI and related packages.
 
 ### 🎉 New features
 
-- Add `eas observe:metrics` command for monitoring app performance metrics. ([#3401](https://github.com/expo/eas-cli/pull/3401) by [@ubax](https://github.com/ubax))
+- Add `eas observe:metrics` and `eas observe:events` commands for monitoring app performance metrics. ([#3401](https://github.com/expo/eas-cli/pull/3401) by [@ubax](https://github.com/ubax))
 
 ### 🐛 Bug fixes
 

diff --git a/packages/eas-cli/src/commands/observe/__tests__/events.test.ts b/packages/eas-cli/src/commands/observe/__tests__/events.test.ts
@@ -0,0 +1,237 @@
+import { Config } from '@oclif/core';
+
+import { ExpoGraphqlClient } from '../../../commandUtils/context/contextUtils/createGraphqlClient';
+import { AppObservePlatform } from '../../../graphql/generated';
+import { fetchObserveEventsAsync } from '../../../observe/fetchEvents';
+import { buildObserveEventsJson } from '../../../observe/formatEvents';
+import { enableJsonOutput, printJsonOnlyOutput } from '../../../utils/json';
+import ObserveEvents from '../events';
+
+jest.mock('../../../observe/fetchEvents');
+jest.mock('../../../observe/formatEvents', () => ({
+  buildObserveEventsTable: jest.fn().mockReturnValue('table'),
+  buildObserveEventsJson: jest.fn().mockReturnValue({}),
+}));
+jest.mock('../../../log');
+jest.mock('../../../utils/json');
+
+const mockFetchObserveEventsAsync = jest.mocked(fetchObserveEventsAsync);
+const mockBuildObserveEventsJson = jest.mocked(buildObserveEventsJson);
+const mockEnableJsonOutput = jest.mocked(enableJsonOutput);
+const mockPrintJsonOnlyOutput = jest.mocked(printJsonOnlyOutput);
+
+describe(ObserveEvents, () => {
+  const graphqlClient = {} as any as ExpoGraphqlClient;
+  const mockConfig = {} as unknown as Config;
+  const projectId = 'test-project-id';
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    mockFetchObserveEventsAsync.mockResolvedValue({
+      events: [],
+      pageInfo: { hasNextPage: false, hasPreviousPage: false },
+    });
+  });
+
+  function createCommand(argv: string[]): ObserveEvents {
+    const command = new ObserveEvents(argv, mockConfig);
+    // @ts-expect-error
+    jest.spyOn(command, 'getContextAsync').mockReturnValue({
+      projectId,
+      loggedIn: { graphqlClient },
+    });
+    return command;
+  }
+
+  it('uses --days-from-now to compute start/end time range', async () => {
+    const now = new Date('2025-06-15T12:00:00.000Z');
+    jest.useFakeTimers({ now });
+
+    const command = createCommand(['--metric', 'tti', '--days-from-now', '7']);
+    await command.runAsync();
+
+    expect(mockFetchObserveEventsAsync).toHaveBeenCalledTimes(1);
+    const options = mockFetchObserveEventsAsync.mock.calls[0][2];
+    expect(options.endTime).toBe('2025-06-15T12:00:00.000Z');
+    expect(options.startTime).toBe('2025-06-08T12:00:00.000Z');
+
+    jest.useRealTimers();
+  });
+
+  it('uses DEFAULT_DAYS_BACK (60 days) when neither --days-from-now nor --start/--end are provided', async () => {
+    const now = new Date('2025-06-15T12:00:00.000Z');
+    jest.useFakeTimers({ now });
+
+    const command = createCommand(['--metric', 'tti']);
+    await command.runAsync();
+
+    const options = mockFetchObserveEventsAsync.mock.calls[0][2];
+    expect(options.startTime).toBe('2025-04-16T12:00:00.000Z');
+    expect(options.endTime).toBe('2025-06-15T12:00:00.000Z');
+
+    jest.useRealTimers();
+  });
+
+  it('uses explicit --start and --end when provided', async () => {
+    const command = createCommand([
+      '--metric',
+      'tti',
+      '--start',
+      '2025-01-01T00:00:00.000Z',
+      '--end',
+      '2025-02-01T00:00:00.000Z',
+    ]);
+    await command.runAsync();
+
+    const options = mockFetchObserveEventsAsync.mock.calls[0][2];
+    expect(options.startTime).toBe('2025-01-01T00:00:00.000Z');
+    expect(options.endTime).toBe('2025-02-01T00:00:00.000Z');
+  });
+
+  it('defaults endTime to now when only --start is provided', async () => {
+    const now = new Date('2025-06-15T12:00:00.000Z');
+    jest.useFakeTimers({ now });
+
+    const command = createCommand(['--metric', 'tti', '--start', '2025-01-01T00:00:00.000Z']);
+    await command.runAsync();
+
+    const options = mockFetchObserveEventsAsync.mock.calls[0][2];
+    expect(options.startTime).toBe('2025-01-01T00:00:00.000Z');
+    expect(options.endTime).toBe('2025-06-15T12:00:00.000Z');
+
+    jest.useRealTimers();
+  });
+
+  it('rejects --days-from-now combined with --start', async () => {
+    const command = createCommand([
+      '--metric',
+      'tti',
+      '--days-from-now',
+      '7',
+      '--start',
+      '2025-01-01T00:00:00.000Z',
+    ]);
+
+    await expect(command.runAsync()).rejects.toThrow();
+  });
+
+  it('passes --limit to fetchObserveEventsAsync', async () => {
+    const command = createCommand(['--metric', 'tti', '--limit', '42']);
+    await command.runAsync();
+
+    const options = mockFetchObserveEventsAsync.mock.calls[0][2];
+    expect(options.limit).toBe(42);
+  });
+
+  it('passes --after cursor to fetchObserveEventsAsync', async () => {
+    const command = createCommand(['--metric', 'tti', '--after', 'cursor-xyz']);
+    await command.runAsync();
+
+    const options = mockFetchObserveEventsAsync.mock.calls[0][2];
+    expect(options.after).toBe('cursor-xyz');
+  });
+
+  it('does not pass after when --after flag is not provided', async () => {
+    const command = createCommand(['--metric', 'tti']);
+    await command.runAsync();
+
+    const options = mockFetchObserveEventsAsync.mock.calls[0][2];
+    expect(options).not.toHaveProperty('after');
+  });
+
+  it('rejects --days-from-now combined with --end', async () => {
+    const command = createCommand([
+      '--metric',
+      'tti',
+      '--days-from-now',
+      '7',
+      '--end',
+      '2025-02-01T00:00:00.000Z',
+    ]);
+
+    await expect(command.runAsync()).rejects.toThrow();
+  });
+
+  it('passes --platform ios to fetchObserveEventsAsync as AppObservePlatform.Ios', async () => {
+    const command = createCommand(['--metric', 'tti', '--platform', 'ios']);
+    await command.runAsync();
+
+    const options = mockFetchObserveEventsAsync.mock.calls[0][2];
+    expect(options.platform).toBe(AppObservePlatform.Ios);
+  });
+
+  it('passes --platform android to fetchObserveEventsAsync as AppObservePlatform.Android', async () => {
+    const command = createCommand(['--metric', 'tti', '--platform', 'android']);
+    await command.runAsync();
+
+    const options = mockFetchObserveEventsAsync.mock.calls[0][2];
+    expect(options.platform).toBe(AppObservePlatform.Android);
+  });
+
+  it('passes --app-version to fetchObserveEventsAsync', async () => {
+    const command = createCommand(['--metric', 'tti', '--app-version', '2.1.0']);
+    await command.runAsync();
+
+    const options = mockFetchObserveEventsAsync.mock.calls[0][2];
+    expect(options.appVersion).toBe('2.1.0');
+  });
+
+  it('passes --update-id to fetchObserveEventsAsync', async () => {
+    const command = createCommand(['--metric', 'tti', '--update-id', 'update-xyz']);
+    await command.runAsync();
+
+    const options = mockFetchObserveEventsAsync.mock.calls[0][2];
+    expect(options.updateId).toBe('update-xyz');
+  });
+
+  it('does not pass platform, appVersion, or updateId when flags are not provided', async () => {
+    const command = createCommand(['--metric', 'tti']);
+    await command.runAsync();
+
+    const options = mockFetchObserveEventsAsync.mock.calls[0][2];
+    expect(options.platform).toBeUndefined();
+    expect(options.appVersion).toBeUndefined();
+    expect(options.updateId).toBeUndefined();
+  });
+
+  it('calls enableJsonOutput and printJsonOnlyOutput when --json is provided', async () => {
+    const mockEvents = [
+      {
+        id: 'evt-1',
+        metricName: 'expo.app_startup.tti',
+        metricValue: 1.23,
+        timestamp: '2025-01-15T10:30:00.000Z',
+        appVersion: '1.0.0',
+        appBuildNumber: '42',
+        deviceModel: 'iPhone 15',
+        deviceOs: 'iOS',
+        deviceOsVersion: '17.0',
+        countryCode: 'US',
+        sessionId: 'session-1',
+        easClientId: 'client-1',
+      },
+    ];
+    mockFetchObserveEventsAsync.mockResolvedValue({
+      events: mockEvents as any,
+      pageInfo: { hasNextPage: false, hasPreviousPage: false },
+    });
+
+    const command = createCommand(['--metric', 'tti', '--json', '--non-interactive']);
+    await command.runAsync();
+
+    expect(mockEnableJsonOutput).toHaveBeenCalled();
+    expect(mockBuildObserveEventsJson).toHaveBeenCalledWith(
+      mockEvents,
+      expect.objectContaining({ hasNextPage: false })
+    );
+    expect(mockPrintJsonOnlyOutput).toHaveBeenCalled();
+  });
+
+  it('does not call enableJsonOutput when --json is not provided', async () => {
+    const command = createCommand(['--metric', 'tti']);
+    await command.runAsync();
+
+    expect(mockEnableJsonOutput).not.toHaveBeenCalled();
+    expect(mockPrintJsonOnlyOutput).not.toHaveBeenCalled();
+  });
+});
diff --git a/packages/eas-cli/src/commands/observe/events.ts b/packages/eas-cli/src/commands/observe/events.ts
@@ -0,0 +1,133 @@
+import { Flags } from '@oclif/core';
+
+import EasCommand from '../../commandUtils/EasCommand';
+import { EasNonInteractiveAndJsonFlags } from '../../commandUtils/flags';
+import { getLimitFlagWithCustomValues } from '../../commandUtils/pagination';
+import { AppObservePlatform } from '../../graphql/generated';
+import Log from '../../log';
+import {
+  type EventsOrderPreset,
+  fetchObserveEventsAsync,
+  resolveOrderBy,
+} from '../../observe/fetchEvents';
+import { resolveMetricName } from '../../observe/metricNames';
+import { validateDateFlag } from '../../observe/fetchMetrics';
+import { buildObserveEventsJson, buildObserveEventsTable } from '../../observe/formatEvents';
+import { enableJsonOutput, printJsonOnlyOutput } from '../../utils/json';
+
+const DEFAULT_EVENTS_LIMIT = 10;
+const DEFAULT_DAYS_BACK = 60;
+
+export default class ObserveEvents extends EasCommand {
+  static override description = 'display individual app performance events ordered by metric value';
+
+  static override flags = {
+    metric: Flags.string({
+      description:
+        'Metric to query (full name or alias: tti, ttr, cold_launch, warm_launch, bundle_load)',
+      required: true,
+    }),
+    sort: Flags.enum<EventsOrderPreset>({
+      description: 'Sort order for events',
+      options: ['slowest', 'fastest', 'newest', 'oldest'],
+      default: 'slowest',
+    }),
+    platform: Flags.enum<'android' | 'ios'>({
+      description: 'Filter by platform',
+      options: ['android', 'ios'],
+    }),
+    after: Flags.string({
+      description:
+        'Cursor for pagination. Use the endCursor from a previous query to fetch the next page.',
+    }),
+    limit: getLimitFlagWithCustomValues({ defaultTo: DEFAULT_EVENTS_LIMIT, limit: 100 }),
+    start: Flags.string({
+      description: 'Start of time range (ISO date)',
+      exclusive: ['days-from-now'],
+    }),
+    end: Flags.string({
+      description: 'End of time range (ISO date)',
+      exclusive: ['days-from-now'],
+    }),
+    'days-from-now': Flags.integer({
+      description: 'Show events from the last N days (mutually exclusive with --start/--end)',
+      min: 1,
+      exclusive: ['start', 'end'],
+    }),
+    'app-version': Flags.string({
+      description: 'Filter by app version',
+    }),
+    'update-id': Flags.string({
+      description: 'Filter by EAS update ID',
+    }),
+    ...EasNonInteractiveAndJsonFlags,
+  };
+
+  static override contextDefinition = {
+    ...this.ContextOptions.ProjectId,
+    ...this.ContextOptions.LoggedIn,
+  };
+
+  async runAsync(): Promise<void> {
+    const { flags } = await this.parse(ObserveEvents);
+    const {
+      projectId,
+      loggedIn: { graphqlClient },
+    } = await this.getContextAsync(ObserveEvents, {
+      nonInteractive: flags['non-interactive'],
+    });
+
+    if (flags.json) {
+      enableJsonOutput();
+    } else {
+      Log.warn('EAS Observe is in preview and subject to breaking changes.');
+    }
+
+    if (flags.start) {
+      validateDateFlag(flags.start, '--start');
+    }
+    if (flags.end) {
+      validateDateFlag(flags.end, '--end');
+    }
+
+    const metricName = resolveMetricName(flags.metric);
+    const orderBy = resolveOrderBy(flags.sort);
+
+    let startTime: string;
+    let endTime: string;
+
+    if (flags['days-from-now']) {
+      endTime = new Date().toISOString();
+      startTime = new Date(Date.now() - flags['days-from-now'] * 24 * 60 * 60 * 1000).toISOString();
+    } else {
+      endTime = flags.end ?? new Date().toISOString();
+      startTime =
+        flags.start ?? new Date(Date.now() - DEFAULT_DAYS_BACK * 24 * 60 * 60 * 1000).toISOString();
+    }
+
+    const platform = flags.platform
+      ? flags.platform === 'android'
+        ? AppObservePlatform.Android
+        : AppObservePlatform.Ios
+      : undefined;
+
+    const { events, pageInfo } = await fetchObserveEventsAsync(graphqlClient, projectId, {
+      metricName,
+      orderBy,
+      limit: flags.limit ?? DEFAULT_EVENTS_LIMIT,
+      ...(flags.after && { after: flags.after }),
+      startTime,
+      endTime,
+      platform,
+      appVersion: flags['app-version'],
+      updateId: flags['update-id'],
+    });
+
+    if (flags.json) {
+      printJsonOnlyOutput(buildObserveEventsJson(events, pageInfo));
+    } else {
+      Log.addNewLineIfNone();
+      Log.log(buildObserveEventsTable(events, pageInfo));
+    }
+  }
+}