Python Library - Command-Line Interface

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

Features Commands

gl-features-parse

Parse and extract information from Garden Linux features.

gl-features-parse

Parse and extract information from Garden Linux features.

usage: gl-features-parse [-h] [--arch ARCH]
                         [--artifact-base-name ARTIFACT_BASE_NAME]
                         [--cname CNAME] [--commit COMMIT]
                         [--feature-dir FEATURE_DIR] [--flavor FLAVOR]
                         [--ignore IGNORE] [--release-file RELEASE_FILE]
                         [--version VERSION]
                         [--versioned-flavor VERSIONED_FLAVOR]
                         [{arch,artifact-base-name,cname,commit-id,container-name,container-tag,elements,features,flags,flavor,graph,platform,platform-variant,platforms,version,version_and_commit-id,versioned-flavor}]

type: Type of output to generate. Choices: arch, artifact-base-name, cname, commit-id, container-name, container-tag, elements, features, flags, flavor, graph, platform, platform-variant, platforms, version, version_and_commit-id, versioned-flavor. Default: ‘cname’.

-h, --help: show this help message and exit

--arch <arch>: Target architecture (e.g., amd64, arm64). Overrides architecture from CName.

--artifact-base-name <artifact_base_name>: Artifact base name to parse. Must be a valid Garden Linux Artifact Base Name.

--cname <cname>: Canonical Name (CName) to parse.

--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.

--flavor <flavor>: Garden Linux flavor name.

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

--release-file <release_file>: Path to a release file containing features metadata. Either –feature-dir or –release-file must be provided.

--version <version>: Version string. If not specified, will be read from VERSION file or release file.

--versioned-flavor <versioned_flavor>: Garden Linux versioned flavor name.

gl-features-metadata

Provides Garden Linux release metadata file handling.

gl-metadata

Handle GardenLinux metadata reading and writing.

usage: gl-metadata [-h] [--arch ARCH]
                   [--artifact-base-name ARTIFACT_BASE_NAME] [--cname CNAME]
                   [--commit COMMIT] [--flavor FLAVOR]
                   [--release-file RELEASE_FILE]
                   [--overwrite-file OVERWRITE_FILE] [--version VERSION]
                   [--versioned-flavor VERSIONED_FLAVOR]
                   [{output-release-metadata,write}]

action

-h, --help: show this help message and exit

--arch <arch>: Target architecture (e.g., amd64, arm64). Overrides architecture from CName.

--artifact-base-name <artifact_base_name>: Artifact base name to parse. Must be a valid Garden Linux Artifact Base Name.

--cname <cname>: Canonical Name (CName) to parse.

--commit <commit>: Git commit hash. If not specified, will be read from COMMIT file or release file.

--flavor <flavor>: GardenLinux flavor name.

--release-file <release_file>: Path to a release file containing features metadata.

--overwrite-file <overwrite_file>: Accept overwriting existing files.

--version <version>: Version string. If not specified, will be read from VERSION file or release file.

--versioned-flavor <versioned_flavor>: GardenLinux versioned flavor name.

Flavors Commands

gl-flavors-parse

Parse flavors.yaml and generate combinations.

sphinx-build

Parse flavors.yaml and generate combinations.

