Python Library - Command-Line Interface

Available command-line tools provided by the Garden Linux Python Library

Features Commands

gl-cname

Generate a canonical name (cname) from feature sets.

gl-cname

Generate a canonical name (cname) from feature sets.

usage: gl-cname [-h] [--arch ARCH] [--commit COMMIT]
                [--feature-dir FEATURE_DIR] [--version VERSION]
                cname

cname

Canonical name (cname) to process. Must be a valid GardenLinux canonical name format.

-h, --help

show this help message and exit

--arch <arch>

Target architecture (e.g., amd64, arm64). If not specified, will be determined from the cname or feature set.

--commit <commit>

Git commit hash. If not specified, will be read from COMMIT file in the GardenLinux root directory.

--feature-dir <feature_dir>

Path to the features directory (default: ‘features’).

--version <version>

Version string. If not specified, will be read from VERSION file in the GardenLinux root directory.

gl-features-parse

Parse and extract information from GardenLinux features.

gl-features-parse

Parse and extract information from GardenLinux features.

usage: gl-features-parse [-h] [--arch ARCH] --cname CNAME [--commit COMMIT]
                         [--feature-dir FEATURE_DIR]
                         [--release-file RELEASE_FILE]
                         [--default-arch DEFAULT_ARCH]
                         [--default-version DEFAULT_VERSION]
                         [--version VERSION] [--ignore IGNORE]
                         [{cname,cname_base,container_name,container_tag,commit_id,features,platform,platforms,flags,flavor,elements,arch,version,version_and_commit_id,graph}]

type

Type of output to generate. Choices: cname, cname_base, container_name, container_tag, commit_id, features, platform, platforms, flags, flavor, elements, arch, version, version_and_commit_id, graph. Default: ‘cname’.

-h, --help

show this help message and exit

--arch <arch>

Target architecture (e.g., amd64, arm64). Overrides architecture from cname.

--cname <cname>

Canonical name (cname) to parse. Must be a valid GardenLinux canonical name.

--commit <commit>

Git commit hash. If not specified, will be read from COMMIT file or release file.

--feature-dir <feature_dir>

Path to the features directory (default: ‘features’). Either –feature-dir or –release-file must be provided.

--release-file <release_file>

Path to a release file containing cname metadata. Either –feature-dir or –release-file must be provided.

--default-arch <default_arch>

Default architecture to use if architecture cannot be determined from cname or other sources.

--default-version <default_version>

Default version to use if version cannot be determined from files or other sources.

--version <version>

Version string. If not specified, will be read from VERSION file or release file.

--ignore <ignore>

Comma-separated list of features to ignore when processing (e.g., ‘feature1,feature2’).

Flavors Commands

gl-flavors-parse

Parse flavors.yaml and generate combinations.

python3 -m sphinx

Parse flavors.yaml and generate combinations.

usage: python3 -m sphinx [-h] [--commit COMMIT] [--no-arch]
                         [--include-only INCLUDE_ONLY] [--exclude EXCLUDE]
                         [--build] [--publish] [--test] [--test-platform]
                         [--category CATEGORY]
                         [--exclude-category EXCLUDE_CATEGORY]
                         [--json-by-arch] [--markdown-table-by-platform]

-h, --help

show this help message and exit

--commit <commit>

Commit hash to fetch flavors.yaml from GitHub. An existing ‘flavors.yaml’ file will be preferred.

--no-arch

Exclude architecture from the flavor output.

--include-only <include_only>

Restrict combinations to those matching wildcard patterns (can be specified multiple times).

--exclude <exclude>

Exclude combinations based on wildcard patterns (can be specified multiple times).

--build

Filter combinations to include only those with build enabled.

--publish

Filter combinations to include only those with publish enabled.

--test

Filter combinations to include only those with test enabled.

--test-platform

Filter combinations to include only platforms with test-platform: true.

--category <category>

Filter combinations to include only platforms belonging to the specified categories (can be specified multiple times).

--exclude-category <exclude_category>

Exclude platforms belonging to the specified categories (can be specified multiple times).

--json-by-arch

Output a JSON dictionary where keys are architectures and values are lists of flavors.

--markdown-table-by-platform

Generate a markdown table by platform.

OCI Commands

gl-oci

Push OCI artifacts to a registry and manage manifests.

gl-oci

