# How to Check for ego-lite Updates: 3 Methods Explained

> Learn how to check for ego-lite updates with 3 simple methods. Discover automatic checks and manual verification for the citrolabs/ego-lite runtime.

- Repository: [CitroLabs/ego-lite](https://github.com/citrolabs/ego-lite)
- Tags: how-to-guide
- Published: 2026-08-03

---

**The ego-lite runtime automatically checks for updates on every command by calling `ego.getBrowserVersion()`, which returns a `BrowserVersionInfo` object indicating whether a newer version is available.**

ego-lite, as implemented in the citrolabs/ego-lite repository, bakes update detection into its core execution flow. When you run any ego-lite script, the runtime queries the host application through a bridge method, formats any available update into a human-readable notice, and appends it to your command output. This guide covers how to check for ego-lite updates programmatically, customize the behavior, and suppress notifications when needed.

## How the Automatic Update Check Works

The update detection mechanism in ego-lite centers on a single bridge method exposed by the host environment.

### The `getBrowserVersion()` Bridge Method

Every ego-lite command invokes `ego.getBrowserVersion()` to retrieve version metadata. According to the source code in [`src/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/index.ts), this call returns a **`BrowserVersionInfo`** object with the following structure:

```typescript
type BrowserVersionInfo = {
  currentVersion: string;   // e.g. "1.4.0"
  updateAvailable: boolean; // true if a newer version exists
  latestVersion?: string;   // version string of the newest release (optional)
  mandatory?: boolean;      // true if the update must be applied immediately
};

```

The `updateAvailable` boolean drives the entire notification pipeline. When `true`, the **[`update-notice.ts`](https://github.com/citrolabs/ego-lite/blob/main/update-notice.ts)** module formats a notice line and the **[`output-sink.ts`](https://github.com/citrolabs/ego-lite/blob/main/output-sink.ts)** module appends it as a footer to your command's output.

### What the Update Notice Looks Like

The formatted notice follows a consistent pattern:

```

[ego-browser:notice] ego lite 1.5.0 is available (current 1.4.0) — run: ego-browser upgrade in your shell, then re-read the ego-browser skill

```

This line appears automatically at the end of any command output when an update is detected.

## Method 1: Call the Bridge Directly

For scripts that need explicit version control, call `ego.getBrowserVersion()` directly.

```typescript
// Assume `ego` is the injected runtime object
async function checkForUpdate() {
  const info = await ego.getBrowserVersion?.();
  if (info?.updateAvailable) {
    console.log('Update available! Current:', info.currentVersion, 
                'Latest:', info.latestVersion ?? '(unknown)');
  } else {
    console.log('ego-lite is up-to-date.');
  }
}

checkForUpdate();

```

This approach gives you full access to all fields in `BrowserVersionInfo`, including the optional `mandatory` flag that indicates whether an update must be applied immediately.

## Method 2: Use the `updateNoticeLine` Helper

The [`src/update-notice.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/update-notice.ts) file exports a higher-level helper that handles timeouts and suppression logic automatically.

```typescript
import { updateNoticeLine } from './update-notice.js';

async function getUpdateNotice() {
  const line = await updateNoticeLine({
    source: () => ego.getBrowserVersion?.() ?? Promise.resolve(null),
    env: process.env,            // respects suppression flags
    timeoutMs: 2000,             // optional custom timeout
  });
  
  if (line) {
    console.log('🛈', line);
  } else {
    console.log('No update available.');
  }
}

getUpdateNotice();

```

**Key advantages of this method:**

- **Automatic timeout handling** — prevents hanging if the bridge is unresponsive
- **CI/environment detection** — respects `EGO_BROWSER_NO_UPDATE_NOTIFIER` automatically
- **Formatted output** — returns the same notice string shown in standard command output, or `null` if no update exists

## Method 3: Read the Notice from Buffered Output

For testing or post-processing scenarios, capture the notice after it has been emitted through the output sink mechanism.

```typescript
// After a command finishes, the buffered sink has flushed its output.
import { resetSink, flushSink } from './output-sink.js';
import { createBufferedLog } from './index.js';

// Set up a custom writable that captures output.
let captured = '';
const fakeStdout = { write: (txt: string) => (captured += txt) };

console.log = createBufferedLog();   // redirects console.log to the buffer

// …run your script…

flushSink(fakeStdout, false);        // flush the buffered output
console.log('Captured output:', captured);

```

This pattern is useful in test suites that verify update-notice behavior without mocking the entire bridge.

## How to Suppress Update Checks

The ego-lite update check respects standard suppression conventions. Set the environment variable `EGO_BROWSER_NO_UPDATE_NOTIFIER` to any value to disable the check entirely:

```bash
EGO_BROWSER_NO_UPDATE_NOTIFIER=1 ego run my-script.ego

```

The check is also automatically suppressed in CI environments, as detected through standard environment heuristics in [`src/update-notice.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/update-notice.ts).

## Key Source Files

Understanding these files helps when debugging or extending update behavior:

| File | Role |
|------|------|
| [[`src/update-notice.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/update-notice.ts)](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/update-notice.ts) | Implements the bridge query, timeout handling, and notice formatting |
| [[`src/output-sink.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/output-sink.ts)](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/output-sink.ts) | Buffers console output and appends the update-notice trailer after commands finish |
| [[`src/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/index.ts)](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/index.ts) | Installs the SDK, wires `emitUpdateNotice` into the runtime, and sets up the buffered console logger |

## Summary

- **Automatic checks** occur on every command via `ego.getBrowserVersion()` in [`src/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/index.ts)
- **Direct bridge calls** give full control over `BrowserVersionInfo` inspection
- **`updateNoticeLine` helper** abstracts timeout handling and suppression logic
- **Buffered output reading** enables testing and post-processing of notices
- **Environment variable `EGO_BROWSER_NO_UPDATE_NOTIFIER`** disables checks without code changes

## Frequently Asked Questions

### How do I check for ego-lite updates in a CI pipeline?

Set `EGO_BROWSER_NO_UPDATE_NOTIFIER=1` in your CI environment. The [`src/update-notice.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/update-notice.ts) implementation automatically detects CI contexts and suppresses the update check, or you can force suppression explicitly with this environment variable.

### What happens if the bridge method `getBrowserVersion()` is unavailable?

The runtime handles missing bridge methods gracefully. In direct calls, use optional chaining (`ego.getBrowserVersion?.()`). The `updateNoticeLine` helper accepts a `source` function that can return `Promise.resolve(null)` as a fallback, ensuring your script continues executing regardless of bridge availability.

### Can I customize the update notice format?

The notice format is hardcoded in [`src/update-notice.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/update-notice.ts). To customize it, you would need to bypass the built-in `emitUpdateNotice` wiring in [`src/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/index.ts) and implement your own version check using the direct bridge call pattern, then format the output as needed.

### How long does the update check wait before timing out?

The default timeout is handled internally by `updateNoticeLine`. You can specify a custom timeout in milliseconds via the `timeoutMs` option, as shown in Method 2 above. The recommended range is 1000-5000ms to balance responsiveness with reliability.