ACT

act allows you to install, run, and manage scripts with ease.

WHY

I really love the simplicity of uv's inline dependency definitions right on top of Python files. act takes this idea and extends the script header with a command property and then allows global calls to these scripts by their command name via, for example, act run helloworld. Additionally shims are created for each script in the ~/.act/bin directory, allowing you to run scripts directly without the act run prefix.

SYNOPSIS

act <command> [options] [arguments]

USAGE

Installs a script from the community-scripts directory:

$ act install weather
'weather' is a community script by janoelze.
It may access the internet, read and write files, and use third party libraries.
Are you sure you want to install this script? [y/N]: y
Community script 'weather' installed successfully.
Successfully recreated shims for 2 scripts in '/Users/janoelze/.act/bin'.

Runs the script with the city argument:

# Runs the weather script with the city argument
$ act run weather --city Berlin
Berlin: 🌨  +2°C
Done in 0.50s.

Or—if you've added the ~/.act/bin directory to your PATH—you can run the script directly:

# Runs the weather script with the city argument
$ weather --city Berlin
Berlin: 🌨  +2°
Done in 0.50s.

INSTALLATION

You can install or update act by running the following command in your terminal:

curl -fsSL https://raw.githubusercontent.com/janoelze/act/main/install.sh | sh

Uninstall act by running the following command:

curl -fsSL https://raw.githubusercontent.com/janoelze/act/main/uninstall.sh | sh

COMMUNITY SCRIPTS

Command	Description
benchmark	Benchmark a given URL using ApacheBench (Created by janoelze)	View
diskclean	List the largest files and directories in your home directory to help free up disk space (optimized with concurrency) (Created by janoelze)	View
helloworld	A simple script that prints 'Hello, world!' (Created by janoelze)	View
resize	Resizes the images in the current directory to a specified width (Created by janoelze)	View
tomp3	Convert any file format to an MP3 using ffmpeg (Created by janoelze)	View
tomp4	Convert any video format to a web-ready MP4 with small file size and reasonable resolution (Created by janoelze)	View
vpntoggle	Toggle VPN connection using OpenVPN (Created by janoelze)	View
weather	Get the current weather in Berlin (Created by janoelze)	View
ytdl	Download YouTube videos via yt-dlp (Created by janoelze)	View
ytdl-audio	Download the audio of a YouTube video via yt-dlp (Created by janoelze)	View

SCRIPT ANATOMY

The script header contains metadata that describes the script's behavior and dependencies.

#!/usr/bin/env python3
# /// script
# command = "helloworld"
# description = "Hello, world!"
# aliases = ["hw"]
# author = "janoelze"
# dependencies = []
# ///

import os

def main():
    print("Hello, world!")

if __name__ == "__main__":
    main()

Aliases are alternative names for the script that can be used to run it. For example, the helloworld script can also be run with the hw command:

$ act run helloworld
Hello, world!
$ act run hw
Hello, world!
$ hw
Hello, world!

COMMANDS

• create [script_name]
  Create a new script with a template header for metadata.
  Example: act create weather

• edit <script_name>
  Open an existing script in your default editor.
  Example: act edit weather

• run <script_name> [args]
  Execute a script, automatically handling its dependencies.
  Example: act run weather --city Boston

• delete <script_name>
  Remove an existing script.
  Example: act delete weather

• list
  List all available scripts by their command names.
  Example: act list

• meta <script_name>
  Display metadata of a specific script.
  Example: act meta weather

• install <script_name>
  Install a community script from the GitHub repository.
  Example: act install weather

• link
  Create shims for all installed scripts, making them globally accessible.
  Example: act link