id = "balena-cli"
name = "balena CLI"
homepage = "https://github.com/balena-io/balena-cli"
description = "The official balena CLI tool."
executables = ["balena"]

[dotfiles]

# The balena CLI troubleshooting guide documents the per-user .balenarc.yml
# (and _balenarc.yml on Windows) plus the token under ~/.balena (or _balena).
# https://github.com/balena-io/balena-cli/blob/master/TROUBLESHOOTING.md
paths = [
  "~/.balenarc.yml",
  "%USERPROFILE%/_balenarc.yml",
]
secret = [
  "~/.balena/token",
  "%USERPROFILE%/_balena/token",
]

[commands]
format = 1
label = "balena CLI"
description = "Push a project to balenaCloud or a local mode device. Other balena commands and login are left out."
quality = "ai-draft"
parser = { end_of_options = "--", interleave = "permute", long_equals = true, short_attached = false, short_bundles = false }

[[commands.source]]
id = "docs"
kind = "manual"
url = "https://raw.githubusercontent.com/balena-io/balena-cli/HEAD/docs/balena-cli.md"
revision = "HEAD 2026-10-27"
evidence = """#### FLEETORDEVICE
fleet name or slug, or local device IP address or ".local" hostname
#### -s, --source SOURCE
Source directory to be sent to balenaCloud or balenaOS device
(default: current working dir)
#### -e, --emulated
Don't use the faster, native balenaCloud ARM builders; force slower QEMU ARM emulation on Intel x86-64 builders.
#### --dockerfile DOCKERFILE
Alternative Dockerfile name/path, relative to the source folder
#### -c, --nocache
Don't use cached layers of previously built images for this project.
#### --pull
When pushing to a local device, force the base images to be pulled again.
#### -R, --registry-secrets REGISTRY-SECRETS
Path to a local YAML or JSON file containing Docker registry passwords used to pull base images.
#### --nolive
Don't run a live session on this push.
#### -d, --detached
When pushing to the cloud, this option will cause the build to start, then return execution back to the shell, with the status and release ID (if applicable).
#### --service SERVICE
Reject logs not originating from this service."""

[[commands.subcommand]]
path = ["push"]
label = "Push a project"
description = "Build release images on balenaCloud or on a local mode device from a source directory."

[[commands.subcommand.source]]
id = "docs"
kind = "manual"
url = "https://raw.githubusercontent.com/balena-io/balena-cli/HEAD/docs/balena-cli.md"
revision = "HEAD 2026-10-27"
evidence = """#### FLEETORDEVICE
fleet name or slug, or local device IP address or ".local" hostname
#### -s, --source SOURCE
Source directory to be sent to balenaCloud or balenaOS device
(default: current working dir)
#### -e, --emulated
Don't use the faster, native balenaCloud ARM builders; force slower QEMU ARM emulation on Intel x86-64 builders.
#### --dockerfile DOCKERFILE
Alternative Dockerfile name/path, relative to the source folder
#### -c, --nocache
Don't use cached layers of previously built images for this project.
#### --pull
When pushing to a local device, force the base images to be pulled again.
#### -R, --registry-secrets REGISTRY-SECRETS
Path to a local YAML or JSON file containing Docker registry passwords used to pull base images.
#### --nolive
Don't run a live session on this push.
#### -d, --detached
When pushing to the cloud, this option will cause the build to start, then return execution back to the shell, with the status and release ID (if applicable).
#### --service SERVICE
Reject logs not originating from this service."""

[[commands.subcommand.field]]
id = "target"
label = "Fleet or device"
description = "Fleet name or slug, or local device IP address or .local hostname."
type = "string"
position = 0
sources = ["docs"]

[[commands.subcommand.field]]
id = "source"
label = "Source directory"
description = "Defaults to the current directory."
type = "path"
option = ["--source", "-s"]
path = { kind = "directory", role = "input", must_exist = true }
sources = ["docs"]

[[commands.subcommand.field]]
id = "dockerfile"
label = "Dockerfile"
description = "Alternative Dockerfile name or path, relative to the source folder."
type = "string"
option = ["--dockerfile"]
sources = ["docs"]

[[commands.subcommand.field]]
id = "nocache"
label = "No cache"
type = "boolean"
option = ["--nocache", "-c"]
sources = ["docs"]

[[commands.subcommand.field]]
id = "emulated"
label = "Force QEMU emulation"
type = "boolean"
option = ["--emulated", "-e"]
sources = ["docs"]

[[commands.subcommand.field]]
id = "pull"
label = "Pull base images again"
description = "Local device only."
type = "boolean"
option = ["--pull"]
sources = ["docs"]

[[commands.subcommand.field]]
id = "detached"
label = "Detached"
type = "boolean"
option = ["--detached", "-d"]
sources = ["docs"]

[[commands.subcommand.field]]
id = "nolive"
label = "No live session"
type = "boolean"
option = ["--nolive"]
sources = ["docs"]

[[commands.subcommand.field]]
id = "registry_secrets"
label = "Registry secrets file"
type = "path"
option = ["--registry-secrets", "-R"]
path = { kind = "file", role = "input", must_exist = true }
sources = ["docs"]

[[commands.subcommand.field]]
id = "service"
label = "Only logs from service"
description = "Local mode device only."
type = "string"
option = ["--service"]
multiple = true
sources = ["docs"]

[[commands.subcommand.task]]
id = "push"
label = "Push current project"
fields = ["target", "source"]
required = ["target"]

[[commands.subcommand.task]]
id = "push_detached"
label = "Push and return immediately"
fields = ["target", "source", "detached"]
required = ["target"]
set = { detached = [true] }

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["target", "source", "detached"]

[[commands.subcommand.group]]
id = "advanced"
label = "Advanced"
fields = ["dockerfile", "nocache", "emulated", "pull", "nolive", "registry_secrets", "service"]