usage: sphinx-build [-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 images.

usage: gl-oci [-h]
              {add-image-to-index,build-image,load-image,load-images-from-directory,new-index,pull-image,push-image,push-index-from-directory,push-index-tags,push-manifest,push-manifest-tags,save-image,tag-image} ...

-h, --help: show this help message and exit

gl-oci add-image-to-index

usage: gl-oci add-image-to-index [-h] --index INDEX --index-tag INDEX_TAG
                                 --repository REPOSITORY --tag TAG
                                 [--insecure | --no-insecure]
                                 [--additional-tag ADDITIONAL_TAG]

-h, --help: show this help message and exit

--index <index>: OCI image index

--index-tag <index_tag>: OCI image index tag

--repository <repository>: Repository path

--tag <tag>: OCI tag of image

--insecure, --no-insecure: Use HTTP to communicate with the registry

--additional-tag <additional_tag>: Additional tag to push

gl-oci build-image

usage: gl-oci build-image [-h] --repository REPOSITORY --tag TAG
                          --dir DIRECTORY [--platform PLATFORM]
                          [--additional-tag ADDITIONAL_TAG]
                          [--build-arg BUILD_ARG] [--oci-archive OCI_ARCHIVE]

-h, --help: show this help message and exit

--repository <repository>: Repository path

--tag <tag>: OCI tag of image

--dir <directory>: Path to the build Containerfile

--platform <platform>: OCI platform as os/arch/variant

--additional-tag <additional_tag>: Additional tag to push

--build-arg <build_arg>: Additional build args for Containerfile

--oci-archive <oci_archive>: OCI archive path and file name

gl-oci load-image

usage: gl-oci load-image [-h] [--oci-archive OCI_ARCHIVE]
                         [--additional-tag ADDITIONAL_TAG]

-h, --help: show this help message and exit

--oci-archive <oci_archive>: OCI archive path and file name

--additional-tag <additional_tag>: Additional tag to push

gl-oci load-images-from-directory

usage: gl-oci load-images-from-directory [-h] --dir DIRECTORY

-h, --help: show this help message and exit

--dir <directory>: Directory of the build artifacts

gl-oci new-index

usage: gl-oci new-index [-h] --index INDEX --index-tag INDEX_TAG
                        [--insecure | --no-insecure]
                        [--additional-tag ADDITIONAL_TAG]

-h, --help: show this help message and exit

--index <index>: OCI image index

--index-tag <index_tag>: OCI image index tag

--insecure, --no-insecure: Use HTTP to communicate with the registry

--additional-tag <additional_tag>: Additional tag to push

gl-oci pull-image

usage: gl-oci pull-image [-h] --repository REPOSITORY [--tag TAG]
                         [--platform PLATFORM] [--insecure | --no-insecure]

-h, --help: show this help message and exit

--repository <repository>: Repository path

--tag <tag>: OCI tag of image

--platform <platform>: OCI platform as os/arch/variant

--insecure, --no-insecure: Use HTTP to communicate with the registry

gl-oci push-image

usage: gl-oci push-image [-h] --repository REPOSITORY [--tag TAG]
                         [--destination DESTINATION]
                         [--insecure | --no-insecure]

-h, --help: show this help message and exit

--repository <repository>: Repository path

--tag <tag>: OCI tag of image

--destination <destination>: OCI repository destination

--insecure, --no-insecure: Use HTTP to communicate with the registry

gl-oci push-index-from-directory

usage: gl-oci push-index-from-directory [-h] --index INDEX
                                        --index-tag INDEX_TAG
                                        [--dir DIRECTORY]
                                        [--insecure | --no-insecure]
                                        [--additional-tag ADDITIONAL_TAG]

-h, --help: show this help message and exit

--index <index>: OCI image index

--index-tag <index_tag>: OCI image index tag

--dir <directory>: Directory to read index entry files from.

--insecure, --no-insecure: Use HTTP to communicate with the registry

--additional-tag <additional_tag>: Additional tag to push

gl-oci push-index-tags

usage: gl-oci push-index-tags [-h] --index INDEX --index-tag INDEX_TAG
                              [--insecure | --no-insecure] --tag TAG

-h, --help: show this help message and exit

--index <index>: OCI image index

--index-tag <index_tag>: OCI image index tag

--insecure, --no-insecure: Use HTTP to communicate with the registry

--tag <tag>: OCI tag of image

gl-oci push-manifest

usage: gl-oci push-manifest [-h] --repository REPOSITORY --cname CNAME
                            [--arch ARCH] [--version VERSION]
                            [--commit COMMIT] --dir DIRECTORY
                            [--manifest-file MANIFEST_FILE]
                            [--cosign-file COSIGN_FILE]
                            [--insecure | --no-insecure]
                            [--additional-tag ADDITIONAL_TAG]

-h, --help: show this help message and exit

--repository <repository>: Repository path

--cname <cname>: Garden Linux Canonical Name

--arch <arch>: Target image CPU architecture

--version <version>: Version of image

--commit <commit>: Commit ID or hash

--dir <directory>: Directory of the build artifacts

--manifest-file <manifest_file>: A file where the metadata for the pushed manifest is written to.

--cosign-file <cosign_file>: A file where pushed manifests digests is written to.

--insecure, --no-insecure: Use HTTP to communicate with the registry

--additional-tag <additional_tag>: Additional tag to push

gl-oci push-manifest-tags

usage: gl-oci push-manifest-tags [-h] --repository REPOSITORY --cname CNAME
                                 [--arch ARCH] [--version VERSION]
                                 [--commit COMMIT]
                                 [--insecure | --no-insecure] --tag TAG

-h, --help: show this help message and exit

--repository <repository>: Repository path

--cname <cname>: Garden Linux Canonical Name

--arch <arch>: Target image CPU architecture

--version <version>: Version of image

--commit <commit>: Commit ID or hash

--insecure, --no-insecure: Use HTTP to communicate with the registry

--tag <tag>: OCI tag of image

gl-oci save-image

usage: gl-oci save-image [-h] --repository REPOSITORY [--tag TAG]
                         [--oci-archive OCI_ARCHIVE]

-h, --help: show this help message and exit

--repository <repository>: Repository path

--tag <tag>: OCI tag of image

--oci-archive <oci_archive>: OCI archive path and file name

gl-oci tag-image

usage: gl-oci tag-image [-h] --repository REPOSITORY [--tag TAG]
                        [--additional-tag ADDITIONAL_TAG]

-h, --help: show this help message and exit

--repository <repository>: Repository path

--tag <tag>: OCI tag of image

--additional-tag <additional_tag>: Additional tag to push

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]
                                            [--artifact-base-name ARTIFACT_BASE_NAME]
                                            [--ignore-missing]

-h, --help: show this help message and exit

--artifact-base-name <artifact_base_name>: Artifact base name used as the S3 key prefix for artifacts.

--ignore-missing: Create a log entry only if the given S3 key prefix has not been found.

gl-s3 upload-artifacts-to-bucket

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

-h, --help: show this help message and exit

--artifact-base-name <artifact_base_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 FILE
                            [--dry-run | --no-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 <file>: Path to the file to upload (required).

--dry-run, --no-dry-run: Perform a dry run without actually uploading the file.

--overwrite-same-name