ghactl

command module
v0.0.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 5, 2026 License: MIT Imports: 5 Imported by: 0

README

GitHub Actions CLI (ghactl)

GitHub Release (latest SemVer) Validate

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

tool

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

tool cache get

Get the tool cache directory path.

ghactl tool cache get

tool cache find-all

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

tool cache find

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

tool cache add dir

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

tool cache add file

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

tool download

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

tool extract tar

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

tool extract tgz

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

tool extract zip

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

tool version check

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

Documentation

The Go Gopher

There is no documentation for this package.

Directories

Path Synopsis
internal

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL