Skip to main content

magmascript

Scripting toolkit with domain-first subcommands for managing magmacrunch.com infrastructure.

Install

Requires Python >= 3.11.

pip install magmascript

pipx (best for CLI-only usage)

pipx install magmascript

Homebrew (macOS / Linux)

brew install magmacrunch-media/tap/magmascript

Development

git clone https://github.com/magmacrunch-media/magmascript.git
cd magmascript
python3 -m venv .venv
.venv/bin/pip install -e ".[all]"

Configure

# Auto-configure from MCP server
magmascript configure

# Or manually set environment variables
export MAGMA_API_KEY="your-mcp-key"
export GITHUB_TOKEN=$(gh auth token)
export MAGMACRUNCH_ROOT="/path/to/magmacrunch.com"

Or use ~/.config/magmascript/config.toml:

[mcp]
url = "https://magmacrunch.duckdns.org/mcp"
api_key = "your-key"

[pi.pi1]
host = "your-pi-host"
user = "jake"

[windows.mc1]
host = "your-windows-host"
user = "magma"

[gh]
token = "ghp_..."
owner = "magmacrunch-media"
repo = "magmacrunch.com"

[project]
root = "/path/to/magmacrunch.com"

Machines are named, so a second Pi or PC is one more section, such as [pi.pi2]. With several of a kind, mark one default = true or pick per command with --host pi2. The older single sections, [pi], [mc1] and [mac], still work. See Configuration.

MagmaScript Language

Write .mgs scripts using a Python-inspired mini language with direct access to all domains.

Quick Start

# Run a script (shorthand)
magmascript scripts/examples/hello.mgs

# Run with arguments
magmascript scripts/examples/top-scores.mgs tetris

# Or use the explicit run subcommand
magmascript run scripts/examples/hello.mgs

# Start interactive REPL
magmascript repl

