DEVELOPER EXPERIENCE

Less code. More control.

Soul is built for explicit, readable filesystem automation. Tasks that usually require dozens of lines in Python, Bash or Go can often be expressed in a few Soul lines and compiled into a tiny native binary.

Benchmarks and binary sizes shown here are representative examples measured on specific workloads. Actual results depend on hardware, dataset and implementation details.

Soul

copy-folder.soul — 6 lines · 22 KB binary

str src = arg("--folderSrc")
str dst = arg("--folderDst")

printStr("Copying...")
copyFolder(src, dst)
printStr("Finished.")

copy_folder.py — 28 lines · needs Python runtime

import os, shutil, argparse, time

parser = argparse.ArgumentParser()
parser.add_argument('--folderSrc', required=True)
parser.add_argument('--folderDst', required=True)
args = parser.parse_args()

print("Copying...")
start = time.time()
count = 0

for root, dirs, files in os.walk(args.folderSrc):
    rel = os.path.relpath(root, args.folderSrc)
    dst_dir = os.path.join(args.folderDst, rel)
    os.makedirs(dst_dir, exist_ok=True)
    for f in files:
        src_f = os.path.join(root, f)
        dst_f = os.path.join(dst_dir, f)
        shutil.copy2(src_f, dst_f)
        count += 1

copy_folder.sh — 22 lines · shell script wrapper

#!/bin/bash
SRC=""
DST=""

while [[ $# -gt 0 ]]; do
  case $1 in
    --folderSrc) SRC="$2"; shift 2 ;;
    --folderDst) DST="$2"; shift 2 ;;
    *) shift ;;
  esac
done

echo "Copying..."
cp -r "$SRC" "$DST"

copy_folder.go — 55 lines · needs Go toolchain

package main

import (
    "flag"
    "fmt"
    "io"
    "os"
    "path/filepath"
)

func copyFile(src, dst string) error {
    in, _ := os.Open(src)
    defer in.Close()
    out, _ := os.Create(dst)
    defer out.Close()
    _, err := io.Copy(out, in)
    return err
}

Soul

backup.soul — 5 lines · 22 KB binary

str src = arg("--folderSrc")
str dst = arg("--folderDst")

mkdir(dst)
backup(src, dst)

backup.py — 40+ lines · needs Python runtime

import os, shutil, argparse, time

parser = argparse.ArgumentParser()
parser.add_argument('--folderSrc', required=True)
parser.add_argument('--folderDst', required=True)
args = parser.parse_args()

os.makedirs(args.folderDst, exist_ok=True)
copied = deleted = skipped = 0

for root, dirs, files in os.walk(args.folderSrc):
    rel = os.path.relpath(root, args.folderSrc)
    dst_dir = os.path.join(args.folderDst, rel)
    os.makedirs(dst_dir, exist_ok=True)
    for f in files:
        s = os.path.join(root, f)
        d = os.path.join(dst_dir, f)

backup.sh — rsync wrapper · external dependency

#!/bin/bash
while [[ $# -gt 0 ]]; do
  case $1 in
    --folderSrc) SRC="$2"; shift 2 ;;
    --folderDst) DST="$2"; shift 2 ;;
    *) shift ;;
  esac
done

if ! command -v rsync &>/dev/null; then
  echo "ERROR: rsync not found"
  exit 1
fi

rsync -av --delete "$SRC/" "$DST/"

Soul

delete-by-ext.soul — 12 lines · 21 KB binary

str folder   = arg("--folder")
str ext      = arg("--ext")
str password = arg("--password")

if startswith(password, "CONFIRM_DELETE"):
    printStr("Password confirmed")
    removeByExt(folder, ext)

delete_by_ext.py — 30 lines · needs Python runtime

import os, argparse, time

parser = argparse.ArgumentParser()
parser.add_argument('--folder', required=True)
parser.add_argument('--ext', required=True)
parser.add_argument('--password', required=True)
args = parser.parse_args()

if not args.password.startswith("CONFIRM_DELETE"):
    print("PASSWORD NOT APPROVED")
    exit(1)

delete_by_ext.sh — 25 lines · shell + find

#!/bin/bash
while [[ $# -gt 0 ]]; do
  case $1 in
    --folder) FOLDER="$2"; shift 2 ;;
    --ext) EXT="$2"; shift 2 ;;
    --password) PASSWORD="$2"; shift 2 ;;
    *) shift ;;
  esac
done

if [[ "$PASSWORD" != CONFIRM_DELETE* ]]; then
  exit 1
fi

Soul

delete-older-than.soul — 17 lines · native binary

str folder = arg("--folder")
str password = arg("--password")
str dias = arg("--days")

if dias == "":
    int days = 1
else:
    int days = toInt(dias)

if startswith(password, "CONFIRM_DELETE"):
    printStr("Password confirmed")
    
    if folder != "":        
        int maxAgeSeconds = days * 86400
        printStr("Cleaning files...")
        removeOlderThan(folder, maxAgeSeconds)

Why it matters

Safe cleanup logic in a tiny binary

This example shows the kind of maintenance task Soul is built for: argument parsing, explicit confirmation, defaults, numeric conversion and a direct filesystem action in a small amount of code.

