Getting Started

ptool runs Lua scripts and injects a standard library for practical automation.

The main entrypoint today is:

ptool run <file>

For .lua files, you can also use the shortcut form:

ptool <file.lua>

For interactive exploration, ptool also provides:

ptool repl

When a script runs, ptool exposes its API through the global ptool table and the shorter alias p.

Install

On Linux and macOS, install ptool with the release installer:

curl -fsSL https://peterlits.net/ptool/install.sh | bash

The installer downloads the latest prebuilt release for the current platform, installs ptool to ~/.local/bin/ptool, and prints a PATH hint if needed.

To install a specific release tag instead of the latest stable release:

curl -fsSL https://peterlits.net/ptool/install.sh | bash -s -- v0.2.0

To install into a custom binary directory instead of ~/.local/bin:

curl -fsSL https://peterlits.net/ptool/install.sh | bash -s -- --bin-dir "$HOME/.cargo/bin"

Minimal script

ptool.use("v0.1.0")

ptool.run("echo", {"hello", "world"})

ptool.use(...) declares the minimum required ptool version for the script. This keeps scripts explicit about the API version they expect and fails early on older runtimes. See Core Lua API for details.

Run it with:

ptool run script.lua
ptool script.lua

Passing arguments

You can pass extra CLI arguments after the script path:

ptool run script.lua --name alice -v a.txt b.txt
ptool script.lua --name alice -v a.txt b.txt

Parse them inside the script with ptool.args.parse(...).

Shebang scripts

ptool supports shebang files. With the .lua CLI shortcut, a script can start with:

#!/usr/bin/env ptool

This lets you execute the script directly once it has the executable bit.

What you get

• A script runner that understands shebang files.
• An interactive REPL for trying Lua expressions and ptool APIs directly.
• Lua helpers for semver, paths, files, TOML, regexes, strings, HTTP, SSH, databases, and templates.
• CLI-oriented helpers for running commands, parsing arguments, and asking for interactive input.

Next steps

• Open REPL for interactive usage, multi-line input, and keyboard behavior.
• Use Lua API Overview to browse the core APIs and available modules.
• Start with Core Lua API for version gating, process execution, config, and script lifecycle helpers.
• Open a module page such as Args API when you need the detailed reference for a specific feature set.