east-c-cli

Command-line runner for east-c — execute compiled East IR natively from the terminal

east-c-cli is the command-line entry point for the C runtime. It links against east-c (core) and east-c-std (standard platform) to execute East IR programs.

Build

Requires CMake 3.16+ and a C11 compiler.

make build    # From libs/east-c/
make test
make clean

See docs/conventions/MAKEFILE_TARGETS.md.

Usage

# Run a Beast2-encoded IR file
./build/packages/east-c-cli/east-c run program.beast2

# Run a JSON-encoded IR file
./build/packages/east-c-cli/east-c run program.json

# With arguments
./build/packages/east-c-cli/east-c run program.beast2 --input '"hello"'

The CLI loads the standard platform from east-c-std by default. Custom platform functions can be linked at build time.

Running a unit (exec)

east-c exec <unit.beast2> is the command e3 runs: the machine-facing twin of run. The unit file names the work — a program to run over its inputs, or the parts of an output to merge — with the platforms, the threads the runner may use, the output's kind (a value the program returns, or an array, set, dict or fold it emits into), and where to write the output and a typed result: the outcome (ok, or failed with the message and its source locations), the peak memory, and the time spent loading, compiling, executing and writing. Paths in a unit may be relative to its file, so a unit and the files it names replay wherever they are moved together. A run unit says how its inputs are read (decode, below). It exits 0 when the outcome is ok and 1 when the result records a failure; -v prints where the time went and the peak memory.

How inputs are read

A collection input opens lazily, whatever it weighs: an indexed beast2 file is mapped, and a read decodes only the segments it reaches — its size, a keyed read and the $.for loop decode a segment at a time, and an operation the pager cannot serve decodes the input whole, once, when it first needs it. A loop holds only the segment it walks. Keyed reads keep the segments they decode, up to 256 MiB of decoded weight per input (EAST_PAGED_CACHE_BYTES; 1 keeps one segment), and reads in key order keep about two. --decode whole decodes every input before the program runs instead, which suits a program that reads at random across more than that, or loops over an input more than once: lazily, a read beyond the segments the pager keeps decodes its segment again. exec reads the same choice from its unit's decode. A value that is not a collection, and a collection whose elements hold a Ref or a function, is decoded whole either way.

east-c run task.beast2 -i rows.beast2 --decode whole -o out.beast2

With -v the runner says how each input opened, and what reading it came to: the segments a lazy input decoded, or what an input decoded whole holds in memory — the growth in resident memory across its decode, beside the size it weighs on disk, since a nested collection decodes at many times that size. Reads that decode segments again are said to, with what decoding the input whole would do instead.

A collection input may also be a manifest directory, the form e3 stages a stored collection in: the input file holds a manifest, and each segment it names is a standalone blob in <file>.segments/<sha256>.beast2. It opens over those files — lazily, a read opening only the segments it reaches, or whole — and weighs its segments in the -v account.

Exiting with the parent

With --exit-with-parent on its command line (any command, anywhere among the arguments) the runner watches its stdin on a thread of its own and exits with status 1 as soon as a read returns end of file or fails. A parent that spawns the runner with a stdin pipe it never writes to — as e3 does — takes the runner down with it when it dies, even while the body is computing. Without the flag, stdin is left alone.

east-c run task.beast2 --exit-with-parent -o out.beast2

On Windows the watcher reads a synchronous pipe or an overlapped one. Hand it an overlapped pipe — FILE_FLAG_OVERLAPPED, or Node's stdio 'overlapped', as e3 does: a read pending on a synchronous pipe holds the pipe's file-object lock, so any other use of stdin in the runner would wait until the parent is gone.

Profiling

east-c run task.beast2 -i rows.beast2 --profile
east-c exec unit.beast2 --profile
EAST_PROFILE=1 EAST_PROFILE_INTERVAL=300 east-c exec unit.beast2

