Quick install by platform

Windows & macOS

1. Go to the ethos-lang releases page.
2. Download the installer for your OS — .exe on Windows, .pkg on macOS. The installer includes both Ethos and Forge.
3. Run it. Both ethos and forge are added to your PATH.
4. Open a terminal and verify:

   ethos --version
   forge --version

There is also a standalone Forge .exe on the Forge releases page if you only want the package manager.

Linux — full instructions

Three install paths are available on Linux. All of them install the same Nuitka-compiled binary — no Python required at runtime.

Option 1 — OBS Repository recommended

Automatic updates via your package manager. Add the repo and install from software.opensuse.org. Packages are published for these distros:

The ethos-lang package recommends ethos-forge (the package manager) as an optional dependency.

Option 2 — AUR (Arch Linux)

# Using yay
yay -S ethos-lang

# Using paru
paru -S ethos-lang

# Manual AUR build
git clone https://aur.archlinux.org/ethos-lang.git
cd ethos-lang
makepkg -si

ethos-forge is available as optdepends.

Option 3 — Universal Tarball any distro

Works on any distro. Includes both ethos and forge. Download ethos-build.tar.gz from the releases page, then:

# Extract
tar -xzf ethos-build.tar.gz
cd ethos-build

# Make the installer executable
chmod +x install.sh

# Install system-wide (needs sudo):
sudo ./install.sh
# → installs to /usr/local/bin/

# OR install user-only (no sudo):
./install.sh
# → installs to ~/bin/ and updates your .bashrc

Android — Termux

Nuitka builds on Termux are not supported due to linker restrictions, so on Termux Ethos runs as a wrapper around the Python source code compressed as a zipapp. Prebuilt Termux binaries will ship after the Rust rewrite. Until then, .deb files and pkg integration are available from v0.5.0 beta onwards.

Option A — download a .deb manually

# After downloading the .deb file with wget or curl:
pkg update && pkg upgrade
pkg install python
pkg install ./path-to-the-deb-file.deb

Option B — add the Ethos Termux repo (recommended)

# 1. Add the repo to your sources list
mkdir -p $PREFIX/etc/apt/sources.list.d/
echo "deb [trusted=yes] https://amancode22.github.io/ethos-termux-repo/repo termux extras" \
  >> $PREFIX/etc/apt/sources.list.d/ethos-repo.list

# 2. Update and install
pkg update
pkg install ethos-lang ethos-forge

What's in a release

Every release I publish on the ethos-lang releases page contains a full set of platform binaries. Each asset ships with a SHA256 checksum so you can verify integrity. The v0.5.0-beta release, for example, contains 11 assets:

Build from source

Requires Python 3.10+. The Forge repo has no dependencies beyond the standard library.

# Clone and run Forge directly
git clone https://github.com/AmanCode22/forge.git
cd forge
python main.py --help

# Clone and build Ethos
git clone https://github.com/AmanCode22/ethos-lang.git
cd ethos-lang
# See BUILDING.md for full build instructions (Nuitka compilation)

Verify your install

$ ethos --version
$ forge --version
$ ethos
# Drops into the Ethos REPL
> say "Hello, Ethos!".
Hello, Ethos!

Syntax rules

• Every statement ends with a period (.).
• Keywords are case-insensitive — SET, Say, set all work.
• Strings use "double" or 'single' quotes.
• Indentation is ignored — the parser tracks blocks via keywords.
• Blank lines are ignored.
• Trailing periods on block keywords (end., otherwise.) are optional.

Lexer internals

is not          is above        is below        is at least
is at most      divided by      to the power of bring in
how to          otherwise if    run function    delete variable
to number       to decimal      to text         to boolean
to list         to tuple        to set          to dictionary
to bytes        to complex

Statements

say — Print ¶

say .
say "Hello.".
say score.
say 42.

Transpiles to print( ).

set — Assignment ¶

set <name> to <expr>.
set x to 10.
set name to "Aman".
set total to x times 3 plus 1.

String slicing:

set <name> to <source> from <start> to <end>.
set piece to name from 0 to 5.   # → piece = name[0:5]

Function return value:

set response to run requests.get with "https://api.github.com".
set random_num to run random.randint with 1, 10.

add / subtract — In-place arithmetic ¶

add <n> to <var>.
subtract <n> from <var>.

add 1 to counter.        # → counter += 1
subtract 5 from health.     # → health -= 5

delete variable ¶

delete variable <name>.

ask — Input ¶

