samytools is a flat shelf of command line scripts, each one solving a single annoyance

Every tool is a file in the repository root, not a package

samytools is described as a collection of simple but effective tools to use on the command line to improve computing, and its subtitle is tools for console cowboying. The repository listing makes the shape obvious. Alongside the README there are executables with no extension at all: 2svg, 3, GET, aes, aire, alert, alexa, all, ana, appkey, arduino, asm, asm2pl, asn1, avg, b64, baud, beep, bl, and many more, running into the hundreds across the alphabet.

The primary language of the repository is Perl, and the description notes that these are mostly Unix tools with an emphasis on macOS. Several entries say so explicitly, marking them as OS X only.

There is no package manifest, no dependency install step and no module system. The tools are scripts you put on your path, and the repository is a directory you clone and start reading. The README's format reinforces that: a bold tool name, a one line description, and often a usage example in backticks. Where a tool has no description, the entry is just a name, and the README has a number of those: ana, b2h, bl, ccchanbw, ccdeviatn, ccdrate, ccfreq, char, dcc, desktopinfo, ds, exp and others are listed with a hyphen and nothing else.

That incompleteness is the honest characterisation of the project. It is a personal working set that was written as needed, with the useful parts documented and the rest left to be discovered by reading the source.

The documented tools are conversion, decoding and signal work

The tools that do have descriptions cluster into a few clear categories.

The first is numeric and format conversion. The 3 entry is a combined calculator and base converter. avg averages numbers, taking the numbers and optionally a repeat count. b64 decodes or encodes base 64, with the direction given as a flag. baud determines a baud rate from bit widths. hex2bin converts an Intel hex file to binary, and asm2pl converts 8051 assembly to Perl, which is an interesting artefact in its own right. de_bruijn generates a De Bruijn sequence, and xor encodes or decodes with XOR across two files or two data values.

The second is comparison and inspection. diffbits diffs two equal length sets of binary data row by row, and diffdir diffs two directories by comparing filenames rather than contents, which is a fast way to find what a build changed. same looks for identical files quickly and takes an optional match regexp and an optional ignore regexp. baud and the serial tools sit in the same family of byte level work.

The third is a set of capture and analysis helpers that lean on external tools. ocr converts an image, local file or URL, to text through tesseract and cleans the image up first with ImageMagick. spec is a GPU accelerated spectrum analyzer. rtl makes listening to and saving data from an rtl-sdr or a hackrf faster, and a later entry describes it as using rtl_fm or hackrf_fm to listen to a frequency with a default of AM modulation and a high sample rate, with the usage line given as rtl [-s squelch] [-m modulation] [-b baudline] [-l lowpass] frequency in Hz or MHz with an optional output file.

pm3cs8 converts a proxmark3 trace to the cs8 format for Inspectrum, which is a very specific piece of radio forensics tooling.

A few scripts reach into the system, and that is where care is needed

Some entries change machine state, and the README says so in as many words.

aire resets the wifi on macOS, and the comment is blunt: the network will disconnect temporarily. ipfwd enables or disables IP forwarding, temporarily or permanently, with a usage that takes a count of seconds to leave it enabled and seconds to disable it, enabling on exit. disable_swap disables the macOS dynamic pager and removes vm/swapfile. cpu unloads OSX Crashplan, which is a background backup daemon. alert plays a sound when a command completes, so a long running command can announce itself without a terminal watcher.

appkey sends keystrokes or shortcut keys to a specific application or globally, to control them programmatically. That one is the most capable tool in the set, and also the one where reading the source before running it matters most.

Two more operate on a serial connection. serialsniff sniffs a serial connection on macOS and prints all unprintable characters, which is the tool you reach for when a device is sending a protocol you cannot see. strace is described as a dtrace wrapper, and the usage line gives the familiar strace flags with either a PID, a name or a command.

The rest are single purpose conveniences. all loops a command over a list of files, so all 'tar -zxvf FILE' *tgz unpacks every archive in a directory. nocolor removes colour from piped input, which the README describes as useful when you are trying to parse data where colour codes are interfering. onchange runs a command whenever a file or directory changes, and the example syncs a directory to a remote host. wx is wget that also unpacks, and unpack recursively unpacks a file and any archives it contains, useful for .pkg files that are xar archives containing further gz or cpio archives, covering zip, bz2, gz, tar, cpio, xar, 7z and xz.