prints, after the work (and after a failure's error), every East function and platform function it called, by self time, with its call count, its total time, and where it is: the name of the Let it was bound to when the IR has one, its definition site, and — when that differs — the site of the first call that reached it, which is what tells apart helpers a builder lowered to calls at their call sites. A platform function is an entry of its own, named after it and placed by the call that reached it, so the time spent inside it is not its caller's self time. So is a lazily read input's decoding: each segment its reads decode, and its whole decode when an operation the pager cannot serve needs one, is a call of one entry named after the input as -v names it (input 1), placed by the first read that decoded. Keyed reads at random beyond the segments the pager keeps (EAST_PAGED_CACHE_BYTES), or a scan repeated, show there; the reading function's total time keeps those decodes, and its self time does not.

EAST_PROFILE set to anything but 0 profiles without the flag, which is how a task run by e3 is profiled: e3 hands its environment to the runner, and the report lands in the task's log. EAST_PROFILE_INTERVAL=N (seconds) also prints the profile so far every N seconds while the work runs, a call still under way counted with its time so far; an interval that is not a number of seconds is said and ignored. east-py's runner prints the same report (the profiler is libeast-c's). Off, profiling costs one branch per call.

The ir toolbox (issue #627) works on IR files without running them:

# The canonical form of an IR file: loc_ids stripped, variables/labels renamed in
# the TypeScript lowering's order, captures recomputed, recursive type ids renumbered
east-c ir normalize program.json -o canonical.json

# Normalize two IR files and report the first structural difference (exit 1) or
# "identical" (exit 0); --raw compares as-is
east-c ir diff program.json rebuilt.beast2

# json <-> beast2 with the source map intact
east-c ir convert program.json -o program.beast2

Claude Code plugin

The East ecosystem also ships a Claude Code plugin — East language skills, example search, and preemptive diagnostics for East code — installed separately from the elaraai marketplace:

# Inside Claude Code
/plugin marketplace add elaraai/east-workspace
/plugin install east@elaraai

# From a terminal
claude plugin marketplace add elaraai/east-workspace
claude plugin install east@elaraai

License

Business Source License 1.1 — see LICENSE.md. Same terms as east-c core.

Ecosystem

• East: Statically typed, expression-based language with serializable IR. Run portable logic across TypeScript, Python, C, and other runtimes.

  • @elaraai/east: Core language SDK with type system, expressions, and reference JS compiler

• East Node: Node.js platform functions for I/O, databases, and system operations.

  • @elaraai/east-node-std: Console, FileSystem, Fetch, Crypto, Time, Path, Random
  • @elaraai/east-node-io: SQLite, PostgreSQL, MySQL, MongoDB, Redis, S3, FTP, SFTP, XLSX, XML, compression
  • @elaraai/east-node-cli: CLI for running East IR programs in Node.js

• East C: C11 native runtime for executing East IR. Tarballed for linux-x64 and linux-arm64, attached to each GitHub Release.

  • east-c: Core runtime — type system, IR interpreter, 200+ builtins, serialization (Beast2, JSON, CSV, East text)
  • east-c-std: Console, FileSystem, Fetch, Crypto, Time, Path, Random
  • east-c-cli: CLI for running East IR programs natively

• East Python: Python runtime, standard platform, I/O, and data-science platform functions. Published to PyPI.

  • east-py: Core Python runtime — type system, IR compiler, 212+ builtins, Cython-accelerated hot paths
  • east-py-std: Console, FileSystem, Fetch, Crypto, Time, Path, Random
  • east-py-io: SQLite, PostgreSQL, MySQL, MongoDB, Redis, S3, FTP, SFTP, XLSX, XML, compression
  • east-py-cli: CLI for running East IR programs in Python
  • east-py-datascience (PyPI) + @elaraai/east-py-datascience (npm): Optimization (MADS, Optuna, ALNS, GoogleOR), ML (XGBoost, LightGBM, NGBoost, PyTorch, Lightning, GP), Bayesian inference (PyMC), explainability (SHAP), conformal prediction (MAPIE)

• East UI: Typed UI component definitions and React renderer, plus VS Code preview.

  • @elaraai/east-ui: 50+ typed UI components for layouts, forms, charts, tables, dialogs
  • @elaraai/east-ui-components: React renderer with Chakra UI v3 styling
  • @elaraai/e3-ui: e3 + UI bridge — Data bindings, e3.ui() task, manifest
  • @elaraai/e3-ui-components: React Query hooks and preview components for the e3 API
  • @elaraai/e3-ui-cli: Browse an e3 repository in the terminal (e3-ui [repo]), and render east-ui / e3-ui components to PNG (e3-ui shot)

• e3 — East Execution Engine: Durable execution engine for running East pipelines at scale. Git-like content-addressable storage, automatic memoization, reactive dataflow, real-time monitoring.

  • @elaraai/e3: SDK for authoring e3 packages with typed tasks and pipelines
  • @elaraai/e3-core: Object store, dataflow orchestrator, execution state
  • @elaraai/e3-types: Shared type definitions for e3 packages
  • @elaraai/e3-cli: e3 repo, e3 package, e3 workspace, e3 dataflow run, e3 watch, e3 task logs commands
  • @elaraai/e3-api-client: HTTP client for remote e3 repositories
  • @elaraai/e3-api-server: REST API server for e3 repositories
  • @elaraai/e3-api-tests: Shared API compliance test suites

Links

• Website: https://elaraai.com/
• Repository: https://github.com/elaraai/east-workspace
• Issues: https://github.com/elaraai/east-workspace/issues
• Email: [email protected]

About Elara

East is developed by Elara AI Pty Ltd, an AI-powered platform that creates economic digital twins of businesses that optimize performance. Elara combines business objectives, decisions and data to help organizations make data-driven decisions across operations, purchasing, sales and customer engagement, and project and investment planning. East powers the computational layer of Elara solutions, enabling the expression of complex business logic and data in a simple, type-safe and portable language.

Developed by Elara AI Pty Ltd.