@ball-lang/cli

<p align="center" <img src="assets/logo.png" alt="Ball Logo" width="120" / </p

<h1 align="center"Ball Programming Language</h1

<p align="center" <strongA polyglot programming language IR where every program is a Protocol Buffer message.</strong </p

<p align="center" <a href="https://github.com/ball-lang/ball/actions/workflows/ci.yml"<img src="https://github.com/ball-lang/ball/actions/workflows/ci.yml/badge.svg" alt="CI"</a <a href="https://www.npmjs.com/package/@ball-lang/engine"<img src="https://img.shields.io/npm/v/@ball-lang/engine" alt="npm"</a <a href="LICENSE"<img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License"</a <a href="https://buf.build/ball-lang/ball"<img src="https://img.shields.io/badge/proto-buf.build-blue" alt="Buf"</a </p

<p align="center" <a href="https://ball-lang.dev"Website</a &middot; <a href="https://ball-lang.dev/playground"Playground</a &middot; <a href="docs/"Documentation</a &middot; <a href="examples/"Examples</a &middot; <a href="docs/articles/introducing-ball.md"Introducing Ball</a </p

---

Why Ball?

Programs are structured data, not text. A Ball program is a protobuf message that can be serialized, transmitted, stored in a database, and compiled to any target language — with zero parsing ambiguity.

| Capability | Details | |---|---| | Programs are data | Protobuf schema enforces structural validity. If it deserializes, it is syntactically valid. No parser, no syntax errors. | | Provably complete security auditing | ball audit statically reports every side effect. No eval, no FFI, no hidden capabilities — every I/O operation flows through a named base function. | | Multi-language compilation | Compile Ball to Dart, C++, and more. Encode Dart source back to Ball. Round-trip real-world code. | | Self-hosted toolchain | The Dart reference interpreter is itself encoded as Ball, then compiled back to Dart with byte-identical conformance output. A TS-native compiler (@ball-lang/compiler) uses ts-morph in-process — Dart fixtures round-trip to TS and execute byte-identical on Node, and the full engine.dart parses cleanly. The C++ compiler runs the conformance corpus end-to-end. Exact pass counts are CI-gated, never hand-maintained — see the conformance matrix. | | Three runtime engines | Dart (true async), C++ (native), TypeScript (runs in the browser). | | Package management | Import modules from pub, npm, and more registries with ball add pub:package@^1.0.0. | | Web playground | Try Ball in your browser at ball-lang.dev/playground. |

Quick Start

Install the TypeScript engine (runs anywhere)

npm install @ball-lang/engine

import { BallEngine } from '@ball-lang/engine';

const program = JSON.parse(fs.readFileSync('hello_world.ball.json', 'utf-8'));
const engine = new BallEngine();
await engine.run(program);

Or use the Dart CLI

# The Dart pub-workspace + Melos root is the repo root; resolve from there.
dart pub get

# Run a program
dart run ball_cli:ball run examples/hello_world/hello_world.ball.json

# Compile Ball to Dart source
dart run ball_cli:ball compile examples/hello_world/hello_world.ball.json

# Encode Dart source back to Ball
dart run ball_cli:ball encode my_app.dart

dart run ballcli:ball audit examples/helloworld/helloworld.ball.json

## Hello World

**Ball program** (`hello_world.ball.json`):

{ "@type": "type.googleapis.com/ball.v1.Program", "name": "helloworld", "version": "1.0.0", "modules": [ { "name": "std", "functions": [{ "name": "print", "isBase": true }], "typeDefs": [{ "name": "PrintInput", "descriptor": { "name": "PrintInput", "field": [{ "name": "message", "number": 1, "label": "LABELOPTIONAL", "type": "TYPESTRING" }] } }] }, { "name": "main", "moduleImports": [{ "name": "std" }], "functions": [{ "name": "main", "outputType": "void", "body": { "call": { "module": "std", "function": "print", "input": { "messageCreation": { "typeName": "PrintInput", "fields": [ { "name": "message", "value": { "literal": { "stringValue": "Hello, World!" } } } ]}} } } }] } ], "entryModule": "main", "entryFunction": "main" }