Platforms

Command line interface

The edge CLI runs on macOS, Linux and WSL. It embeds the engine the JS host loads, a compiler.wasm built from the same source and precompiled for the machine.

The system calls run in SpiderMonkey inside the binary. A program answers the same on both hosts.

edge run app.py        # run a script, a .edge, or stdin (--web)
edge build             # pack a portable .edge (--app, --web)
edge actor actor.yml   # run a pool of cooperative actors
edge serve             # dev server with live reload
edge repl              # interactive shell
edge test              # run *_test.py files
edge init my-app       # scaffold a project
edge publish app.edge  # send a packed .edge to the registry
edge add json          # add a package to edge.json
edge remove json       # remove a package from edge.json
edge lock              # resolve edge.json into edge.lock
edge uninstall         # remove the binary and the PATH entry

Install

The prebuilt binary is the recommended install.

• The script drops the binary at ~/.local/bin/edge.
• It appends that directory to your ~/.bashrc or ~/.zshrc unless it is already there.
• Open a new shell and edge --version answers.
• Run the same line again to upgrade.
• The Linux binaries are static and run on any distribution.

To install one release instead of the latest, pass its tag, as in curl -fsSL https://cdn.edgepython.com/cli/install.sh | sh -s vX.Y.Z. Every release from 1.0 on keeps a frozen copy of itself on the CDN. A pinned install and a downgrade read that copy.

To build from source, run these two lines at the repo root.

make wasm-cli js lucide
cargo install --path cli

• cargo install embeds what make wasm-cli js lucide built and fetches nothing.
• EDGE_COMPILER_WASM points the build at another compiler.wasm.
• The first build compiles SpiderMonkey from source. It needs clang, python3 and llvm-objdump on the path, which on macOS is a symlink to /usr/bin/objdump.
• The full setup is in CONTRIBUTING on GitHub.

edge run

Runs a script and streams its output to the terminal. An uncaught error prints a traceback to stderr and exits 1.

$ edge run broken.py
before
error: ZeroDivisionError: division by zero
  --> broken.py:2:1
  |
2 | x = 1 / 0
  | ^

raise SystemExit(code) with no argument or an integer exits cleanly with that code and no traceback. A string argument surfaces as a regular error and exits 1.

Run flags

• Without --save-state, a script parked on a wait the engine cannot serve prints an error and exits 1.
• edge test and edge repl take --memory and --ops too.

Run on the browser host

--web runs the script on the browser host in headless Chrome. The JS host and the engine come out of the binary and are served on a loopback port. Only the modules the manifest declares by URL leave the machine.

• It drives a Chrome the system already has.
• Without one, it offers to download one the first time into ~/.local/share/edge/chromium. edge uninstall offers to remove it.
• EDGE_CHROME_PATH names a browser directly.
• --events, --save-state, --restore-state and --preempt belong to the native engine. They are refused beside --web rather than ignored.
• --memory and --ops apply on both hosts.

Module resolution

Every run happens under the sandbox limits with a real wall clock. sleep() and timeouts wait in real time.

• A bare import resolves through edge.json. Declare it with edge add and resolve it with edge lock first.
• A declared version resolves through the edge.lock beside the manifest that declared it.
• A relative import loads from disk relative to the importing file.
• A dotted import loads from the nearest edge.json directory.

Cache

$XDG_CACHE_HOME replaces ~/.cache when it is set.

Module errors

A module that fails to load fails at compile time, at the import that names it. (via <importer>) is appended when another module reached it.

edge serve

Serves the current directory for browser apps. It reloads the page on any file change through a small polling client injected into served HTML.

$ edge serve
  http://localhost:5173
  watching .

edge repl

$ edge repl
Edge Python 0.9.5  ·  .reset to start fresh  ·  .exit, Ctrl+C or Ctrl+D to quit
>>> from math import sqrt
>>> print(sqrt(2))
1.4142135623730951

One interpreter stays alive across prompts.

• Imports, definitions and mutations persist. An input that raises keeps the effects it made before the error.
• Each line is one input. A compound statement goes on a single line, such as def double(n): return n * 2.
• Expression results are not printed. Use print().
• Arrow-key history works within the session and is not saved to disk.
• .reset wipes the session state. .exit, Ctrl+C and Ctrl+D quit.

edge test

