CLI Host

Relevant source files

• README.md
• apps/cli/src/build.ts
• apps/cli/src/daemon-state.test.ts
• apps/cli/src/daemon-state.ts
• apps/cli/src/daemon.test.ts
• apps/cli/src/daemon.ts
• apps/cli/src/device-login.test.ts
• apps/cli/src/device-login.ts
• apps/cli/src/local-server-manifest.test.ts
• apps/cli/src/local-server-manifest.ts
• apps/cli/src/main.ts
• apps/cli/src/server-connection.test.ts
• apps/cli/src/server-connection.ts
• apps/cli/src/server-profile.test.ts
• apps/cli/src/server-profile.ts
• apps/cli/src/service.test.ts
• apps/cli/src/service.ts
• apps/cli/src/tooling.test.ts
• apps/cli/src/tooling.ts
• apps/cli/vitest.config.ts
• apps/cloud/src/api/protected-jwt-auth.node.test.ts
• apps/cloud/src/auth/api-jwt-bearer.ts
• apps/cloud/src/auth/workos-auth-provider.ts
• apps/cloud/src/mcp/jwt.ts
• apps/desktop/scripts/smoke-sidecar.ts
• apps/desktop/src/main/supervised-daemon.test.ts
• apps/desktop/src/main/supervised-daemon.ts
• apps/desktop/vitest.config.ts
• apps/local/tsconfig.json
• packages/core/sdk/src/promise.test.ts
• packages/hosts/mcp/src/stdio-integration.test.ts
• packages/plugins/onepassword/src/sdk/onepassword-sdk.ts
• packages/plugins/onepassword/src/sdk/service.test.ts
• packages/plugins/onepassword/src/sdk/service.ts
• patches/@1password%2Fsdk-core@0.4.1-beta.1.patch
• tests/daemon-bootstrap.test.ts
• tests/daemon-state.test.ts
• tests/presets-reachable.test.ts
• tests/tools-cli.test.ts

The Executor CLI (executor) is a cross-platform, single-file binary built with Bun that serves as a headless host for the Executor SDK. It manages a background daemon, provides a rich command-line interface for tool discovery and invocation, and bridges the local executor to AI agents via the Model Context Protocol (MCP).

Architecture and Command Loop

The CLI is implemented using effect/unstable/cli and acts as a wrapper around the @executor-js/local server and the @executor-js/api layer.

Core Command Set

The CLI exposes several primary command groups:

• install / uninstall: Manages the OS-native background service (launchd, systemd, Task Scheduler) apps/cli/src/service.ts76-94
• web: Launches the local server and opens the embedded React console in the default browser apps/cli/src/main.ts96-102
• daemon: Low-level management of the background process, including run (foreground) and start/stop (background) apps/cli/src/daemon.ts112-137
• tools: Inspects the tool catalog, searches by intent, and describes tool schemas apps/cli/src/tooling.ts49-105
• call: Invokes a tool by its hierarchical path (e.g., github.issues.create) apps/cli/src/tooling.ts149-190
• mcp: Acts as an MCP stdio bridge for agents like Claude Code or Cursor apps/cli/src/main.ts73-75

Data Flow: CLI to Code Entity

The following diagram maps CLI user actions to the internal functions and classes that handle them.

CLI Command Mapping

Sources: apps/cli/src/main.ts64-176 apps/cli/src/tooling.ts49-151 apps/cli/src/service.ts76-94

---

Daemon Lifecycle and Election

The CLI uses a "daemon" model to ensure a local API server is always available without requiring the user to manually manage processes.

Election and Locking

When a command requiring the API is run (like call or tools), the CLI checks if a daemon is already reachable apps/cli/src/daemon.ts88-98 If not, it attempts to start one:

