eai — Elliot AI CLI

The Elliot AI CLI entry point. It resolves the OpenCode runtime binary and hands over to it, forwarding every argument verbatim.

eai                  ->  <runtime>              (TUI)
eai --version        ->  <runtime> --version
eai --help           ->  <runtime> --help
eai models           ->  <runtime> models
eai mcp list         ->  <runtime> mcp list
eai run "..."        ->  <runtime> run "..."

Why it parses nothing

Any flag this launcher understands is a flag it can disagree with the runtime about. By forwarding process.argv.slice(2) untouched, every current and future runtime command works on day one and cannot drift. There is no argument schema here on purpose.

Arguments are passed without a shell, so quoting, spaces and shell metacharacters in a prompt arrive exactly as typed. Exit codes are propagated, signal deaths are re-raised rather than flattened, and stdio is inherited (which is what makes the TUI work).

How the runtime is located

In precedence order (lib/resolve.js):

| # | Source | Path | |---|---|---| | 1 | ELLIOT_OPENCODE_BIN | the binary itself | | 2 | platform npm package | @elliotsystems/eai-<platform>-<arch>/bin/opencode[.exe], via require.resolve -- this is how an installed eai finds its runtime | | 3 | bundled runtime | vendor/opencode-<platform>-<arch>/bin/opencode[.exe] | | 4 | ELLIOT_OPENCODE_HOME | <home>/packages/opencode/dist/… or <home>/opencode-<platform>-<arch>/… | | 5 | in-repo fork checkout | ../opencode/packages/opencode/dist/… -- development only | | 6 | sibling fork checkout | ../../opencode/packages/opencode/dist/… -- development only, last resort |

Two deliberate rules:

• Explicit configuration is strict. If ELLIOT_OPENCODE_BIN or ELLIOT_OPENCODE_HOME is set, development fallbacks are skipped entirely. Silently running a different build than the operator configured is worse than not running: the results look legitimate and nobody suspects the path.
• No PATH lookup. Falling back to whatever opencode happens to be on PATH would let an unrelated or upstream build answer as the Elliot runtime, with no version guarantee.

Platform/arch directory names mirror upstream's own dist naming, so bundling a runtime later is a file copy, not a translation.

Set ELLIOT_LAUNCHER_DEBUG=1 to print the resolved path to stderr (stdout stays clean for piping).

Command name

eai is a new, unused command name. It deliberately does not collide with elliot-ai, which is the bin name of the shipped legacy CLI (@elliotsystems/elliot-ai, currently on PATH). Both can coexist, so the legacy CLI keeps working untouched and its retirement stays a separate, later decision.

Run it locally, without installing, with node bin/eai.

This section previously said the package was private: true and that publishing was out of scope. It has been published as @elliotsystems/eai since 0.1.0; the note was left behind and is corrected here.

Install

npm i -g @elliotsystems/eai

The platform-specific OpenCode binary is delivered automatically via the package's optionalDependencies (@elliotsystems/eai-<os>-<arch>). There is no build or toolchain step required on the user's machine.

Supported platforms (v1)

• darwin-arm64 (macOS, Apple Silicon)
• darwin-x64 (macOS, Intel)
• linux-x64 (Linux, x86-64)
• linux-arm64 (Linux, ARM64)
• windows-x64 (Windows, x86-64)

Release process (maintainers)

To publish a new release to npm:

1. Ensure the GitHub Actions secret NPM_TOKEN is configured (an npm automation/granular token with read+write permissions to the @elliotsystems scope) and you are a member of the @elliotsystems npm organization.

2. Run the publish-eai GitHub Actions workflow via workflow_dispatch:

   • Set dryRun: true first to verify the build and package assembly on CI.
   • After verifying the dry-run succeeds, trigger again with dryRun: false to publish to npm.
   • Alternatively, push a tag matching eai-v* (e.g., eai-v1.0.0) to publish directly; the tag triggers a live publish (dry-run is skipped).

3. The workflow cross-compiles all platforms on a single Ubuntu runner (using Bun), assembles per-platform npm packages (@elliotsystems/eai-<os>-<arch>), and publishes them along with the meta package. The publish is idempotent—versions already on npm are skipped.

4. Bump elliot-launcher/package.json version for a new release; all per-platform packages inherit that version.

Note: The terminal project-screen eai install command currently uses the local vendor + npm i -g <checkout> flow. Repointing it to npm i -g @elliotsystems/eai is a follow-up task once the first publish succeeds.

Tests

npm test        # node --test, no dependencies