id          = "kargo"
name        = "Kargo"
homepage    = "https://kargo.akuity.io"
description = "Kargo is a Kubernetes-native continuous promotion platform for GitOps workflows."
executables      = ["kargo"]

[dotfiles]

# https://github.com/akuity/kargo/blob/main/pkg/cli/config/config.go — the
# CLI explicitly sets XDG_CONFIG_HOME to $HOME/.config when unset, then calls
# xdg.ConfigFile("kargo/config"); this file intentionally has no extension.
paths  = ["[configHome]/kargo/config"]
secret = []

# config.go documents both tokens as authentication credentials sent in the
# Authorization header or used to refresh a token.
[[dotfiles.secret_paths]]
file   = "[configHome]/kargo/config"
format = "yaml"
match  = { key_path = ["bearerToken", "refreshToken"] }

[commands]
format = 1
label = "Kargo"
description = "Promote freight to a stage. Exactly one freight selector and one target are expected; the form does not enforce that. Other commands, login and --wait are left out."
quality = "ai-draft"
parser = { end_of_options = "--", interleave = "permute", long_equals = true, short_attached = true, short_bundles = true }

[[commands.subcommand]]
path = ["promote"]
label = "Promote freight"
description = "Promote freight (by name, alias or from a warehouse) to a stage or to the stages downstream of it, or abort a promotion."

[[commands.subcommand.source]]
id = "src"
kind = "help"
url = "https://github.com/akuity/kargo/blob/main/pkg/cli/cmd/promote/promote.go"
revision = "main 2026-10-27"
evidence = """
"promote [--project=project] " +
"(--freight=freight | --freight-alias=alias | --warehouse=warehouse | --name=name) " +
"[(--stage=stage | --downstream-from=stage) | --abort]",
# Promote a piece of freight specified by name to the QA stage
kargo promote --project=my-project --freight=abc123 --stage=qa
kargo promote --project=my-project --freight-alias=wonky-wombat --stage=qa
kargo promote --project=my-project --freight=abc123 --downstream-from=qa
kargo promote --project=my-project --warehouse=my-warehouse --stage=qa
# Abort a Promotion by name
kargo promote --project=my-project --name=my-promotion --abort
"""

[[commands.subcommand.field]]
id = "project"
label = "Project"
description = "Defaults to the project set with kargo config set-project."
type = "string"
option = ["--project"]
sources = ["src"]

[[commands.subcommand.field]]
id = "freight"
label = "Freight name"
type = "string"
option = ["--freight"]
sources = ["src"]

[[commands.subcommand.field]]
id = "freight_alias"
label = "Freight alias"
type = "string"
option = ["--freight-alias"]
sources = ["src"]

[[commands.subcommand.field]]
id = "warehouse"
label = "Warehouse"
type = "string"
option = ["--warehouse"]
sources = ["src"]

[[commands.subcommand.field]]
id = "stage"
label = "Target stage"
type = "string"
option = ["--stage"]
sources = ["src"]

[[commands.subcommand.field]]
id = "downstream_from"
label = "Promote to stages downstream of"
type = "string"
option = ["--downstream-from"]
sources = ["src"]

[[commands.subcommand.field]]
id = "name"
label = "Promotion name (abort only)"
type = "string"
option = ["--name"]
sources = ["src"]

[[commands.subcommand.field]]
id = "abort"
label = "Abort the promotion"
type = "boolean"
option = ["--abort"]
effect = "exec"
sources = ["src"]

[[commands.subcommand.task]]
id = "promote-freight"
label = "Promote freight to a stage"
fields = ["project", "freight", "freight_alias", "stage"]
required = ["stage"]

[[commands.subcommand.task]]
id = "promote-downstream"
label = "Promote to downstream stages"
fields = ["project", "freight", "freight_alias", "downstream_from"]
required = ["downstream_from"]

[[commands.subcommand.task]]
id = "abort"
label = "Abort a promotion"
set = { abort = [true] }
lock = ["abort"]
fields = ["project", "name", "abort"]
required = ["name"]

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["project", "freight", "freight_alias", "warehouse", "stage", "downstream_from"]

[[commands.subcommand.group]]
id = "advanced"
label = "Advanced"
fields = ["name", "abort"]