GitHub Actions CLI (ghactl)

ghactl is a CLI for GitHub Actions workflows. It exposes the same capabilities as the JavaScript GitHub Actions Toolkit as shell commands, so you can use them directly in run: steps without writing a custom action.
Why ghactl?
The official toolkit packages only work in JavaScript/TypeScript actions. Workflow commands exist for shell steps but the coverage is limited and the syntax is fiddly. ghactl is a single binary that gives shell steps access to tool-cache management, downloads, archive extraction, and version resolution.
Features
- Find, list, and cache tools in the runner tool cache with semver version matching
- Download files from URLs with automatic retries
- Extract
.tar, .tar.gz, and .zip archives
- Check versions against semver constraints
Installation
Installation instructions are not yet available.
Commands
ghactl is organised into top-level commands, each covering a distinct area of GitHub Actions functionality.
[!NOTE]
More commands will be added over time.
| Command |
Description |
tool |
Manage GitHub runner tools |
Global Flags
| Flag |
Description |
--verbose |
Enable verbose output |
--version |
Print the version |
--help |
Show help |
Manage GitHub runner tools: download, extract, cache, and check versions.
| Subcommand |
Description |
cache get |
Get the tool cache directory path |
cache find-all |
Find all cached paths for a tool |
cache find |
Find a specific cached tool version |
cache add dir |
Add a directory to the tool cache |
cache add file |
Add a file to the tool cache |
download |
Download a tool to a temporary directory |
extract tar |
Extract a tar archive to a temporary directory |
extract tgz |
Extract a tar.gz archive to a temporary directory |
extract zip |
Extract a zip archive to a temporary directory |
version check |
Check if a version matches a constraint |
Get the tool cache directory path.
ghactl tool cache get
Find all cached paths for a tool.
| Flag |
Required |
Default |
Description |
--name |
Yes |
|
Name of the tool |
--arch |
No |
Runtime GOARCH |
Architecture of the tool |
ghactl tool cache find-all --name my-tool
ghactl tool cache find-all --name my-tool --arch amd64
Find the path to a specific cached tool version.
| Flag |
Required |
Default |
Description |
--name |
Yes |
|
Name of the tool |
--arch |
No |
Runtime GOARCH |
Architecture of the tool |
--version |
No |
* (any) |
Version spec to match |
ghactl tool cache find --name my-tool --version "^1.0.0"
ghactl tool cache find --name my-tool --version "1.2.3" --arch arm64
Add a directory to the tool cache.
| Flag |
Required |
Default |
Description |
--source |
Yes |
|
Source directory path |
--name |
Yes |
|
Name of the tool |
--version |
Yes |
|
Version of the tool |
--arch |
No |
Runtime GOARCH |
Architecture of the tool |
ghactl tool cache add dir --source /tmp/extracted --name my-tool --version 1.2.3
Add a single file to the tool cache.
| Flag |
Required |
Default |
Description |
--source |
Yes |
|
Source file path |
--name |
Yes |
|
Name of the tool |
--version |
Yes |
|
Version of the tool |
--arch |
No |
Runtime GOARCH |
Architecture of the tool |
--target-name |
No |
Tool name |
Name to rename the source file to |
ghactl tool cache add file --source /tmp/my-binary --name my-tool --version 1.0.0
ghactl tool cache add file --source /tmp/binary --name my-tool --version 1.0.0 --target-name custom-name
Download a tool from a URL to a temporary directory. Outputs the path to the downloaded file.
| Flag |
Required |
Description |
--url |
Yes |
URL to download the tool from |
ghactl tool download --url https://example.com/tool-v1.0.0-linux-amd64.tar.gz
Extract a tar archive to a temporary directory.
| Flag |
Required |
Description |
--path |
Yes |
Path to the tar archive |
ghactl tool extract tar --path /tmp/tool.tar
Extract a tar.gz archive to a temporary directory.
| Flag |
Required |
Description |
--path |
Yes |
Path to the tar.gz archive |
ghactl tool extract tgz --path /tmp/tool.tar.gz
Extract a zip archive to a temporary directory.
| Flag |
Required |
Description |
--path |
Yes |
Path to the zip archive |
ghactl tool extract zip --path /tmp/tool.zip
Check if a version satisfies a semver constraint. Outputs true or false.
| Flag |
Required |
Description |
--version |
Yes |
Version to check |
--version-spec |
Yes |
Version constraint to check against |
ghactl tool version check --version 1.2.3 --version-spec "^1.0.0"
Contributing
See CONTRIBUTING.md for development setup and guidelines.
Security
See SECURITY.md for reporting vulnerabilities.
License
MIT