Discovers *_test.py files recursively and runs each in a fresh interpreter. It skips dist/ and hidden directories and prints a verdict per file. A directory argument narrows discovery to that subtree, and a file argument runs that file alone.

$ edge test
pass. adds
1 passed, 0 failed
  (successful) main_test.py
pass. parses
1 passed, 0 failed
  (successful) lib/parse_test.py

  2/2 files passed · 0.0s

• Test files declare tests with the test package and do not call run(). The runner drives it after the file loads.
• The verdict comes from the SystemExit code of the file, never from parsed output.
• A file that registers no tests fails. State never leaks between files.
• The project must declare test in edge.json. Otherwise the runner stops with declare test in edge.json (edge add test).

--web runs the same files on the browser host in headless Chrome. A package proves it works where the system calls run in a real browser. One browser serves the whole suite with a fresh page per file.

• Discovery, the test declaration and the exit codes stay the same.
• The engine comes out of the binary the way edge run --web gets it.

edge init

Creates a ready-to-serve project. With no argument it scaffolds the current directory.

$ edge init my-app
  created my-app/
    ├─ index.html
    ├─ main.py
    └─ edge.json

  cd my-app && edge serve

• --bare skips index.html for script-only projects.
• The manifest holds only the edge version that scaffolded it. Nothing resolves until edge add fills it.

edge add and edge remove

Edits edge.json by name. You never paste URLs. Each line prints the name and what it wrote.

$ edge add math
  + math       0.1.0

  updated edge.json, run edge lock to resolve it

• An unknown name or version aborts the whole command before any write.
• A URL goes to imports too. Each host tells a code module from a native module by the artifact.
• A .js or .mjs URL is refused before anything is written.
• edge add keeps extends and every other key already in the manifest.
• edge remove deletes entries by name the same way.
• Neither command touches edge.lock.

edge lock

Turns each version edge.json declares into the URL and digest of that release.

It writes them to edge.lock beside the manifest. Commit the lock. Every other command reads it.

$ edge lock
  + json       https://cdn.edgepython.com/pkg/json/0.1.0/app.edge

  wrote edge.lock

• This is the only command that asks a registry where a name points.
• It rebuilds the whole lock each time. Run it again after editing edge.json to bring the two back in step.
• It records a digest for a bare URL too. Those bytes are pinned as well.
• edge run, edge test and edge build read the lock and never resolve a version themselves.

edge build

Packs the project and its imports into one artifact.

$ edge build

  packed app.edge (2 files)
  0.06 KB

  run  edge run app.edge   or send it to an actor eval group

--out <path> replaces the default output, app.edge, app or dist/ per mode.

• Every mode carries each module the manifest declares by URL, with the files it imports beside it. The artifact is the whole program.
• A .edge and an app binary carry the lock beside each manifest they carry. The artifact resolves its own names.
• A --web build rewrites every root import to a vendored path, its relative imports and a sibling edge.json included. It leaves the root lock out of dist/, and a nested package keeps its own.
• An app binary honors the run flags --save-state, --restore-state, --preempt and --events.
• A .edge and an app binary carry the README.md and any LICENSE at the project root.
• A .edge carries the pages when edge.json declares a docs directory. They sit under a reserved @docs/ prefix no import can reach.

Pages must follow the package docs convention, or the build fails.

edge publish

Uploads a .edge packed by edge build. Set EDGE_TOKEN to a token from the settings first.

$ export EDGE_TOKEN=edge_pat_...
$ edge publish app.edge
  published slugify 0.1.0

  add it with  edge add slugify
  https://cdn.edgepython.com/pkg/slugify/0.1.0/app.edge

• The artifact is the whole request. The name and version come from the manifest inside it.
• The CLI signs each publish with the token rather than sending it. The token never leaves your machine.
• A bundle that carries a .js or .mjs file is refused before it is sent.
• Publishing a version that already exists exits 2 instead of 1. A script can tell it apart from a failure.

What the registry reads, the naming rules, the quotas and the signing are in Publishing.

edge actor

Runs many programs as cooperative actors over a few threads, described by an actor.yml. The manifest, the groups, the server and untrusted code are in Actors.

edge uninstall

Removes the binary and its PATH entry. The non-interactive equivalent is curl -fsSL https://cdn.edgepython.com/cli/uninstall.sh | sh.

Global flags

Ctrl+C cancels a running command with exit code 130.