Readable scripts, compact bytecode, Go-powered runtime.

Use a release binary

Download the Tiny executable for your platform, place it in a tools folder, and make sure that folder is available from your terminal.

# Windows
tiny.exe version

# Linux
./tiny_linux version

# Mac
./tiny_darwin version

Build on Windows

The repository includes a Windows build script that builds the runtime and compiler executable.

build.bat
tiny version

Build on Linux

The Linux build script produces `tiny_linux` and the embedded Linux runtime.

chmod +x ./build_linux.sh
./build_linux.sh
./tiny_linux version

Build on Mac

The Mac build script produces `tiny_darwin` and the embedded Darwin runtime.

chmod +x ./build_mac.sh
./build_darwin.sh
./tiny_darwin version

Command check

`tiny version` prints the language version and bytecode cache version. If this command works, the CLI is installed correctly.

tiny version

Variables

Use `let` for mutable bindings and `const` for values that should not be reassigned.

const language: string = "Tiny"
let count: number = 3

count = count + 1
count += 2
count++

Values

Core values include numbers, strings, booleans, arrays, objects, functions, classes, buffers, errors, and `null`.

let enabled = true
let empty = null
let words = ["tiny", "docs"]
let user = {
    name: "Ada",
    active: enabled
}

Strings

Backtick strings support interpolation with `${...}` expressions.

const name = "Tiny"
const version = 1

let label = `${name} docs v${version}`

Objects and arrays

Use dot access for named fields and bracket access for dynamic keys.

let numbers = [1, 2, 3]
numbers.push(4)

let user = { name: "Sam" }
user.role = "reader"
user["level"] = "beginner"

If and loops

while index < values.length() {
    const value = values.get(index)
    index = index + 1

    if value == 5 {
        continue
    }

    if value > 6 {
        break
    }
}

Classic `for`

for let i = 0; i < values.length(); i++ {
    io.println(values.get(i))
}

`for in`

for value in values {
    io.println(value)
}

Match

match state {
    "Small" {
        io.println("small")
    }
    "Medium" {
        io.println("medium")
    }
    _ { // default
        io.println("large")
    }
}

Standard modules

import std "io"
import std "json"

io.println(json.pretty({ ok: true }))

File modules

import "numbers.tiny" as Numbers

io.println(Numbers.sum([2, 4, 6]))

Exports

export const defaultStep = 1

export fn sum(values): number {
    let total = 0
    for value in values {
        total += value
    }
    return total
}

Plugin imports

The compiler includes native plugin support for external DLL/SO integrations. Plugins are imported separately from standard and file modules.

Installing libraries

Use tiny add to add a dependency to your tiny.json and download it. You can specify a custom alias name if desired.

# Install library using default repo name
tiny add github:owner/repo

# Install library using a specific alias name
tiny add aliasName github:owner/repo

# Install using a specific ref (branch, tag, or commit)
tiny add github:owner/repo@v1.0.0

Run tiny install to download all dependencies declared in your project's tiny.json file.

tiny install

Removing & Listing

Use tiny remove (or tiny rm) to delete a dependency from your project and its downloaded files.

# Remove project dependency and its global cache
tiny remove aliasName

# Remove dependency from project only
tiny remove aliasName --project-only

# Remove globally downloaded library cache
tiny remove owner/repo --global

Use tiny deps (or tiny list) to list all globally downloaded libraries and their versions.

tiny deps

Using libraries

Import library modules using the import lib syntax. Use "owner/repo" as the import path and provide an alias name.

import lib "owner/repo" as MyLib

Text

embedstr "./data.json" const data
io.println(data)

Binary

embedbin "./icon.png" const iconBytes
fs.writeBytes("icon-copy.png", iconBytes)

Directory

embeddir "./ui" const assets
const html = assets["index.html"]

Use cases

Bundled webview HTML, config files, templates, images, and other static resources that should travel with a distributed tool.

What Tiny loads

Tiny loads platform shared libraries. On Windows, paths without an extension resolve as `.dll`; on Linux, they resolve as `.so` and Darwin as `.dylib`.

import plugin "./hash" as hashPlugin

The runtime searches the current working directory, the executable directory, and registered import/source folders.

Required exports

The native library must export exactly the functions Tiny looks for: `TinyPluginCall` and `TinyPluginFree`.

// Tiny calls this with a method name and JSON payload.
TinyPluginCall(method, argsJSON) -> char*

// Tiny calls this after reading the returned string.
TinyPluginFree(ptr)

If either symbol is missing, plugin loading fails before any method is called.

Call payload

Each call is serialized as JSON. Tiny sends the method name separately and also includes it in the payload.

{
  "method": "hash",
  "args": [
    {
      "text": "Tiny",
      "method": "sha256"
    }
  ]
}

Return payload

Return normal JSON-compatible values: strings, numbers, booleans, arrays, objects, or `null`. Tiny maps the JSON result back into Tiny values.

{
  "success": true,
  "method": "sha256",
  "result": "..."
}

Wrapper responsibilities

Expose a Tiny-shaped API, not a native-shaped API. Prefer objects with named fields over positional argument lists when a call has several options.

Type the boundary

Use `interface`, `enum`, and return type hints in the `.tiny` wrapper so callers get validation and editor help before the native library is involved.

Keep JSON-compatible data

The native boundary is JSON-based. Pass simple Tiny values, arrays, and objects. Represent native resources as string handles.

Distribution

`tiny dist` scans plugin imports and literal `Plugin.load("...")` calls, copies plugin files into the release, and rewrites paths for the target package.

Cache path

Normal runs may create `.tinycache` bytecode beside the entry file. The cache is an implementation detail; source files remain the normal authoring format.

Distribution path

`tiny pack` and `tiny dist` turn bytecode, runtime assets, embeds, and plugin dependencies into deployable artifacts.

Concurrency path

`spawn` runs work in isolated VM state, while shared resources should be protected by `sync.mutex()` and `lock` blocks.

Native boundary

`native fn` compiles Go snippets through TinyGo/WASM, while plugins communicate with the VM through a JSON-compatible ABI.

Use `tiny version`

The version command is `tiny version`, with aliases `tiny ver` and `tiny v`. It is not `tiny --version`.

One defer per scope

The current parser permits one `defer` statement per function scope. Use one cleanup function that performs all cleanup work.

Plugins are JSON-boundary APIs

Keep plugin arguments and results JSON-compatible. Use string handles for native resources rather than exposing raw pointers to Tiny.

Ship plugin wrappers

Plugin users should import `.tiny` wrapper modules, not call raw native plugin methods directly. Wrappers provide types, defaults, validation, and editor help.

Cache is not your API

`.tinycache` files are generated artifacts. Do not edit them by hand; rebuild from source or use `--disable-cache` while debugging cache behavior.

Native functions need tooling

`native fn` requires Go and TinyGo where the native code is compiled. Plain Tiny scripts and packaged runtime execution do not require those tools.

Compile and run bytecode

Source is compiled into `.tbc` bytecode and executed by the VM. Cache files live under `.tinycache`.

Pack a standalone tool

tiny pack src/main.tiny -o mytool

`pack` bundles bytecode and the Tiny runtime into one native executable.

Distribute with native dependencies

tiny dist src/main.tiny -o release/app

`dist` resolves plugin/runtime assets and produces a clean release folder.

Windowed apps

tiny dist --windowed

Use this for GUI apps on Windows when you do not want a console window.