The join tool shows the author's taste for terse output

Several of the tools are demonstrations of an idea rather than utilities you would install. The clearest is j, which joins multiple arguments or stdin into a single string with an optional join parameter, and the README shows the kind of output it produces:

tigerblood:/b$ j 0 1 1 1 1 0 0 1 0 1 1 0 1 1 1 1
0111100101101111

tigerblood:/b$ j -s ,
first
second
third
first,second,third

That is two behaviours in one tool. With plain arguments it concatenates them into a bit string, and with -s and a separator it joins lines of input with that separator. It is a shell composer's tool, useful when you are building a command line out of fragments.

avg is the same kind of thing. Its usage is avg <numbers> [NUMBERxTIMES] [...], so it can repeat a value a number of times before averaging, which is a way to weight a sample without doing the arithmetic.

g is described as grep++ and has a usage line with file arguments, an -i=file option for a file of inputs, an -x option to run a command such as ls -lh, and a negated match form. It is a wrapper for search that can also act on the results.

The README is a list of these entries rather than a tutorial, which suits the project's purpose. Nothing here needs explaining beyond its usage line, and each one is small enough to read in a minute before you decide whether to trust it.

Radio, hardware and reverse engineering work runs through external tools

A noticeable cluster of the tools is about pulling data off hardware and putting it somewhere you can look at it.

There is the rtl family for software defined radio, the pm3 tools for proxmark3 traces, a gcode-xbox entry for controlling a Grbl based CNC machine such as a Carvey or an X-Carve from an Xbox controller, and an arduino entry with no description. The asm entry compiles, links and executes an .asm file via nasm, which is a one command path to running assembly.

The conv tool is a media converter for mp4, FLV, mov, AIF, flac, mp3, jpg, png, gif and bmp, and it is a thin wrapper over whatever converter is on the machine. b2h is listed with no description, and the repository also contains an autodxf2svg file and a dxf2svg file, which suggests a CAD drawing conversion path.

Two of these are worth calling out as genuinely useful beyond their own hobby. The unpack tool is a recursive unpacker that handles the awkward nested archive formats, and the README explains the motivating case precisely: files like .pkg that are xar archives containing further gz or cpio archives. A single tar invocation will not do that, and writing a loop to find the inner archive is a common annoyance.

The nocolor filter is the other one. Parsing output that happens to contain ANSI colour is a problem that most people solve badly, and a filter that strips it from a pipe is a small thing that saves a long debugging session.

The licence is unstated, and the scripts are read before they are run

The repository listing shows no licence identifier for the project, and the top level entries include a LICENSE file among the scripts. When a licence cannot be classified, the practical step is to read the file and decide for yourself rather than to assume the permissive default that most single file utilities carry. This is a licensing note rather than legal advice, and it matters more here than usual because the tools are meant to be copied into your own path.

The last push was on 2026-09-21 and the repository is not archived, so the collection is being added to. There are no GitHub releases, so there is no version to pin and no changelog to diff; the repository history is the only record of what changed.

Given the shape of the collection, the sane adoption model is to copy rather than to depend. These are single file scripts with no install step, and reading one before running it is a thirty second task that is well spent for anything touching a serial device, a network interface or a keyboard. The ones that write to your shell path are the ones you will keep: a base converter, a colour stripper, a recursive unpacker, a baud rate calculator, a quick file comparison.

The alternative to a personal script collection is your own shell alias file, or a language runtime with a package manager and versions. The difference in approach is that samytools trades version pinning and dependency resolution for a flat directory you can read end to end, which is a reasonable trade for a utility that does one thing and is meant to be edited when it does not quite do what you want.

Editorial conclusion

Adopt samytools selectively, by copying the two or three scripts that solve a problem you actually have, since each tool is a standalone executable with no shared runtime to install. Do not adopt it as a curated toolkit, because the README lists many entries with no description, the licence is not stated in the repository listing, and the macOS specific scripts will not run elsewhere. Verify first that the tool you want handles your input format, and read the script itself before running anything that touches a serial device or your network configuration, since aire and ipfwd change system state and the README says the network will disconnect temporarily.

Frequently asked questions

Official sources

1. Issues
2. README
3. samyk/samytools on GitHub