# Format files, keeping comments; --check lists, --write rewrites
magmascript fmt --check scripts/examples/*.mgs

fmt changes layout and nothing else. It keeps every comment, the author's blank lines and any statement spread over several lines inside brackets, and it checks the result parses to the same program with the same comments before writing; a file it cannot keep whole is reported and left alone.

Syntax Overview

// Variables
name = "MagmaCrunch"
version = 2

// String interpolation
print(f"Hello, {name} v{version}!")

// Functions
double = fn(x) { x * 2 }
result = double(21)

// Arrow functions
triple = x -> x * 3

// Script arguments
args_list = args()
if len(args_list) > 0 {
    print(f"First arg: {args_list[0]}")
}

// Control flow
if x > 10 {
    print("big")
} else {
    print("small")
}

// Loops
for i in range(5) {
    print(i)
}

while x > 0 {
    x = x - 1
}

// Dict literals
scores = {"Pong": 12, "Tetris": 45}
print(scores["Tetris"])

// List comprehensions
numbers = [1, 2, 3, 4, 5]
evens = [x for x in numbers if x % 2 == 0]
doubled = [x * 2 for x in numbers]

// String methods
csv = "apple,banana,cherry"
fruits = csv.split(",")
upper = [f.upper() for f in fruits]
print("-".join(upper))

// Domain calls work directly
boards = mcp.scoreboards()
for board in boards {
    print(f"{board.game}: {board.entries} entries")
}

Language Features

Import System

// Import a module (access as namespace)
intent "utils.mgs"
result = utils.greet("World")

// Import with alias
intent "utils.mgs" as u
result = u.greet("World")

// Import specific names
intent { greet, farewell } from "utils.mgs"
result = greet("World")

Error Handling

try {
    result = risky_operation()
} haunter (e) {
    print(f"Error: {e.message}")
}

// Throw custom errors
throw fire toad("something went wrong")

MagmaCrunch error vocabulary:

  • haunter: syntax/parse errors
  • fire toad: runtime errors
  • devastate: undefined variable errors
  • contemplate: type errors
  • spooked: warnings (non-fatal, prints to stderr)
spooked("this is a warning")

File I/O

content = quarry("data.txt")           // read file
litho("output.txt", "hello world")    // write file

HTTP Requests

response = http.get("https://api.example.com/data")
print(response.status)
print(response.json)

http.post("https://api.example.com/data", body={"key": "value"})

Shell Commands

result = exec("ls -la")
print(result.stdout)
print(result.exit_code)

Classes

class Dog {
    fn init(name) {
        self.name = name
    }

    fn bark(self) {
        return self.name + " says woof!"
    }
}

rex = Dog("Rex")
print(rex.bark())  // "Rex says woof!"

Default Parameters

fn greet(name, greeting="hello") {
    return greeting + ", " + name + "!"
}

greet("Jake")           // "hello, Jake!"
greet("Jake", "hey")    // "hey, Jake!"

Multi-Assignment

a, b = 1, 2
x, y, z = 10, 20, 30
a, b = [1, 2]  // list unpacking

in / not in Operators

if "key" in {"name": "Jake"} { ... }
if 5 not in [1, 2, 3] { ... }
if "xyz" not in "hello" { ... }

List/String Slicing

[1, 2, 3, 4, 5][0:3]     // [1, 2, 3]
[1, 2, 3][::-1]           // [3, 2, 1]
[0, 1, 2, 3, 4][::2]     // [0, 2, 4]
"hello world"[0:5]        // "hello"
"abcdef"[::-1]            // "fedcba"

Regex

"123abc".match("\\d+")            // ["123"] (match at start)
"abc123def456".findall("\\d+")    // ["123", "456"]

Built-in Functions

Function Description
print(...) Print to stdout
echo(...) Print to stdout (alias for print)
len(x) Length of string, list, or dict
type(x) Type name as string
range(n), range(start, stop), range(start, stop, step) Generate integer ranges
str(x), int(x), float(x) Type conversions
abs(x), min(...), max(...), sum(...) Math utilities
keys(d), values(d) Dict operations
args() Get script arguments from CLI
quarry(path) Read file contents
litho(path, content) Write content to file
exec(command) Execute shell command, returns {stdout, stderr, exit_code}

String Methods

Method Description
s.split(sep) Split string by separator
s.join(list) Join list with string separator
s.upper() Convert to uppercase
s.lower() Convert to lowercase
s.contains(sub) Check if substring exists
s.replace(old, new) Replace substring
s.length() Get string length
s.startswith(prefix) Check if starts with prefix
s.endswith(suffix) Check if ends with suffix
s.strip() Remove leading/trailing whitespace
s.match(pattern) Match regex at start, return groups or none
s.findall(pattern) Find all non-overlapping regex matches

Example Scripts

See scripts/examples/ for working examples:

Script Description
hello.mgs Hello World and basic features
fibonacci.mgs Recursive functions and loops
top-scores.mgs Arcade leaderboards (all games or single game)
album-isrcs.mgs Get ISRCs/ISWCs for every song on an album
album-lookup.mgs Album research: MusicBrainz + ISRC/ISWC + rights
artist-rights.mgs Full artist rights catalog
pi-health.mgs Pi system health check
pi-traffic-report.mgs Nginx traffic analysis
deploy-and-verify.mgs Deploy to Pi with service verification
full-backup.mgs MusicBrainz backup pipeline
weekly-scores.mgs Weekly scores report in markdown
maintenance.mgs Weekly maintenance pipeline
real-domains.mgs Test real domain connections (MCP search, scoreboards, games)
domain-example.mgs Domain object overview and usage patterns
astheno-list.mgs A linked list built by hand in the arena
astheno-packing.mgs The same struct fields, two orderings, two sizes
astheno-faults.mgs Every memory fault, caught and named

The Asthenosphere: explicit memory

The layer beneath the lithosphere. A second tier where you manage memory yourself: a real byte arena, pointers, structs with visible padding, and integers that wrap like C's.

It is not faster than the dynamic tier: an i32 add still costs a Python dispatch. What it gives you instead is the thing C cannot: the interpreter sees every memory operation, so it catches the use-after-free, names the line that leaked, and hex-dumps a struct with its fields labelled. C's behavior, but narrated.

floorplan Point {
    tag: u8
    x: i32
    y: i32
}

layout(Point)              // prints the field table, padding rows included

p = garrison(Point)        // claim ground
p.x = i32(10)
p.y = i32(-20)
bathysphere(p)             // annotated hex dump
scorch(p)                  // release it

Widths are i8 i16 i32 i64 u8 u16 u32 u64 f32 f64. There is no integer promotion, i32 + u8 is an error pointing you at osmosis(), and / truncates toward zero on integer widths, as C does.

Mistakes are reported, not swallowed:

quicksand at demo.mgs:line 4, column 7
    |
  4 | x = p.peek(i32)
    |       ^
this ground was scorched at line 3 (garrisoned at line 1)
Fault Reported as
touching scorched ground quicksand, naming the line that scorched it
reading outside a block area does not exist, with the block's extent
never scorching spooked: ancient weeds at exit, naming each garrison line
arithmetic that does not fit spooked, with the exact value and the wrap

floorplan is the only new reserved word; everything else is a shadowable builtin, so existing scripts are unaffected. Full reference on the Asthenosphere wiki page.

REPL

Start an interactive MagmaScript session:

magmascript repl

Features:

  • Syntax highlighting via Pygments
  • Tab completion for keywords, builtins, domain methods, and user-defined variables
  • Persistent history across sessions (~/.magmascript_history)
  • Multiline editing with proper continuation prompts
  • Dot-commands:
Command Description
.help Show available commands
.exit Exit the REPL
.clear Clear the screen
.ast Show AST for last expression
.magma System status dashboard
.crunch <target> Run batch pipeline
.texas <target> Full/heavy operation
.toast <target> Burn/clear caches

Domains

MCP Domain: MusicBrainz, scores, Discogs, write operations

magmascript mcp scoreboards                  # game leaderboards
magmascript mcp scores tetris                # tetris scores
magmascript mcp search "radiohead"           # search MusicBrainz
magmascript mcp entities                     # all cached entities
magmascript mcp games                        # arcade games
magmascript mcp mb-search "album name"       # search MusicBrainz releases
magmascript mcp mb-release <mbid>            # get release details
magmascript mcp mb-recording <mbid>          # get recording details

Pi Domain: Direct SSH to Raspberry Pi

magmascript pi status                        # all service statuses
magmascript pi logs arcade-chat              # service logs
magmascript pi restart arcade-chat           # restart service
magmascript pi info                          # uptime, memory, temp, disk
magmascript pi deploy arcade/chat-server.py  # deploy files
magmascript pi backup musicbrainz            # backup + commit to GitHub
magmascript pi traffic                       # nginx traffic analysis

Windows PC domain (windows): management over SSH

Manages Windows PCs over SSH with PowerShell, any running OpenSSH. Each is named in config as [windows.<name>]; magmascript windows hosts lists them, and --host <name> picks one when there are several.

// In a .mgs script
info = windows.info()
print(f"CPU: {info.cpu_load}, Memory: {info.memory}")

other = windows.on("mc2").info()    // another configured PC

services = windows.services()
for svc in services {
    print(f"{svc.name}: {svc.status}")
}

windows.restart("OllamaSvc")
windows.set_power_mode("always-on")

Also on the CLI: magmascript windows status, info, processes, memory (commit headroom, and WSL's real use apart from page cache), restart <service>, power, set-power-mode <always-on|sleep>, wake <mac>, reboot, each taking --host <name>.

mc1, the domain's old name, still works on the command line, in scripts and as MC1Client: it means the host named mc1, or the default if none is.

Note: windows commands connect over SSH, so run them from another machine. Run on the Windows PC they point at, they SSH into that same machine and hang.

Mac Domain: Mac management (via SSH)

// In a .mgs script, or: magmascript mac info
info = mac.info()
print(f"{info.hostname}, {info.os_version}")
print(f"{info.cpu_name} ({info.cpu_cores} cores), {info.memory}")

// Keep a checkout in sync
print(mac.git_status())
mac.git_pull()

Also on the CLI: magmascript mac info, mac processes, mac git-status, mac git-pull, mac run "<cmd>".

GitHub Domain: Direct API access

magmascript gh workflows                     # all workflow statuses
magmascript gh trigger "Deploy to Pi"        # trigger workflow
magmascript gh runners                       # self-hosted runners: online, busy
magmascript gh issues                        # list issues
magmascript gh file path/to/file.txt         # read file
magmascript gh sync                          # diff + commit all data files

Scores Domain: Game high scores

magmascript scores list                      # all game leaderboards
magmascript scores get tetris                # tetris scores
magmascript scores report                    # markdown report
magmascript scores report --discord          # Discord JSON payload
magmascript scores reset tetris              # reset one game (backup created)

Archive Domain: Archive page operations

magmascript archive check-format             # validate HTML formatting
magmascript archive generate-stubs           # generate stub HTML for new entities

MusicBrainz Domain: MusicBrainz API client

magmascript mb backup                        # full MusicBrainz backup
magmascript mb backup --dry-run              # preview backup
magmascript mb backup --stale-only           # only refresh stale caches

Last.fm Domain: Last.fm API client

magmascript lastfm fetch                     # fetch play counts
magmascript lastfm fetch --skip-existing     # skip cached artists

Search Domain: Site search index builder

magmascript search build-index               # build search-index.json
magmascript search preview 10                # preview first 10 entries

Rights Domain: Music rights metadata (ISRC, ISWC, ASCAP)

magmascript rights search "Farewell"         # search by title, ISRC, ISWC, or ASCAP ID
magmascript rights catalog "C.P. Rutledge"   # full rights catalog for an artist
magmascript rights export                    # TSV export for ASCAP forms
magmascript media search "sunset"            # search all providers
magmascript media providers                  # list available providers

Cache Domain: Cache management

magmascript cache stats                      # show cache statistics
magmascript cache clear                      # clear all cache

Magma: System status dashboard

magmascript magma                            # version, domains, cache stats

Crunch: Batch pipeline

magmascript crunch mb                        # MusicBrainz backup
magmascript crunch lastfm                    # Last.fm fetch
magmascript crunch search                    # Build search index
magmascript crunch archive                   # Archive pages
magmascript crunch scores                    # Scores update
magmascript crunch gh                        # GitHub sync
magmascript crunch all                       # Run all targets

Texas: Full/heavy operation (same targets, no shortcuts)

magmascript texas mb                         # Full MusicBrainz backup
magmascript texas lastfm                     # Full Last.fm fetch
magmascript texas search                     # Full search index rebuild
magmascript texas archive                    # Full archive processing
magmascript texas scores                     # Full scores update
magmascript texas gh                         # Full GitHub sync
magmascript texas all                        # Full heavy run

Toast: Burn/clear caches

magmascript toast cache                      # Clear general cache
magmascript toast mb-cache                   # Clear MusicBrainz cache
magmascript toast lastfm-cache               # Clear Last.fm cache
magmascript toast scores-cache               # Clear scores cache
magmascript toast gh-cache                   # Clear GitHub cache
magmascript toast search-index               # Remove search index
magmascript toast all                        # Clear everything

Domains from other packages

A package can publish its own domain by declaring an entry point; it then appears in .mgs scripts and the REPL without any change to magmascript.

# in the other package's pyproject.toml
[project.entry-points."magmascript.domains"]
texastoast = "texastoast.mgs:TexastoastDomain"

The value names a class taking a single config argument. It is constructed on first use, not at startup, so a domain may hold real resources. Built-in domains win a name clash, and an entry point that fails to import is skipped rather than breaking the interpreter.

texastoast is the first: pip install texastoast and .mgs scripts can drive a game engine. It registers under two names, texastoast and the shorter tt.

g = tt.game({"title": "hello", "width": 400, "height": 300})

A package may register the same class under several names this way; nothing stops it, and the clients stay independent. Note that none of this touches the magmascript toast CLI verb, which still clears caches, registry domains are not dispatched as subcommands.

Python Library

from magmascript import MCPClient, PIClient, GHClient, RightsClient

# MCP
with MCPClient() as mcp:
    boards = mcp.scoreboards()
    releases = mcp.mb_search_releases("album name")

# Pi (direct SSH)
with PIClient() as pi:
    status = pi.services()
    info = pi.info()

# GitHub (direct API)
with GHClient() as gh:
    workflows = gh.workflows()

# Music rights metadata
with RightsClient() as rights:
    catalog = rights.catalog("C.P. Rutledge")

Shell Helpers

source lib/magmascript.sh

mcp_scoreboards          # MCP commands
pi_status                # Pi commands
gh_workflows             # GitHub commands

Documentation

Full documentation on the Wiki:

Support This Project

If you find magmascript useful, consider supporting its development:

Sponsor PayPal

License

MIT

Metadata

Release files for magmascript 4.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for magmascript 4.4.0
File Size Uploaded Provenance Actions
magmascript-4.4.0.tar.gz 200.4 kB With provenance Details for magmascript-4.4.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for magmascript 4.4.0
File Interpreter ABI Platform Actions
magmascript-4.4.0-py3-none-any.whl Python 3 none any Details for magmascript-4.4.0-py3-none-any.whl

Total release size: 386.0 kB

Release files / magmascript-4.4.0.tar.gz

Download URL magmascript-4.4.0.tar.gz
Size 200.4 kB
Tags Source
SHA-256 checksum
How to use checksums
75266584fe89718647cc5ef56b23a773c4c3a10a734ba93c61a8295ff93d751a
BLAKE2b-256 checksum
How to use checksums
a9fa7840c6cac537672d2b2f81a2e6119ac11f592530d2a52c95ff9cbf84bf50
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

Release files / magmascript-4.4.0-py3-none-any.whl

Download URL magmascript-4.4.0-py3-none-any.whl
Size 185.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7bf5197de350ba585b355176f203eceb0d6f8b9bc087663a556263c5c3f6889f
BLAKE2b-256 checksum
How to use checksums
d1f86cf610260d7ae63dbefc21fd8b5eb2d4ec6b54038b0bd0792ee2d2e77ee0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

Security for magmascript 4.4.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for magmascript-4.4.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page