Password-gated destructive action
Default value handling without extra boilerplate
Direct native execution with no interpreter dependency

Soul

move.soul — 25 lines · native binary

str src = arg("--folderSrc")
str dst = arg("--folderDst")

mkdir(dst)

diriter it = listdir(src)

while true:
    str name = dir_next(it)
    if name == 0:
        break

    str from = join(src, name)
    str to   = join(dst, name)
    move(from, to)

dir_close(it)

rmdir(src)

Why it matters

Explicit iteration over directory contents

This example is useful because it shows Soul doing more than a single builtin call. You can validate inputs, iterate over a directory, build source and destination paths, move entries and clean up the original folder in a compact and readable flow.

Readable low-level filesystem control
No runtime installation required
Good fit for server-side workers and automation jobs

Soul

overview.soul — 5 lines · native binary

str folder = arg("--folder")

printStr(folder)

overviewinfo ov = overview(folder)
str txt = overviewSummary(ov)
printStr(txt)

Why it matters

High-level filesystem inspection

Soul is not only about copy, delete or move operations. It can also expose higher-level analysis primitives so a program can inspect a folder, summarize its contents and produce actionable output with very little code.

Compact summary-oriented workflow
Useful for analysis, audit and planning tasks
Strong fit for future tooling like soul plan

⚡ Less boilerplate for filesystem workloads

📦 Native binaries with no runtime dependency

🐳 Small deployment artifacts, including scratch-ready images

BENCHMARK

Real-world Filesystem Performance

Same machine • Same datasets • Cold cache • Native binaries.
Note: Soul shines especially in tasks that combine filesystem access with logic and processing.

Task	Dataset	Soul	Go	Python	PHP	Bash
Soul Core Tools Performance
Analyzer – Full scan (extensions + biggest files)	210K files, 18 dirs	0.39s	0.71s	4.2s	5.8s	2.4s
Incremental Backup (scan + selective copy, 4 workers)	~1,600 files, 1.4 GB	1.9s	4.3s	38s	47s	—
Detailed Overview (stats + extensions breakdown)	210K files, 18 dirs	0.28s	0.44s	2.4s	3.1s	—
Recursive Folder Copy (4 parallel workers)	~1,600 files, 1.4 GB	4.8s	11.2s	48s	1m 14s	—
File search (walk + match across all dirs)	210K files, 18 dirs	2.3s	—	—	—	~2.5s
Other common operations
Create files	100K files	1.74s	2.3s	5.1s	5.7s	4.2s
Delete folder	100K files	1.34s	1.8s	4.3s	4.9s	3.1s
Create files	1M files	2m 01s	—	—	—	—
Delete by extension (selective)	~800 files	18ms	95ms	310ms	420ms	2.7s

Measured with /usr/bin/time -v on Linux (NVMe SSD, cold cache).
Soul results are from real executions of compiled Soul binaries (30–50 KB standalone, no runtime).
Other languages show optimized equivalent implementations.
Folder Copy and Backup use 4 parallel workers in Soul; Go comparison uses equivalent goroutine-based implementation.

Docker Image Size — Pure binary on scratch

Soul compiles to fully static binaries via musl-gcc. Docker images use FROM scratch — no base OS, no runtime, no layers. Just the binary.

Tool	Soul binary	Soul Docker (scratch)	Go (Docker)	Python (Docker)	Node.js (Docker)
hello-world	16 KB	44 KB	~2 MB	~50 MB	~70 MB
overview	17 KB	68 KB	~4 MB	~50 MB	~70 MB
analyzer	30 KB	91 KB	~5 MB	~55 MB	~75 MB
backup (4 workers)	22 KB	130 KB	~6 MB	~55 MB	~75 MB
copy-folder (4 workers)	22 KB	130 KB	~6 MB	~55 MB	~75 MB
Full catalog: 13 tools — 247 KB total on disk • Docker images: 44–130 KB each • Pull any tool in under a second on any connection

Soul Docker images measured from Docker Hub via Docker Desktop. Go/Python/Node.js figures are representative of typical minimal implementations.
Soul binaries compiled with musl-gcc -O3 -static -s. Dockerfile uses FROM scratch with zero additional layers.

Run these benchmarks yourself →

Build ultra-fast filesystem tools.

A language for filesystem automation.
Compiled, explicit and Linux-first.

Native binaries

Filesystem-first

Built for Linux

Explicit by design

Less code. More control.

Safe cleanup logic in a tiny binary

Explicit iteration over directory contents

High-level filesystem inspection

Real-world Filesystem Performance

Docker Image Size — Pure binary on scratch

Simple, One-Shot Licensing

Free

Explorer

Architect

Build ultra-fast filesystem tools.

A language for filesystem automation. Compiled, explicit and Linux-first.

Native binaries

Filesystem-first

Built for Linux

Explicit by design

Less code. More control.

Safe cleanup logic in a tiny binary

Explicit iteration over directory contents

High-level filesystem inspection

Real-world Filesystem Performance

Docker Image Size — Pure binary on scratch

Simple, One-Shot Licensing

Free

Explorer

Architect

A language for filesystem automation.
Compiled, explicit and Linux-first.