1. Lock Acquisition: It uses acquireDaemonStartLock to prevent race conditions where multiple CLI instances try to spawn a daemon simultaneously apps/cli/src/daemon-state.ts118-124
2. Port Selection: It probes for an available port, starting with the preferred 4788 or 4789 apps/cli/src/daemon.ts106-110
3. Process Spawning: It spawns a detached process using the current executable path with the daemon run --foreground arguments apps/cli/src/daemon.ts112-137
4. State Persistence: The daemon's PID and base URL are written to a "pointer" file in the data directory apps/cli/src/daemon-state.ts128-130

OS Service Integration

For permanent backgrounding, executor install registers the binary with the host OS:

• macOS: Generates a launchd plist in ~/Library/LaunchAgents apps/cli/src/service.ts15-18
• Linux: Creates a systemd --user unit file apps/cli/src/service.ts15-18
• Windows: Uses schtasks.exe to create a Task Scheduler entry and a .vbs launcher to hide the console window apps/cli/src/service.ts24-27

Sources: apps/cli/src/daemon.ts104-166 apps/cli/src/daemon-state.ts118-130 apps/cli/src/service.ts1-28

---

Tooling and Invocation

The CLI provides a hierarchical "path-based" interface to the flat tool catalog.

Path Inspection

Tools are addressed using dot-notation (e.g., stripe.customers.list). The inspectToolPath function allows the CLI to provide "help" at any level of the hierarchy:

• It filters the full catalog based on a prefix apps/cli/src/tooling.ts53-66
• It identifies "child" segments and determines if they are terminal (invokable) or further namespaces apps/cli/src/tooling.ts70-87

The Call Pipeline

When executor call <path> <json> is executed:

1. Resolution: resolveToolInvocation splits the path and identifies if the last argument is inline JSON or a file path (prefixed with @) apps/cli/src/tooling.ts149-189
2. Code Generation: It generates a small snippet of JavaScript (e.g., buildInvokeToolCode) that will be executed by the kernel's execution engine apps/cli/src/tooling.ts161-166
3. Execution: The CLI sends this code to the daemon's /api/executions endpoint.
4. Output Sanitization: Results are stripped of ANSI escape codes and control characters before being printed to stdout apps/cli/src/tooling.ts15-22

Tool Invocation Flow

Sources: apps/cli/src/tooling.ts15-116 apps/cli/src/tooling.ts149-190 apps/cli/src/main.ts160-176

---

Device Login OAuth Flow

The CLI supports a "Device Code" flow for authenticating with Executor Cloud without requiring the user to manually copy-paste long-lived tokens.

1. Request: requestDeviceCode calls the cloud's /oauth/device/code endpoint apps/cli/src/device-login.ts93-94
2. Interaction: The CLI prints a user code and attempts to open the browser to the verification URL using openBrowser apps/cli/src/device-login.ts90
3. Polling: The CLI enters a polling loop via pollForDeviceTokens, checking the cloud's token endpoint until the user completes the login apps/cli/src/device-login.ts91
4. Storage: Once received, the access and refresh tokens are stored in the local keychain using @napi-rs/keyring apps/cli/src/main.ts1-3

Sources: apps/cli/src/device-login.ts88-94 apps/cli/src/main.ts1-3

---

Build and Distribution Pipeline

The CLI is distributed as a self-contained binary for multiple platforms.

Native Binding Colocation

Because Bun's bun build --compile does not bundle native .node files, the build script apps/cli/src/build.ts explicitly:

1. Resolves native binaries for @napi-rs/keyring and @libsql/client for the target platform apps/cli/src/build.ts135-173
2. Copies them into the dist directory alongside the compiled binary apps/cli/src/build.ts181-200
3. At runtime, apps/cli/src/native-bindings.ts (imported first in main.ts) sets environment variables like NAPI_RS_NATIVE_LIBRARY_PATH so the loaders find these colocated files apps/cli/src/main.ts1-3

Asset Embedding

The build process embeds the QuickJS WASM module and the 1Password SDK WASM directly into the binary so that the CLI has no external dependencies apps/cli/src/build.ts15-34 The local web UI is also baked into the binary as a generated asset apps/cli/src/main.ts178-179

Sources: apps/cli/src/build.ts1-200 apps/cli/src/main.ts1-43