ask " " into <name>.
ask "Your name: " into username.

Exactly 4 tokens required. into is mandatory. Returns a string — use type casting for numbers.

if / otherwise if / otherwise / end — Conditionals ¶

if <cond>.
  ...
otherwise if <cond>.
  ...
otherwise.
  ...
end.

Conditions support and, or, not:

if age is at least 18 and verified is 1.
  say "Access granted.".
end.

repeat — Count loop ¶

repeat <n>.
  ...
end.

Anonymous loop variable (_). Transpiles to for _ in range(n):.

count — Ranged loop ¶

count from <start> to <end> variable <i>.
  ...
end.

count from 1 to 5 variable i.
  say i.
end.

With step:

count from 10 to 0 variable i stepping -2.
  say i.
end.

The parser adjusts the range end by +1 (forward) or -1 (backward).

while — Condition loop ¶

while lives is above 0.
  subtract 1 from lives.
end.

how to / run — Functions ¶

# Define
how to <name>.
  ...
end.

how to <name> with <a>, <b>.
  ...
end.

# Call
run <name>.
run <name> with <a>, <b>.
run function <name> with <a>.

run and run function are identical. Dot notation works:

bring in requests.
run requests.get with "https://api.github.com".

bring in — Import ¶

bring in math.
set pi to math.pi.
set result to run function math.sqrt with 16.

note / notes — Comments ¶

note single line comment.

notes.
  block comment
  spanning lines.
endnotes.

python / pythonend — Inspect generated code ¶

python.
set x to 5 plus 3.
pythonend.

Output: PY_GEN: x = 5 + 3

debug / debugend — Token trace ¶

debug.
set x to 10.
debugend.

Output: DEBUG: set x to 10

Operators

Arithmetic

Comparison

Type casting

set age to "25" to number.     # → age = int("25")
set pi  to "3.14" to decimal.  # → pi  = float("3.14")

Errors

Ethos surfaces Python tracebacks directly, prefixed with context from the source sentence. If a Hard Trait fails to load, the runtime reports which trait and which function was missing.

Soft Traits — Python packages

Soft Traits are simply Python packages. Forge queries the PyPI JSON API, picks the best wheel for your platform (platform-specific first, then pure-Python any, then sdist fallback), downloads it, and extracts it into ~/.ethos/traits/. Forge never runs install scripts — it only extracts the archive.

For a package to be importable, its top-level module folder must land directly inside ~/.ethos/traits/ after extraction.

# Install from PyPI
$ forge pymodule get requests

# Then in Ethos
bring in requests.
set response to run requests.get with "https://api.github.com".
say response.

Hard Traits — Native binaries

A Hard Trait is a compiled shared library (a .so on Linux/Termux, .dylib on macOS, .dll on Windows) plus a manifest.json describing its functions. Ethos loads it via ctypes at startup.

Hard Trait folder layout

~/.ethos/traits/hard_traits/<name>/<version>/
├── manifest.json
└── (compiled binary here)

manifest.json ¶

The manifest declares the trait's name, version, author, license, all 8 platform binaries, checksums, and the functions Ethos can call. Every Hard Trait submitted to Foundry must include all 8 platforms.

Example manifest.json

{
  "name": "mymath",
  "version": "1.0.0",
  "description": "Fast integer math",
  "author": "Aman",
  "repository": "https://github.com/AmanCode22/ethos-trait-mymath",
  "license": "MIT",
  "tags": ["math"],
  "verified": false,
  "platforms": {
    "linux-x86_64":    { "url": "...", "checksum": "sha256: ..." },
    "linux-aarch64":   { "url": "...", "checksum": "sha256: ..." },
    "macos-arm64":     { "url": "...", "checksum": "sha256: ..." },
    "macos-x86_64":    { "url": "...", "checksum": "sha256: ..." },
    "windows":         { "url": "...", "checksum": "sha256: ..." },
    "windows-arm64":   { "url": "...", "checksum": "sha256: ..." },
    "termux-aarch64":  { "url": "...", "checksum": "sha256: ..." },
    "termux-armv7":    { "url": "...", "checksum": "sha256: ..." }
  },
  "functions": {
    "add_ints":    { "return": "int",    "args": ["int", "int"] },
    "get_message": { "return": "char *", "args": [] }
  }
}

Supported C types

Using a Hard Trait in Ethos

Here's the real end-to-end flow, using greetr — my verified Rust sample trait — as the example:

# Install a trait from Foundry
$ forge foundry get greetr

