@statelyai/sdk 0.4.1 → 0.5.1

package/README.md

@@ -1,16 +1,34 @@
 # @statelyai/sdk
 
-Embed the [Stately editor](https://stately.ai) in your app and talk to the Stately Studio API. Zero dependencies, fully typed.
+<!-- package.json#name and #description — top-level summary -->
+
+Embed the [Stately editor](https://stately.ai), inspect running actor systems over WebSockets, talk to the Stately Studio API, and convert between Studio graph data and code. Fully typed.
 
 ## Install
 
+<!-- install command derived from package.json#name -->
+
 ```bash
 npm install @statelyai/sdk
 ```
 
+## What It Includes
+
+<!-- top-level runtime exports from src/index.ts and CLI bin from package.json#bin -->
+
+- `createStatelyEmbed()` for browser embeds backed by `postMessage`
+- `createStatelyInspector()` for inspecting live actor systems over WebSockets
+- `createStatelyClient()` for Stately Studio API access
+- graph conversion and codegen helpers such as `fromStudioMachine()`, `toStudioMachine()`, `graphToMachineConfig()`, and `graphToXStateTS()`
+- sync helpers under `@statelyai/sdk/sync` and a `statelyai` CLI binary
+
 ## Authentication
 
-The editor uses a pluggable authentication system. How you configure it depends on whether you're using the hosted Stately platform or self-hosting.
+The embed supports three common deployment models:
+
+- Hosted Stately: pass an API key to `createStatelyEmbed()`
+- Same-origin deployments: rely on the host application's session/cookie auth
+- Self-hosted deployments: configure auth in the editor server and omit `apiKey` when no token is required
 
 ### With Stately (default)
 
@@ -32,56 +50,39 @@ const embed = createStatelyEmbed({
 });
 ```
 
-The server validates the key against the Stately registry API.
-
-### Self-hosting
-
-When self-hosting the editor, authentication is controlled by the `AUTH_PROVIDER` environment variable on the server:
-
-| Value | Behavior |
-| ---------- | ----------------------------------------------------------- |
-| `stately` | Validates tokens against the Stately registry API |
-| `none` | Allows all requests (no authentication) |
-| _(unset)_ | `none` in development, `stately` in production |
-
-For a fully self-contained deployment with no Stately dependency:
-
-```bash
-AUTH_PROVIDER=none
-```
-
-### Custom authentication
+### Same-origin embed (cookie auth)
 
-You can implement your own auth by writing a custom `AuthValidator` — an async function that receives a token and returns whether it's valid:
+When the embed host and the editor share a domain, you can omit `apiKey` and rely on the host application's auth/session layer:
 
 ```ts
-import type { AuthValidator } from '@/lib/auth';
-
-const myValidator: AuthValidator = async (token) => {
-  const res = await fetch('https://my-auth-server.com/verify', {
-    headers: { Authorization: `Bearer ${token}` },
-  });
-  return res.ok;
-};
+const embed = createStatelyEmbed({
+  baseUrl: process.env.NEXT_PUBLIC_BETA_EDITOR_URL ?? window.location.origin,
+});
 ```
 
-The built-in adapters are:
-
-- **`createStatelyValidator(baseUrl?)`** — verifies against the Stately registry API (`/registry/api/v1/verify`)
-- **`allowAllValidator`** — always returns `true`
+### Self-hosting
 
-To use a custom validator, call `getAuthValidator()` from `src/lib/auth` in the server-side page code, or replace the resolver logic in `src/lib/auth/index.tsx` to return your implementation.
+When self-hosting the editor, authentication is enforced by the editor server, not by this npm package.
 
-### Environment variables
+The common environment variables are:
 
 | Variable | Purpose |
-| ----------------------- | -------------------------------------------- |
-| `AUTH_PROVIDER` | Auth strategy: `stately`, `none`, or unset |
+| --- | --- |
+| `AUTH_PROVIDER` | Auth strategy used by the editor host |
+| `EDITOR_SYNC_AUTH_REQUIRED` | Set to `false` to disable API-key checks for editor-sync endpoints only |
 | `STATELY_API_KEY` | Server-side API key for Stately data fetching |
-| `STATELY_API_URL` | Stately API base URL (server-side override) |
-| `NEXT_PUBLIC_BASE_URL` | Public-facing base URL |
+| `STATELY_API_URL` | Stately API base URL override |
+| `NEXT_PUBLIC_BASE_URL` | Public-facing editor URL |
+
+For a fully self-contained deployment with no auth, omit `apiKey` in the SDK and configure the host/editor to allow unauthenticated access:
+
+```ts
+const embed = createStatelyEmbed({
+  baseUrl: 'https://your-editor.example.com',
+});
+```
 
-## Quick start
+## Quick Start
 
 ### Third-party embed (with API key)
 
@@ -97,39 +98,15 @@ embed.mount(document.getElementById('editor')!);
 
 embed.init({
   machine: myMachineConfig,
+  format: 'xstate',
   mode: 'editing',
   theme: 'dark',
 });
 ```
 
-### Same-origin embed (cookie auth)
-
-When the embed host and the editor share a domain (e.g. Stately Studio embedding the beta editor), Supabase session cookies handle auth automatically — no API key needed:
-
-```ts
-const embed = createStatelyEmbed({
-  baseUrl: process.env.NEXT_PUBLIC_BETA_EDITOR_URL ?? window.location.origin,
-});
-
-embed.mount(container);
-```
-
-### Self-hosted (no auth)
-
-When self-hosting with `AUTH_PROVIDER=none`, no token is required:
-
-```ts
-const embed = createStatelyEmbed({
-  baseUrl: 'https://your-editor.example.com',
-});
-
-embed.mount(container);
-```
-
 ### Comments
 
-Comments are optional and integrator-configured. Pass a `comments` object to
-`embed.init()` when you want Liveblocks-backed commenting enabled.
+Comments are optional and integrator-configured. Pass a `comments` object to `embed.init()` when you want Liveblocks-backed commenting enabled.
 
 ```ts
 embed.init({
@@ -156,30 +133,38 @@ embed.init({
 });
 ```
 
-`roomId` is required when comments are enabled. `userId` is optional and only
-used for comment identity metadata.
+`roomId` is required when comments are enabled. `userId` is optional and only used for comment identity metadata.
 
-## Module layout
+## Module Layout
 
-The SDK ships direct root exports for the common entry points:
+<!-- subpath imports derived from package.json#exports -->
+
+The SDK ships root exports for the most common entry points and helpers:
 
 ```ts
 import {
-  createStatelyInspector,
-  createStatelyEmbed,
   createStatelyClient,
+  createStatelyEmbed,
+  createStatelyInspector,
+  fromStudioMachine,
+  graphToMachineConfig,
+  graphToXStateTS,
+  toStudioMachine,
 } from '@statelyai/sdk';
 ```
 
-It also supports subpath imports when you want a narrower surface:
+It also supports narrower subpath imports:
 
 ```ts
 import { createStatelyClient } from '@statelyai/sdk/studio';
 import { createStatelyInspector } from '@statelyai/sdk/inspect';
 import { createStatelyEmbed } from '@statelyai/sdk/embed';
+import { fromStudioMachine, toStudioMachine } from '@statelyai/sdk/graph';
+import { planSync, pullSync } from '@statelyai/sdk/sync';
+import type { GraphPatch } from '@statelyai/sdk/patchTypes';
 ```
 
-## Studio API client
+## Studio API Client
 
 ```ts
 import { createStatelyClient } from '@statelyai/sdk';
@@ -193,35 +178,90 @@ const machine = await studio.machines.get('machine-id', { version: '42' });
 const extracted = await studio.code.extractMachines(sourceCode);
 ```
 
-## API
+<!-- public methods of StudioClient from src/studio.ts -->
+
+Available client methods:
+
+| Method | Description |
+| --- | --- |
+| `studio.auth.verify(apiKey?)` | Verify an API key against the registry API |
+| `studio.projects.get(projectId)` | Fetch a project and its machines |
+| `studio.machines.get(machineId, { version? })` | Fetch a machine, optionally pinned to a version |
+| `studio.code.extractMachines(code, { apiKey? })` | Extract machine configs from source text |
+
+## Inspector
+
+<!-- public API of createStatelyInspector from src/inspect.ts -->
+
+`createStatelyInspector()` streams actor-system state to the Stately inspector over WebSockets. It supports both automatic XState actor adoption and manual actor registration.
+
+```ts
+import { createActor } from 'xstate';
+import { createStatelyInspector } from '@statelyai/sdk';
+
+const actor = createActor(machine);
+const inspector = createStatelyInspector({
+  actor,
+  url: 'ws://localhost:4242',
+  autoOpen: true,
+});
+
+actor.start();
+```
+
+Key options:
+
+| Option | Description |
+| --- | --- |
+| `actor` | Root actor to adopt and inspect automatically |
+| `url` | Devtools relay URL. Defaults to `ws://localhost:4242` |
+| `autoOpen` | Whether to ask the relay to open the inspector UI |
+| `sessionId` | Override the relay session id |
+| `name` | Display name shown to the inspector |
+| `serializeSnapshot` | Customize snapshot serialization before sending it over the wire |
+| `extractMachineConfig` | Customize how machine config is derived from an actor |
+| `selectedActorId` | Focus a specific actor first |
+| `panels`, `theme`, `readOnly`, `depth` | Initial inspector UI options |
+| `transport` | Inject an existing transport instead of opening a new WebSocket |
+
+Key methods:
+
+- `inspector.export(format, options?)`
+- `inspector.actor(id, options?)`
+- `inspector.snapshot(actorId, snapshot, event?)`
+- `inspector.event(actorId, event, { source? })`
+- `inspector.stop(actorId)`
+- `inspector.destroy()`
+
+## Embed API
 
 ### `createStatelyEmbed(options)`
 
 Creates an embed instance.
 
-| Option     | Type                             | Description                               |
-| ---------- | -------------------------------- | ----------------------------------------- |
-| `baseUrl`  | `string`                         | **Required.** Base URL of the Stately app  |
-| `apiKey`   | `string`                         | API key for authentication (see [Authentication](#authentication)) |
-| `origin`   | `string`                         | Custom target origin for postMessage      |
-| `assets`   | `AssetConfig`                    | Asset upload configuration (see [Asset uploads](#asset-uploads)) |
-| `onReady`  | `() => void`                     | Called when embed is ready                |
-| `onLoaded` | `(graph) => void`                | Called when machine is loaded             |
-| `onChange` | `(graph, machineConfig) => void` | Called on every change                    |
-| `onSave`   | `(graph, machineConfig) => void` | Called on save                            |
-| `onError`  | `({ code, message }) => void`    | Called on error                           |
+<!-- public options of StatelyEmbedOptions from src/embed.ts -->
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `baseUrl` | `string` | **Required.** Base URL of the Stately app |
+| `apiKey` | `string` | API key for hosted Stately deployments |
+| `origin` | `string` | Optional strict target origin for `postMessage`; defaults to permissive wildcard messaging for local/self-hosted testing |
+| `assets` | `AssetConfig` | Asset upload configuration |
+| `onReady` | `() => void` | Called when the embed is ready |
+| `onLoaded` | `(graph) => void` | Called when a machine is loaded |
+| `onChange` | `(graph, machineConfig) => void` | Called on every change |
+| `onSave` | `(graph, machineConfig) => void` | Called on save |
+| `onError` | `({ code, message }) => void` | Called when the embed reports an error |
 
 ### Embed methods
 
 #### `embed.mount(container)` / `embed.attach(iframe)`
 
-Mount creates an iframe inside a container element. Attach connects to an existing iframe.
+`mount()` creates an iframe inside a container element. `attach()` connects to an existing iframe.
 
 ```ts
-// Create a new iframe
 const iframe = embed.mount(document.getElementById('editor')!);
 
-// Or attach to an existing one
 embed.attach(document.querySelector('iframe')!);
 ```
 
@@ -232,9 +272,9 @@ Initialize the embed with a machine and display options.
 ```ts
 embed.init({
   machine: machineConfig,
-  format: 'xstate', // optional
-  mode: 'editing', // 'editing' | 'viewing' | 'simulating'
-  theme: 'dark', // 'light' | 'dark'
+  format: 'xstate',
+  mode: 'editing',
+  theme: 'dark',
   readOnly: false,
   depth: 3,
   panels: {
@@ -242,6 +282,10 @@ embed.init({
     rightPanels: ['events'],
     activePanels: ['code'],
   },
+  unsavedIndicator: {
+    enabled: true,
+    mode: 'structural',
+  },
   comments: {
     roomId: 'machine:checkout',
     publicApiKey: 'pk_live_...',
@@ -252,13 +296,20 @@ embed.init({
 `comments` accepts:
 
 | Field | Type | Description |
-| ---------- | ---------- | ----------------------------------------------- |
+| --- | --- | --- |
 | `roomId` | `string` | **Required.** Liveblocks room identifier |
 | `publicApiKey` | `string` | Liveblocks public key |
 | `authEndpoint` | `string` | Custom Liveblocks auth endpoint |
 | `baseUrl` | `string` | Custom Liveblocks base URL for self-hosting |
 | `userId` | `string \| null` | Optional user identity metadata |
 
+`unsavedIndicator` accepts:
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `enabled` | `boolean` | Show the persistent "Save to apply" pill |
+| `mode` | `'structural' \| 'all'` | Track only structural graph edits or all edits |
+
 #### `embed.updateMachine(machine, format?)`
 
 Update the displayed machine.
@@ -269,7 +320,7 @@ Change the embed mode or theme at runtime.
 
 #### `embed.setSettings(settings)`
 
-Update editor settings at runtime. Merges with existing settings.
+Update editor settings at runtime. Settings are merged with the existing editor settings.
 
 ```ts
 embed.setSettings({
@@ -281,7 +332,7 @@ embed.setSettings({
 Available core settings:
 
 | Path | Type | Default |
-|------|------|---------|
+| --- | --- | --- |
 | `appearance.colorMode` | `'light' \| 'dark' \| 'system'` | `'dark'` |
 | `canvas.showGrid` | `boolean` | `true` |
 | `canvas.viewMode` | `'graph' \| 'list'` | `'graph'` |
@@ -296,20 +347,31 @@ Available core settings:
 Export the current machine. Returns a promise.
 
 ```ts
-const code = await embed.export('xstate', { version: 5 });
-const json = await embed.export('json');
-const mermaid = await embed.export('mermaid');
+const xstateCode = await embed.export('xstate', { version: 5 });
+const digraph = await embed.export('digraph');
+const rtk = await embed.export('rtk');
+const aslYaml = await embed.export('asl-yaml');
 ```
 
-Supported formats: `xstate`, `json`, `digraph`, `mermaid`, `scxml`
+<!-- supported export formats from ExportFormatMap in src/protocol.ts -->
+
+Supported formats: `xstate`, `json`, `xgraph`, `digraph`, `mermaid`, `rtk`, `zustand`, `asl-json`, `asl-yaml`, `scxml`
 
 #### `embed.on(event, handler)` / `embed.off(event, handler)`
 
-Subscribe/unsubscribe to embed events: `ready`, `loaded`, `change`, `save`, `error`.
+<!-- keys of EmbedEventMap in src/protocol.ts -->
+
+Event names are `ready`, `loaded`, `change`, `save`, `error`, and `snapshot`.
+
+`createStatelyEmbed()` emits `ready`, `loaded`, `change`, `save`, and `error` for browser embeds:
 
 ```ts
-embed.on('change', ({ graph, machineConfig }) => {
-  console.log('Machine changed', machineConfig);
+embed.on('change', ({ graph, machineConfig, patches }) => {
+  console.log('Machine changed', graph, machineConfig, patches);
+});
+
+embed.on('save', ({ validations }) => {
+  console.log('Save validations', validations);
 });
 ```
 
@@ -323,96 +385,142 @@ Tear down the embed. Removes listeners, rejects pending promises, and removes th
 
 ### Asset uploads
 
-By default, dropped images are stored as base64 data URLs. To upload assets to your own storage, pass an `assets` config:
+By default, dropped files are stored as base64 data URLs. To upload assets to your own storage, pass an `assets` config:
 
 ```ts
 const embed = createStatelyEmbed({
   baseUrl: 'https://stately.ai',
   assets: {
     onUploadRequest: async (file, { stateNodeId }) => {
-      // upload `file` (a File object) to your storage
-      // return { url } at minimum
+      return { url: await uploadToStorage(file, stateNodeId) };
     },
-    accept: ['image/*'],          // MIME patterns (default: ['image/*'])
-    maxFileSize: 5 * 1024 * 1024, // bytes (default: 10 MB)
+    accept: ['image/*'],
+    maxFileSize: 5 * 1024 * 1024,
   },
 });
 ```
 
 | Option | Type | Description |
 | --- | --- | --- |
-| `onUploadRequest` | `(file: File, context: { stateNodeId: string }) => Promise<UploadResult>` | **Required.** Called when the editor needs to upload a file. Return the hosted URL. |
-| `accept` | `string[]` | Accepted MIME types. Supports wildcards (`image/*`). Default: `['image/*']` |
-| `maxFileSize` | `number` | Max file size in bytes. Default: `10_485_760` (10 MB) |
+| `onUploadRequest` | `(file: File, context: { stateNodeId: string }) => Promise<UploadResult>` | **Required.** Called when the editor needs to upload a file |
+| `accept` | `string[]` | Accepted MIME types. Supports wildcards like `image/*` |
+| `maxFileSize` | `number` | Max file size in bytes. Defaults to `10_485_760` |
 
 `UploadResult`:
 
 ```ts
 interface UploadResult {
-  url: string;                        // hosted URL (required)
-  name?: string;                      // display name (defaults to filename)
-  metadata?: Record<string, unknown>; // arbitrary metadata stored on the asset
+  url: string;
+  name?: string;
+  metadata?: Record<string, unknown>;
 }
 ```
 
-#### Example: AWS S3 (presigned URL)
+If `onUploadRequest` throws or rejects, the editor shows an error toast. If no `assets` config is provided, files are stored inline and no upload request is sent.
+
+## Graph And Codegen Helpers
+
+<!-- root helper exports from src/index.ts -->
+
+Use the conversion helpers to move between Studio digraph data, generic Stately graphs, machine config objects, and XState TypeScript source.
 
 ```ts
-import { createStatelyEmbed } from '@statelyai/sdk';
+import {
+  fromStudioMachine,
+  graphToMachineConfig,
+  graphToXStateTS,
+  toStudioMachine,
+} from '@statelyai/sdk';
 
-const embed = createStatelyEmbed({
-  baseUrl: 'https://stately.ai',
-  assets: {
-    onUploadRequest: async (file) => {
-      // 1. Get a presigned upload URL from your backend
-      const { uploadUrl, publicUrl } = await fetch('/api/s3/presign', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({
-          filename: file.name,
-          contentType: file.type,
-        }),
-      }).then((r) => r.json());
-
-      // 2. PUT the file directly to S3
-      await fetch(uploadUrl, {
-        method: 'PUT',
-        headers: { 'Content-Type': file.type },
-        body: file,
-      });
-
-      return { url: publicUrl, name: file.name };
-    },
-    accept: ['image/*'],
-    maxFileSize: 10 * 1024 * 1024,
-  },
+const graph = fromStudioMachine(studioMachine);
+const machineConfig = graphToMachineConfig(graph, {
+  showDescriptions: true,
+  showMeta: true,
+});
+const source = graphToXStateTS(graph, {
+  exportStyle: 'named',
 });
+const digraph = toStudioMachine(graph);
 ```
 
-#### Example: Cloudflare R2 (worker upload)
+Other exported helpers:
+
+- `studioMachineConverter` for reusable format conversion
+- `serializeJS()`, `raw()`, and `RawCode` for emitting JavaScript source
+- `jsonSchemaToTSType()`, `contextSchemaToTSType()`, and `eventsSchemaToTSType()` for generating inline TypeScript types from JSON Schema
+- `GraphPatch` and `ActionLocation` types from `@statelyai/sdk/patchTypes`
+
+## Sync Helpers And CLI
+
+<!-- sync helpers from src/sync.ts and CLI commands from src/cli.ts#COMMANDS -->
+
+The sync helpers compare or materialize machines across local files, Stately machine IDs, and Stately URLs.
+
+Programmatic usage:
 
 ```ts
-import { createStatelyEmbed } from '@statelyai/sdk';
+import { planSync, pullSync } from '@statelyai/sdk/sync';
 
-const embed = createStatelyEmbed({
-  baseUrl: 'https://stately.ai',
-  assets: {
-    onUploadRequest: async (file) => {
-      const form = new FormData();
-      form.append('file', file);
+const plan = await planSync({
+  source: './checkout.machine.ts',
+  target: 'machine-id',
+  apiKey: process.env.STATELY_API_KEY,
+});
 
-      // Upload via a Cloudflare Worker that writes to R2
-      const { url } = await fetch('https://uploads.example.com/assets', {
-        method: 'POST',
-        body: form,
-      }).then((r) => r.json());
+if (plan.summary.hasChanges) {
+  console.log(plan.summary);
+}
 
-      return { url, name: file.name };
-    },
-    accept: ['image/*', 'application/pdf'],
-    maxFileSize: 25 * 1024 * 1024,
-  },
+await pullSync({
+  source: 'machine-id',
+  target: './checkout.machine.ts',
+  apiKey: process.env.STATELY_API_KEY,
 });
 ```
 
-If `onUploadRequest` throws or rejects, the editor shows an error toast. If no `assets` config is provided, files are stored as inline base64 data URLs (no network requests).
+Supported locators:
+
+- local files
+- Stately machine IDs
+- full Stately machine URLs
+
+Installing the package also exposes a `statelyai` binary:
+
+```bash
+npx statelyai open ./checkout.machine.ts
+
+statelyai plan ./checkout.machine.ts machine-id
+statelyai diff ./checkout.machine.ts machine-id --fail-on-changes
+statelyai pull machine-id ./checkout.machine.ts
+statelyai open ./checkout.machine.ts
+```
+
+For one-off use, `npx statelyai ...` installs the small `statelyai` CLI package, which delegates to this SDK CLI.
+
+Available commands:
+
+| Command | Description |
+| --- | --- |
+| `statelyai plan <source> <target>` | Print a semantic sync summary |
+| `statelyai diff <source> <target>` | Diff two locators and optionally fail on changes |
+| `statelyai pull <source> <target>` | Materialize a source into a local target file |
+| `statelyai open <file>` | Open a local file in a browser-backed visual editor session |
+
+Common flags:
+
+- `--api-key` for remote machine resolution or editor servers that require auth
+- `--base-url` for self-hosted or non-default Stately deployments
+- `--fail-on-changes` to return a nonzero exit code when a diff is detected
+
+`statelyai open` also supports `--api-key`, `--editor-url`, `--host`, `--port`, `--no-open`, and `--debug`. It watches the local file on disk and sends source snapshots to `/api/editor-sync/*` endpoints, which return the text replacements to apply locally. Pass `--api-key` or set `STATELY_API_KEY` when the editor server requires auth. Self-hosted servers can disable editor-sync API-key checks with `EDITOR_SYNC_AUTH_REQUIRED=false`. The private source reconciliation engine is not bundled into the published CLI.
+
+## Transport Helpers
+
+<!-- transport helpers exported from src/index.ts -->
+
+For advanced integrations, the root package also exports:
+
+- `createPostMessageTransport()` for iframe-based clients
+- `createWebSocketTransport()` for relay-based integrations
+
+These power the embed and inspector internals, but they are also available when you need lower-level control over the `@statelyai.*` protocol.

package/dist/cli.d.mts

@@ -10,16 +10,16 @@ declare abstract class BaseSyncCommand extends Command {
   static flags: {
     help: _oclif_core_interfaces0.BooleanFlag<void>;
     'fail-on-changes': _oclif_core_interfaces0.BooleanFlag<boolean>;
-    'api-key': _oclif_core_interfaces0.OptionFlag<string, _oclif_core_interfaces0.CustomOptions>;
-    'base-url': _oclif_core_interfaces0.OptionFlag<string, _oclif_core_interfaces0.CustomOptions>;
+    'api-key': _oclif_core_interfaces0.OptionFlag<string | undefined, _oclif_core_interfaces0.CustomOptions>;
+    'base-url': _oclif_core_interfaces0.OptionFlag<string | undefined, _oclif_core_interfaces0.CustomOptions>;
   };
 }
 declare abstract class ParsedSyncCommand extends BaseSyncCommand {
   protected parseSync<T extends typeof BaseSyncCommand>(command: T): Promise<_oclif_core_interfaces0.ParserOutput<{
     help: void;
     'fail-on-changes': boolean;
-    'api-key': string;
-    'base-url': string;
+    'api-key': string | undefined;
+    'base-url': string | undefined;
   }, {
     [flag: string]: any;
   }, {
@@ -53,11 +53,30 @@ declare class PullCommand extends ParsedSyncCommand {
   };
   run(): Promise<void>;
 }
+declare class OpenCommand extends Command {
+  static enableJsonFlag: boolean;
+  static summary: string;
+  static description: string;
+  static args: {
+    file: _oclif_core_interfaces0.Arg<string, Record<string, unknown>>;
+  };
+  static flags: {
+    help: _oclif_core_interfaces0.BooleanFlag<void>;
+    'api-key': _oclif_core_interfaces0.OptionFlag<string | undefined, _oclif_core_interfaces0.CustomOptions>;
+    'editor-url': _oclif_core_interfaces0.OptionFlag<string | undefined, _oclif_core_interfaces0.CustomOptions>;
+    host: _oclif_core_interfaces0.OptionFlag<string, _oclif_core_interfaces0.CustomOptions>;
+    port: _oclif_core_interfaces0.OptionFlag<number, _oclif_core_interfaces0.CustomOptions>;
+    open: _oclif_core_interfaces0.BooleanFlag<boolean>;
+    debug: _oclif_core_interfaces0.BooleanFlag<boolean>;
+  };
+  run(): Promise<void>;
+}
 declare const COMMANDS: {
   plan: typeof PlanCommand;
   diff: typeof DiffCommand;
   pull: typeof PullCommand;
+  open: typeof OpenCommand;
 };
-declare function run(argv?: string[]): Promise<void>;
+declare function run(argv?: string[], entryUrl?: string): Promise<void>;
 //#endregion
 export { COMMANDS, formatPlanSummary, run };