gl-oci provides functionality to handle OCI containers. It can pull and push images from remote repositories as well as handle GardenLinux artifacts, OCI image indices and manifests.

• since: 0.7.0

Usage

gl-oci [OPTIONS] COMMAND [ARGS]...

add-container-to-index

Adds an image container to an OCI image index.

• since: 1.0.0

Usage

gl-oci add-container-to-index [OPTIONS]

Options

--index <index>

Required OCI image index

--index-tag <index_tag>

Required OCI image index tag

--container <container>

Required Container Name

--tag <tag>

Required OCI tag of image

--insecure <insecure>

Use HTTP to communicate with the registry

--additional_tag <additional_tag>

Additional tag to push the index with

build-container

Build an OCI container based on the defined Containerfile.

• since: 1.0.0

Usage

gl-oci build-container [OPTIONS]

Options

--container <container>

Required Container Name

--tag <tag>

Required OCI tag of image

--dir <directory>

Required Path to the build Containerfile

--platform <platform>

OCI platform as os/arch/variant

--additional_tag <additional_tag>

Additional tag to push the manifest with

--build_arg <build_arg>

Additional build args for Containerfile

--oci_archive <oci_archive>

Write build result to the OCI archive path and file name

load-container

Load an OCI archive.

• since: 1.0.0

Usage

gl-oci load-container [OPTIONS]

Options

--oci_archive <oci_archive>

Write build result to the OCI archive path and file name

--additional_tag <additional_tag>

Additional tag to push the manifest with

load-containers-from-directory

Load multiple OCI archives.

• since: 1.0.0

Usage

gl-oci load-containers-from-directory [OPTIONS]

Options

--dir <directory>

Required path to the build artifacts

new-index

Create a new OCI image index.

• since: 1.0.0

Usage

gl-oci new-index [OPTIONS]

Options

--index <index>

Required OCI image index

--index-tag <index_tag>

Required OCI image index tag

--insecure <insecure>

Use HTTP to communicate with the registry

--additional_tag <additional_tag>

Additional tag to push the index with

pull-container

Pull an OCI image container from a remote OCI registry.

• since: 1.0.0

Usage

gl-oci pull-container [OPTIONS]

Options

--container <container>

Required Container Name

--tag <tag>

OCI tag of image

--platform <platform>

OCI platform as os/arch/variant

--insecure <insecure>

Use HTTP to communicate with the registry

push-container

Push an OCI image container to a remote OCI registry.

• since: 1.0.0

Usage

gl-oci push-container [OPTIONS]

Options

--container <container>

Required Container Name

--tag <tag>

OCI tag of image

--destination <destination>

OCI container destination

--insecure <insecure>

Use HTTP to communicate with the registry

push-index-from-directory

Pushes manifests stored in a directory to a given OCI image index.

• since: 0.10.9

Usage

gl-oci push-index-from-directory [OPTIONS]

Options

--index <index>

Required OCI image index

--index-tag <index_tag>

Required OCI image index tag

--manifest_folder <manifest_folder>

A folder where the index entries are read from.

--insecure <insecure>

Use HTTP to communicate with the registry

--additional_tag <additional_tag>

Additional tag to push the index with

push-index-tags

Push OCI image index tags to a registry.

• since: 0.10.9

Usage

gl-oci push-index-tags [OPTIONS]

Options

--index <index>

Required OCI image index

--index-tag <index_tag>

Required OCI image index tag

--insecure <insecure>

Use HTTP to communicate with the registry

--tag <tag>

Required Tag to push the OCI image index with

push-manifest

Push to an OCI image container given GardenLinux canonical named artifacts in a specified directory.

• since: 0.7.0

Usage

gl-oci push-manifest [OPTIONS]

Options

--container <container>

Required Container Name

--cname <cname>

Required Canonical Name of Image

--arch <arch>

Target Image CPU Architecture

--version <version>

Version of image

--commit <commit>

Commit of image

--dir <directory>

Required path to the build artifacts

--cosign_file <cosign_file>

A file where the pushed manifests digests is written to. The content can be used by an external tool (e.g. cosign) to sign the manifests contents

--manifest_file <manifest_file>

A file where the index entry for the pushed manifest is written to.

--insecure <insecure>

Use HTTP to communicate with the registry

--additional_tag <additional_tag>

Additional tag to push the manifest with

push-manifest-tags