# Then in Ethos
bring in greetr.
set result to run greetr.greet with "Aman".
say result.

Writing your own Hard Trait

Start from one of the official templates — they include CI workflows that automatically build binaries for all 8 platforms when you tag a release.

Verified sample traits

Three sample Hard Traits — one per language — show how a real trait looks end-to-end. All three are on Foundry and verified. Each is a "greet" trait — the simplest possible native function that returns a greeting string.

Version & help

$ forge --version
$ forge -v
$ forge --help

Soft Traits — Python packages

Install from PyPI

$ forge pymodule get requests

Forge queries the PyPI JSON API, picks the best wheel for your platform (platform-specific first, then pure-Python any, then sdist fallback), downloads it, and extracts it into ~/.ethos/traits/.

Install from a remote wheel URL

$ forge pymodule wheel get <url>

Install from a local .whl file

$ forge pymodule wheel local <path>

Install from a remote sdist tarball

$ forge pymodule sdist get <url>

Install from a local .tar.gz sdist

$ forge pymodule sdist local <path>

Hard Traits — native binaries

Install from a URL

$ forge get <url>

Forge downloads the zip, finds manifest.json at any depth, validates name and binary, and moves the trait folder into ~/.ethos/traits/hard_traits/<name>/<version>/.

Install from a local zip

$ forge local <path-to-zip>

Foundry support

Foundry is the curated registry of Hard Traits. Forge can search and install directly from it.

# Search for a hard trait in Foundry
$ forge foundry search greetr

# Install a trait from Foundry
$ forge foundry get greetr

Listing installed traits

$ forge list            # everything
$ forge list pymodule   # Soft Traits only
$ forge list native     # Hard Traits only

Removing traits

$ forge remove <name>           # Hard Trait
$ forge remove pymodule <name>  # Soft Trait

Output prefixes

Forge uses consistent prefixes to indicate status:

Build from source

Requires Python 3.10+. No dependencies beyond the standard library.

$ git clone https://github.com/AmanCode22/forge.git
$ cd forge
$ python main.py --help

Status

Verified sample traits

Three sample "greet" traits — one per supported language — are verified and live on Foundry right now. They're the simplest possible reference implementations, useful as a starting point if you're writing your own.

Quick use

# Search the registry
$ forge foundry search greet

# Install a trait (e.g. my verified Rust sample)
$ forge foundry get greetr

# List what you have installed
$ forge list native

Then in Ethos:

bring in greetr.
set result to run greetr.greet with "Aman".
say result.

How it works — the full lifecycle

1. You write a Hard Trait using one of the official template repos (C, C++, or Rust). The template has GitHub Actions that build binaries for all 8 platforms automatically.
2. You tag a release (e.g. v1.0.0). The workflows build binaries for all 8 platforms and upload them to GitHub Releases.
3. You open a PR to Foundry with the auto-generated manifest.json from your release. You must open a PR to Foundry for each version bump also — the manifest in your release is different from the one in your source repo.
4. The PR is reviewed personally. If it looks good, it's merged. The trait goes live on Foundry.

Required platforms — all 8 required

Every trait must include binaries for all of these. No partial support.

Adding your trait

1. Fork a template. Pick your language:
   • C: ethos-trait-c-template
   • C++: ethos-trait-cpp-template
   • Rust: ethos-trait-rust-template
   These repos have starter code, build config, and CI workflows. They compile for all 8 platforms automatically when you tag a release. You don't need to build anything locally.
2. Build and release. Write your code. Push. Tag a release like v1.0.0. The workflows build binaries for all platforms and upload them to GitHub Releases automatically.
3. Open a PR. The GitHub workflow auto-creates a manifest.json for the PR. You just need to use that and you're done.
4. Review and merge. The PR is reviewed personally. If it passes, it's merged. The trait goes live on Foundry.

Updating your trait

When you release a new version:

1. Update your trait repo and tag a new release (e.g. v2.0.0).
2. The CI builds new binaries for all platforms and uploads them.
3. You open a PR to Foundry with the updated manifest.json.
4. The PR is reviewed and merged. Users get the latest version when they run forge foundry get.

You don't need to do anything extra. Just tag a release and open a PR.

Rules — the same rules apply to templates and platform support

Links

• Foundry repo: AmanCode22/ethos-foundry
• Live registry: foundry-ethos.pages.dev
• Mirror: amancode22.github.io/ethos-foundry
• Ethos docs: DOCS.md
• C template: ethos-trait-c-template
• C++ template: ethos-trait-cpp-template
• Rust template: ethos-trait-rust-template

