run-scripts

A personal collection of scripts for run - a script and task manager with a Lua-based scripting layer.

Everything here is written to be universal: it runs on macOS, Linux and Windows, without pulling in a package manager, and without assuming a shell you may not have.

Install

Install everything:

run manage install github.com/pt-main/run-scripts@main/run.task.lua --args="all"

Install only part of the collection:

run manage install github.com/pt-main/run-scripts@main/run.task.lua --args="text"
run manage install github.com/pt-main/run-scripts@main/run.task.lua --args="files"
run manage install github.com/pt-main/run-scripts@main/run.task.lua --args="python"

Group	Contents
text	Search, transform, hash and encode text and data. Pure Lua, no interpreter needed.
files	Find, rename, measure, protect and back up files. Pure Lua.
system	What is running and what is installed on this machine.
python	Scripts that require Python 3.
all	Everything.

Several groups can be combined:

run manage install github.com/pt-main/run-scripts@main/run.task.lua --args="text files"

To install into a project instead of the global storage, put --lm right after run:

run --lm manage install github.com/pt-main/run-scripts@main/run.task.lua --args="all"

After installing, list and run the scripts:

run manage list
run sysinfo

Every script supports --help. All of them also work as plain scripts, without run:

lua run-scripts/hashfile.lua sha256 README.md
python3 run-scripts/envcheck.py

Scripts

Text and data

Group: text

• hashfile - checksums for files, globs and directories. md5, sha1, sha256, crc32, adler32, all implemented in pure Lua. Can verify a sha256sum-style checksum file.
• codec - base64, hex, url, rot13, plus the fnv1/fnv1a/djb2/sdbm hashes.
• jsontool - a real JSON parser: pretty, minify, validate, get, set, merge, keys, type.
• tabler - CSV/TSV rendering as aligned tables or Markdown, conversion to and from JSON, select, sort, stats.
• timefmt - time conversion, ISO-8601 parsing, human durations, arithmetic, and a 5-field cron that prints the next fire times.
• idgen - uuid, ulid, nanoid, tokens and passwords from a seeded, unbiased generator.
• textgrep - recursive grep with no external tools: context lines, globs, JSON output, binary detection.
• diffq - text diff, unified or side by side, with --ignore-space and an optional word diff.
• linefix - bulk text transforms (replace, trim, dedent, strip comments, CRLF/LF, sort) with a dry run by default.

Files

Group: files

• dirsize - what is eating the disk: totals per entry, --depth aggregation, largest files.
• finddups - duplicate files by content, plus --empty, --large and --broken-symlinks.
• batchrename - bulk rename with {n}/{name}/{date}/{hash} templates, collision checks, and --undo.
• secretscan - finds committed credentials: provider token patterns, generic key = value, and a high-entropy detector. Exits 1 on findings, so it works as a pre-commit hook.
• backup - timestamped backups with a manifest, verify, restore and prune.

System

Group: system

• portscan - list listening ports, or check whether one is free (--check, --wait).
• sysinfo - system information: OS, kernel, CPU, memory, disk, Lua version.
• sysfetch - colored system info, rendered like a fetch splash.
• luabench - Lua speed benchmark, JIT on versus off.
• envcheck - report the state of the machine and the project: toolchains, repo hygiene, .gitignore coverage, env vars, free ports. --json and --strict for CI.

Require Python 3

Group: python

• go-build - universal cross-platform Go builder: parallel builds, per-platform overrides, checksums, archives. See run go-build --help.
• httpcheck - HTTP health checks with status/content/header assertions, retries with backoff, JSON output.
• selfupdate - atomic, verified updates of a script or binary from a URL or a GitHub release.
• portkill - find the process holding a port and free it.
• gitall - run a git command in every repository under a directory, in parallel, with a JSON report.
• projnew - scaffold a new project (go, python, node, rust, lua) with license, git and CI wired up.
• envgen - generate .env secrets, or audit an existing one without printing the values.
• addMit / addApache20 - write a license to LICENSE in the current directory.

Conventions

Every script in this repository follows the same rules, so that muscle memory learned on one of them works on all of them:

• --help first. It is handled before any side effect, so --help is always safe.
• Exit codes mean something. 0 success, 1 failure, 2 "nothing to do". Where a script has a different convention, it says so in its own help.
• Nothing destructive happens by default. batchrename, linefix and secretscan all require an explicit flag to write, delete or rename. finddups prints the full plan before it removes anything.
• Never prompt. These run in CI and in pipelines. A script that needs a decision takes a flag instead.
• Colors are opt-out. NO_COLOR and --no-color both work everywhere.
• Machine output when asked. --json is available on anything that is useful to pipe into another program.
• Paths with spaces are quoted. User input is never pasted into a shell string unescaped.

Compatibility

The Lua scripts are written in the Lua 5.1 dialect and avoid //, bitwise operators, goto, math.type, utf8 and table.move. That is deliberate: run embeds gopher-lua, while luabench and the interpreter on your machine may be Lua 5.4 or LuaJIT. The scripts are tested on both.

The Python scripts target 3.8+ and use only the standard library.

Add your own script

1. Put the script file in this repository.
2. Add one install(...) call to the matching -- @text, -- @files, -- @system or -- @python block in run.task.lua.
3. Add it to the -- @all block if it belongs to no existing group.
4. Update the lists above.

A description must not contain quotes or apostrophes: it is passed as a single quoted word, and a stray quote would break the whole command.

Notes on individual scripts

License scripts

addMit and addApache20 take the copyright holder as an argument, and use the current year unless --year is given. A holder with spaces must stay quoted, because --args is parsed as a shell-like line:

run -r addMit --args="'Pt'"
run -r addMit --args="'Acme Inc' --year 2019"
run -r addApache20 --args="'Acme Inc'"

They refuse to overwrite an existing LICENSE unless --force is passed. Use --file to write somewhere else:

run -r addMit --args="'Pt' --file docs/LICENSE --force"

secretscan

run secretscan --path src --severity high
run secretscan --json > findings.json

Values are masked in the output, so a report can be pasted into an issue. Rules are provider patterns (GitHub, AWS, Slack, Stripe, OpenAI, Telegram and others), a generic password = "..." detector, and a Shannon-entropy check for values that look random enough to be a key. The entropy threshold is tunable with --min-entropy, and the generic detector can be turned off with --no-entropy.

The placeholder filter is deliberately conservative: it only suppresses values that are obviously filler, because a secret scanner that hides real keys is worse than no scanner at all.

backup

run backup ~/work --label nightly --verify
run backup list
run backup restore 20260927-143211-nightly
run backup prune --keep 10

Backups land in ~/.cache/run-scripts/backup (override with --cache or BACKUP_CACHE). Each archive carries a manifest recording the original paths and the names used inside the tar, which is what makes restore able to put things back where they came from. verify re-reads the archive and checks that every manifest entry is present.

envcheck

run envcheck --project . --env CI,TOKEN --ports 3000
run envcheck --json --strict

Exit codes: 0 when every requested probe passed, 1 when one failed, and with --strict a warning is a failure too. Useful as a CI gate before a build.