Push tags to an OCI image container for a given GardenLinux canonical named image.

• since: 0.10.0

Usage

gl-oci push-manifest-tags [OPTIONS]

Options

--container <container>

Required Container Name

--cname <cname>

Canonical Name of Image

--arch <arch>

Target Image CPU Architecture

--version <version>

Version of image

--commit <commit>

Commit of image

--insecure <insecure>

Use HTTP to communicate with the registry

--tag <tag>

Required Tag to push the manifest with

save-container

Saves a given OCI image container as an OCI archive.

• since: 1.0.0

Usage

gl-oci save-container [OPTIONS]

Options

--container <container>

Required Container Name

--tag <tag>

OCI tag of image

--oci_archive <oci_archive>

Write build result to the OCI archive path and file name

tag-container

Adds additional tags to a given OCI image container.

• since: 1.0.0

Usage

gl-oci tag-container [OPTIONS]

Options

--container <container>

Required Container Name

--tag <tag>

OCI tag of image

--additional_tag <additional_tag>

Additional tag to push the manifest with

S3 Commands

gl-s3

Upload and download artifacts from S3 buckets.

gl-s3

usage: gl-s3 [-h] [--bucket BUCKET] [--path PATH] [--dry-run]
             {download-artifacts-from-bucket,upload-artifacts-to-bucket} ...

-h, --help

show this help message and exit

--bucket <bucket>

S3 bucket name to upload to or download from.

--path <path>

Local directory path for upload (source) or download (destination).

--dry-run

Perform a dry run without actually uploading or downloading files.

gl-s3 download-artifacts-from-bucket

usage: gl-s3 download-artifacts-from-bucket [-h] [--cname CNAME]

-h, --help

show this help message and exit

--cname <cname>

Canonical name (cname) used as the S3 key prefix for artifacts.

gl-s3 upload-artifacts-to-bucket

usage: gl-s3 upload-artifacts-to-bucket [-h] [--artifact-name ARTIFACT_NAME]

-h, --help

show this help message and exit

--artifact-name <artifact_name>

S3 artifact base name.

GitHub Commands

gl-gh-release

Create and manage GitHub releases.

gl-gh-release

Create and manage GitHub releases.

usage: gl-gh-release [-h] {create,create-with-gl-release-notes,upload} ...

-h, --help

show this help message and exit

gl-gh-release create

usage: gl-gh-release create [-h] [--owner OWNER] [--repo REPO] --tag TAG
                            [--name NAME] --body BODY [--commit COMMIT]
                            [--pre-release] [--latest]

-h, --help

show this help message and exit

--owner <owner>

GitHub repository owner (default: ‘gardenlinux’).

--repo <repo>

GitHub repository name (default: ‘gardenlinux’).

--tag <tag>

Git tag name for the release (required).

--name <name>

Release name/title. If not specified, the tag will be used.

--body <body>

Release notes/description body (required).

--commit <commit>

Git commit hash. If not specified, the tag will be used to find the commit.

--pre-release

Mark the release as a pre-release (default: True).

--latest

Mark this release as the latest release (default: False).

gl-gh-release create-with-gl-release-notes

usage: gl-gh-release create-with-gl-release-notes [-h] [--owner OWNER]
                                                  [--repo REPO] --tag TAG
                                                  --commit COMMIT [--latest]
                                                  [--dry-run]

-h, --help

show this help message and exit

--owner <owner>

GitHub repository owner (default: ‘gardenlinux’).

--repo <repo>

GitHub repository name (default: ‘gardenlinux’).

--tag <tag>

Git tag name for the release (required).

--commit <commit>

Git commit hash used to generate release notes (required).

--latest

Mark this release as the latest release (default: False).

--dry-run

Perform a dry run without actually creating the release.

gl-gh-release upload

usage: gl-gh-release upload [-h] [--owner OWNER] [--repo REPO]
                            --release_id RELEASE_ID --file_path FILE_PATH
                            [--dry-run] [--overwrite-same-name]

-h, --help

show this help message and exit

--owner <owner>

GitHub repository owner (default: ‘gardenlinux’).

--repo <repo>

GitHub repository name (default: ‘gardenlinux’).

--release_id <release_id>

GitHub release ID to upload the file to (required).

--file_path <file_path>

Path to the file to upload (required).

--dry-run

Perform a dry run without actually uploading the file.

--overwrite-same-name