Hello, Ethos

say "Hello, Ethos!".

Try in playground ▶

Variables and arithmetic

set a to 10.
set b to 20.
set sum to a plus b.
say sum.

set product to a times b.
say product.

set power to a to the power of 2.
say power.

Try in playground ▶

Input + if / otherwise

ask "What's your name? " into name.
set greeting to "Hello, ".
say greeting.
say name.

set score to 95.
if score is above 90.
  say "That's an A.".
otherwise if score is at least 75.
  say "That's a B.".
otherwise.
  say "Keep going.".
end.

Try in playground ▶

count loop with step

count from 1 to 5 variable i.
  say i.
end.

count from 10 to 0 variable j stepping -2.
  say j.
end.

Try in playground ▶

while loop

set lives to 3.
while lives is above 0.
  say lives.
  subtract 1 from lives.
end.
say "Game over.".

Try in playground ▶

Functions

how to greet with name.
  set msg to "Hello, ".
  say msg.
  say name.
end.

run greet with "Aman".

how to add with a, b.
  set result to a plus b.
  say result.
end.

run add with 5, 7.

Try in playground ▶

String slicing

set name to "Ethos".
set first to name from 0 to 1.
set rest to name from 1 to 5.
say first.
say rest.

Try in playground ▶

Type casting

set age_text to "25".
set age to age_text to number.
add 1 to age.
say age.

set pi_text to "3.14".
set pi to pi_text to decimal.
set twice to pi times 2.
say twice.

Try in playground ▶

Imports (Soft Trait)

bring in math.
set pi to math.pi.
say pi.

set r to run function math.sqrt with 16.
say r.

# works in local Ethos install; in the browser Playground, math is bundled with Pyodide so it also runs.

Try in playground ▶

Hard Trait usage — greetr, greetc, greetcpp

Three sample traits — one per language — are verified and on Foundry. Pick whichever language you want to learn from:

Then in Ethos — using greetr as the example:

# After: forge foundry get greetr
bring in greetr.
set result to run greetr.greet with "Aman".
say result.

# Hard Traits require a local Ethos install with ctypes — not available in the browser Playground.

v0.5.0-beta — Major bug fix, Termux support, Hard Trait API

# released 14 Apr 2026 · 11 assets · commit c16d82c · GPG signed

The v0.5.0-beta release ships major bug fixes alongside two significant additions: Termux support and the completed Hard Trait API.

Termux support is available through both the package repository and direct .deb downloads. Due to linker restrictions in the Termux environment, Termux builds require Python and are distributed as a zipapp of the source code. Native Termux binaries will ship after the Rust rewrite.

The Hard Trait API is completed with the introduction of Ethos Foundry, the official Hard Trait registry. Foundry is hosted on Cloudflare Pages and GitHub Pages, and provides pre-built hard traits. See ethos-foundry for details on submitting a trait.

This is the final beta release. Bug reports and feature requests are tracked via GitHub issues. The next milestone is the first stable release, followed by the Rust rewrite on a new branch. Windows ARM64 support is also included in this release.

What's new

• Termux support — available via the Termux repository and via downloadable .deb files.
• Hard Trait API — completed, with Ethos Foundry as the official registry.
• Windows ARM64 — support added to the combined installer.
• Major bug fixes across the transpiler and runtime.

Assets (11)

View release on GitHub ↗

v0.4.0-beta — The first beta, macOS support, type casting

# released 30 Mar 2026 · 9 assets · commit dd5ae77 · GPG signed

The v0.4.0-beta release is the first beta for the Ethos language. It introduces official macOS support, fixes several bugs found during testing, and expands Python standard library coverage within the Nuitka-compiled binary. Requests for additional standard library modules can be opened as GitHub issues.

Type casting is supported in this release using Ethos's English-like syntax. See the language documentation for details. The release also switches Windows builds from Nuitka onefile mode to standalone mode, which avoids a Windows Defender false positive that flagged onefile builds.

What's new

• macOS support — officially added for both arm64 and x86_64.
• Type casting — English-like syntax (to number, to decimal, to text, etc.).
• Expanded Python stdlib — additional modules bundled into the Nuitka binary.
• Standalone Windows builds — replaces onefile mode to avoid Windows Defender false positives.

View release on GitHub ↗

v0.3.0-alpha — Major Linux package manager support

# released 23 Mar 2026 · 6 assets · commit a64a315 · GPG signed

The v0.3.0-alpha release adds -v and --version flags to the Ethos CLI for version detection, and introduces major package manager support for Linux installations. Packages are published via the Open Build Service for supported distributions.

If a distribution is not supported by the OBS repository, the universal tarball (ethos-build.tar.gz) can be downloaded and installed via install.sh. The tarball installs both Ethos and Forge; the same applies to the Windows installer.

What's new

• Version flags — ethos -v and ethos --version.
• OBS repository — packages published at software.opensuse.org for openSUSE, Arch, Debian, Fedora, openEuler, and Ubuntu.
• Universal tarball — ethos-build.tar.gz with install.sh for unsupported distributions.

Assets (6)

• ethos — 8.4 MB (Linux standalone)
• ethos-build.tar.gz — 19.6 MB (universal tarball)
• Ethos-windows-installer.exe — 11.9 MB
• ethos.exe — 5.41 MB (Windows standalone)
• Source code (zip)
• Source code (tar.gz)

View release on GitHub ↗

v0.2.0-alpha — Windows support added

# released 21 Mar 2026 · 4 assets · commit 755b72e · GPG signed

The v0.2.0-alpha release adds Windows support to the Ethos programming language. The list and dict Python data types are now officially supported and tested, and float support has been added to the language.

What's new

• Windows support — native Windows installer and standalone binary.
• list and dict types — officially supported and tested.
• float support — added to the type system.

Assets (4)

• Ethos-v0.2-windows-installer.exe — 12 MB
• ethos.exe — 5.4 MB (standalone)
• Source code (zip)
• Source code (tar.gz)

View release on GitHub ↗

v0.1.0-alpha — The Foundation Release

# released 19 Mar 2026 · 3 assets · commit 606a90c · GPG signed

The v0.1.0-alpha release is the first public alpha of the Ethos programming language. It establishes the core foundation: a natural-language-inspired parser that transpiles human-readable syntax into a Python execution environment.

Key features in this alpha

• Natural language parsing — support for dynamic math expressions (set x to 5 plus 10), conditional logic (is above, is not), and control flow using explicit end blocks.
• Interactive I/O — fully functional say and the ask "Prompt" into variable syntax.
• The how to engine — define and execute custom functions natively.
• Hard Trait bindings — the core executer dynamically loads compiled C/C++ shared libraries (.so) mapped via manifest.json, bringing native performance into Ethos scripts.

Linux installation (standalone)

The Ethos binary is compiled using Nuitka; Python is not required to run it. Download the ethos binary, make it executable, and run a script:

chmod +x ethos
./ethos run script.ethos

Windows and macOS native binaries are planned for later releases. Non-Linux users can run Ethos directly from the Python source code. Android (Termux) builds are planned after the project reaches a stable release.

Assets (3)

• ethos — Linux standalone binary
• Source code (zip)
• Source code (tar.gz)

View release on GitHub ↗

Roadmap

Rule 1 — The PR rules are the Foundry rules

Rule 2 — Templates are required

Hard Traits must be built from one of the official templates:

Rule 3 — PR required per version bump

Every version bump requires a new PR to Foundry. Don't edit manifests in-place. The flow:

1. Update your trait repo and tag a new release (e.g. v2.0.0).
2. CI builds new binaries for all 8 platforms and uploads them to GitHub Releases.
3. The workflow auto-creates a new manifest.json for the PR — use that one, not the one in your source repo (they are different).
4. Open a PR to ethos-foundry with the updated manifest.
5. I review and merge. Users get the latest version via forge foundry get.

Rule 4 — No binaries in repos

Binaries live on GitHub Releases, not in source repos. PRs containing binaries (in the trait repo or in Foundry) are rejected. All URLs in manifests must be public, and SHA256 checksums are mandatory for every platform entry.

Rule 5 — Trait name must match folder name

The name field in manifest.json must match the folder name (and the repo name). For example, ethos-trait-mymath → name: "mymath" → same name used in CMakeLists.txt first line as project name. PRs with mismatched names are rejected.

Rule 6 — Public license only

MIT, Apache-2.0, etc. No proprietary licenses accepted on Foundry. The trait's license field in the manifest must match the LICENSE file in the source repo.

Where to contribute

Quick checklist before opening a PR

Communication

• GitHub issues — primary channel for bugs, feature requests, platform exceptions, and new-language-binding requests.
• Reddit DM — u/AmanCode22 — for testers and direct contact.
• Open an issue before starting large features to avoid duplicate work.