Luma CLI 命令参考#

以下内容来自当前 CLI 解析器。使用 python scripts/generate-cli-reference.py 重新生成英文参考，CI 通过 --check 验证。认证、部署和恢复操作见 CLI 中文指南。全局选项放在命令前，命令选项放在对应命令后。代码块保留实际 CLI 帮助输出，便于与终端逐项核对。

luma#

usage: luma [-h] [--config CONFIG] [--env-file ENV_FILE] [--no-env] {init,version,status,preflight,configure,login,context,secret,registry,git-provider,bootstrap,update,doctor,manager,node,cloudflare,egress,tailscale,service,validate,render,dns-sync,deploy,import,build,workflow,rollback,history,compose,storage,region} ...

Self-hosted deployment control plane.

arguments:
  {init,version,status,preflight,configure,login,context,secret,registry,git-provider,bootstrap,update,doctor,manager,node,cloudflare,egress,tailscale,service,validate,render,dns-sync,deploy,import,build,workflow,rollback,history,compose,storage,region}
    doctor              Check authentication and remote Control/node readiness
    manager             Manager recovery and maintenance operations
    region              Create and list scheduling regions
    import              Build and deploy a Git repository; auto-discovers .luma.yml or
                        luma.compose.yml
    build               Inspect and retry repository import build runs
    workflow            Inspect and record server-side build/deploy workflows; deployment commands
                        check them automatically
    rollback            Roll a Nomad-engine service back to a previous version
    history             Show a Nomad-engine service's deploy version history

arguments:
  -h, --help            show this help message and exit
  --config CONFIG       Path to luma.yaml
  --env-file ENV_FILE   Path to local env file
  --no-env              Do not load .env

luma init#

usage: luma init [-h]

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

luma version#

usage: luma version [-h] [--control-url CONTROL_URL] [--insecure] [--resolve-ip RESOLVE_IP] [--local]

arguments:
  -h, --help            show this help message and exit
  --control-url CONTROL_URL
                        Control API URL to check instead of the current login context
  --insecure            Skip TLS verification for the control API check
  --resolve-ip RESOLVE_IP
                        Connect to this IP while keeping the control hostname as Host
  --local               Only print the local CLI version

luma status#

usage: luma status [-h] [--control-context CONTROL_CONTEXT] [--control-url CONTROL_URL] [--token TOKEN] [--insecure] [--resolve-ip RESOLVE_IP] [--format {text,json,ndjson}] [--quiet]

arguments:
  -h, --help            show this help message and exit
  --control-context CONTROL_CONTEXT
                        Use a saved cluster context without switching the current context
  --control-url CONTROL_URL
                        Control API URL to use instead of the current login context
  --token TOKEN         Management token to use with --control-url
  --insecure            Skip TLS verification for the control API
  --resolve-ip RESOLVE_IP
                        Connect to this IP while keeping the control hostname as Host
  --format {text,json,ndjson}
                        Output format
  --quiet               Print only the final result or error

luma preflight#

usage: luma preflight [-h]

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

luma configure#

usage: luma configure [-h] [--role {manager,worker,client}] [--show]

arguments:
  -h, --help            show this help message and exit
  --role {manager,worker,client}
  --show                Show configured key names without printing secret values

luma login#

usage: luma login [-h] [--token TOKEN | --token-stdin] [--format {text,json,ndjson}] [--quiet] [--insecure] [--resolve-ip RESOLVE_IP] endpoint

arguments:
  endpoint

arguments:
  -h, --help            show this help message and exit
  --token TOKEN         Management token (prefer --token-stdin or LUMA_DEPLOY_TOKEN)
  --token-stdin         Read management token from stdin
  --format {text,json,ndjson}
                        Output format
  --quiet               Print only the final result or error
  --insecure            Skip TLS verification for self-signed control endpoints
  --resolve-ip RESOLVE_IP
                        Connect to this IP while keeping the endpoint hostname as Host

luma context#

usage: luma context [-h] {list,use} ...

arguments:
  {list,use}

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

luma context list#

usage: luma context list [-h] [--format {text,json,ndjson}] [--quiet]

arguments:
  -h, --help            show this help message and exit
  --format {text,json,ndjson}
                        Output format
  --quiet               Print only the final result or error

luma context use#

usage: luma context use [-h] [--format {text,json,ndjson}] [--quiet] cluster

arguments:
  cluster

arguments:
  -h, --help            show this help message and exit
  --format {text,json,ndjson}
                        Output format
  --quiet               Print only the final result or error

luma secret#

usage: luma secret [-h] {list,set,import} ...

arguments:
  {list,set,import}
    import           Import deployment secrets from a .env file into an application scope

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

luma secret list#

usage: luma secret list [-h] [--control-context CONTROL_CONTEXT] [--control-url CONTROL_URL] [--token TOKEN] [--insecure] [--resolve-ip RESOLVE_IP] [--format {text,json,ndjson}] [--quiet]

arguments:
  -h, --help            show this help message and exit
  --control-context CONTROL_CONTEXT
                        Use a saved cluster context without switching the current context
  --control-url CONTROL_URL
                        Control API URL to use instead of the current login context
  --token TOKEN         Management token to use with --control-url
  --insecure            Skip TLS verification for the control API
  --resolve-ip RESOLVE_IP
                        Connect to this IP while keeping the control hostname as Host
  --format {text,json,ndjson}
                        Output format
  --quiet               Print only the final result or error

luma secret set#

usage: luma secret set [-h] [--scope SCOPE] [--value VALUE] [--value-stdin] [--control-context CONTROL_CONTEXT] [--control-url CONTROL_URL] [--token TOKEN] [--insecure] [--resolve-ip RESOLVE_IP] name

arguments:
  name

arguments:
  -h, --help            show this help message and exit
  --scope SCOPE         Application/stack scope; omit only for legacy global secrets
  --value VALUE
  --value-stdin         Read the secret value from stdin
  --control-context CONTROL_CONTEXT
                        Use a saved cluster context without switching the current context
  --control-url CONTROL_URL
                        Control API URL to use instead of the current login context
  --token TOKEN         Management token to use with --control-url
  --insecure            Skip TLS verification for the control API
  --resolve-ip RESOLVE_IP
                        Connect to this IP while keeping the control hostname as Host

luma secret import#

usage: luma secret import [-h] --scope SCOPE [--control-context CONTROL_CONTEXT] [--control-url CONTROL_URL] [--token TOKEN] [--insecure] [--resolve-ip RESOLVE_IP] env_file

arguments:
  env_file

arguments:
  -h, --help            show this help message and exit
  --scope SCOPE         Application/stack scope used to isolate common names like DATABASE_URL
  --control-context CONTROL_CONTEXT
                        Use a saved cluster context without switching the current context
  --control-url CONTROL_URL
                        Control API URL to use instead of the current login context
  --token TOKEN         Management token to use with --control-url
  --insecure            Skip TLS verification for the control API
  --resolve-ip RESOLVE_IP
                        Connect to this IP while keeping the control hostname as Host

luma registry#

usage: luma registry [-h] {list,login,remove,serve,images,delete,deletion,gc,policy} ...

arguments:
  {list,login,remove,serve,images,delete,deletion,gc,policy}
    serve               Deploy a managed registry on a Linux Luma node
    images              List managed Registry manifests and protection state
    delete              Queue a protected manifest deletion
    deletion            Cancel, execute, or restore a deletion
    gc                  Preview or execute offline Registry garbage collection
    policy              Show or update Registry retention policy

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

luma registry list#

usage: luma registry list [-h] [--control-context CONTROL_CONTEXT] [--control-url CONTROL_URL] [--token TOKEN] [--insecure] [--resolve-ip RESOLVE_IP] [--format {text,json,ndjson}] [--quiet]

arguments:
  -h, --help            show this help message and exit
  --control-context CONTROL_CONTEXT
                        Use a saved cluster context without switching the current context
  --control-url CONTROL_URL
                        Control API URL to use instead of the current login context
  --token TOKEN         Management token to use with --control-url
  --insecure            Skip TLS verification for the control API
  --resolve-ip RESOLVE_IP
                        Connect to this IP while keeping the control hostname as Host
  --format {text,json,ndjson}
                        Output format
  --quiet               Print only the final result or error

luma registry login#

usage: luma registry login [-h] --username USERNAME [--password-stdin] [--control-context CONTROL_CONTEXT] [--control-url CONTROL_URL] [--token TOKEN] [--insecure] [--resolve-ip RESOLVE_IP] host

arguments:
  host

arguments:
  -h, --help            show this help message and exit
  --username USERNAME
  --password-stdin      Read the registry password/token from stdin
  --control-context CONTROL_CONTEXT
                        Use a saved cluster context without switching the current context
  --control-url CONTROL_URL
                        Control API URL to use instead of the current login context
  --token TOKEN         Management token to use with --control-url
  --insecure            Skip TLS verification for the control API
  --resolve-ip RESOLVE_IP
                        Connect to this IP while keeping the control hostname as Host

luma registry remove#

usage: luma registry remove [-h] [--control-context CONTROL_CONTEXT] [--control-url CONTROL_URL] [--token TOKEN] [--insecure] [--resolve-ip RESOLVE_IP] host

arguments:
  host

arguments:
  -h, --help            show this help message and exit
  --control-context CONTROL_CONTEXT
                        Use a saved cluster context without switching the current context
  --control-url CONTROL_URL
                        Control API URL to use instead of the current login context
  --token TOKEN         Management token to use with --control-url
  --insecure            Skip TLS verification for the control API
  --resolve-ip RESOLVE_IP
                        Connect to this IP while keeping the control hostname as Host

luma registry serve#

usage: luma registry serve [-h] --node NODE [--port PORT] [--image IMAGE] [--name NAME] [--storage-class STORAGE_CLASS] [--domain DOMAIN] [--username USERNAME] [--password-stdin] [--no-activate] [--control-context CONTROL_CONTEXT] [--control-url CONTROL_URL] [--token TOKEN] [--insecure] [--resolve-ip RESOLVE_IP] [--format {text,json,ndjson}] [--quiet] [--timeout TIMEOUT]

arguments:
  -h, --help            show this help message and exit
  --node NODE           Ready Linux node that hosts the registry
  --port PORT           Host port the registry listens on (default: 5000)
  --image IMAGE         Registry image (default: registry:2)
  --name NAME           Service name (default: luma-registry)
  --storage-class STORAGE_CLASS
                        Optional storageClass; otherwise use a node-local Docker volume
  --domain DOMAIN       TLS hostname for a secure registry; avoids Docker daemon restarts
  --username USERNAME   Basic Auth username for --domain
  --password-stdin      Read the secure registry password from stdin
  --no-activate         Do not make the new secure registry the Builder push/pull registry
  --control-context CONTROL_CONTEXT
                        Use a saved cluster context without switching the current context
  --control-url CONTROL_URL
                        Control API URL to use instead of the current login context
  --token TOKEN         Management token to use with --control-url
  --insecure            Skip TLS verification for the control API
  --resolve-ip RESOLVE_IP
                        Connect to this IP while keeping the control hostname as Host
  --format {text,json,ndjson}
                        Output format
  --quiet               Print only the final result or error
  --timeout TIMEOUT

luma registry images#

usage: luma registry images [-h] [--refresh] [--control-context CONTROL_CONTEXT] [--control-url CONTROL_URL] [--token TOKEN] [--insecure] [--resolve-ip RESOLVE_IP] [--format {text,json,ndjson}] [--quiet]

arguments:
  -h, --help            show this help message and exit
  --refresh
  --control-context CONTROL_CONTEXT
                        Use a saved cluster context without switching the current context
  --control-url CONTROL_URL
                        Control API URL to use instead of the current login context
  --token TOKEN         Management token to use with --control-url
  --insecure            Skip TLS verification for the control API
  --resolve-ip RESOLVE_IP
                        Connect to this IP while keeping the control hostname as Host
  --format {text,json,ndjson}
                        Output format
  --quiet               Print only the final result or error

luma registry delete#

usage: luma registry delete [-h] [--execute-now] [--control-context CONTROL_CONTEXT] [--control-url CONTROL_URL] [--token TOKEN] [--insecure] [--resolve-ip RESOLVE_IP] [--format {text,json,ndjson}] [--quiet] repository digest

arguments:
  repository
  digest

arguments:
  -h, --help            show this help message and exit
  --execute-now         Bypass the queue grace period after a fresh protection check
  --control-context CONTROL_CONTEXT
                        Use a saved cluster context without switching the current context
  --control-url CONTROL_URL
                        Control API URL to use instead of the current login context
  --token TOKEN         Management token to use with --control-url
  --insecure            Skip TLS verification for the control API
  --resolve-ip RESOLVE_IP
                        Connect to this IP while keeping the control hostname as Host
  --format {text,json,ndjson}
                        Output format
  --quiet               Print only the final result or error

luma registry deletion#

usage: luma registry deletion [-h] [--force] [--control-context CONTROL_CONTEXT] [--control-url CONTROL_URL] [--token TOKEN] [--insecure] [--resolve-ip RESOLVE_IP] [--format {text,json,ndjson}] [--quiet] id {cancel,execute,restore}

arguments:
  id
  {cancel,execute,restore}

arguments:
  -h, --help            show this help message and exit
  --force
  --control-context CONTROL_CONTEXT
                        Use a saved cluster context without switching the current context
  --control-url CONTROL_URL
                        Control API URL to use instead of the current login context
  --token TOKEN         Management token to use with --control-url
  --insecure            Skip TLS verification for the control API
  --resolve-ip RESOLVE_IP
                        Connect to this IP while keeping the control hostname as Host
  --format {text,json,ndjson}
                        Output format
  --quiet               Print only the final result or error

luma registry gc#

usage: luma registry gc [-h] [--execute] [--force] [--control-context CONTROL_CONTEXT] [--control-url CONTROL_URL] [--token TOKEN] [--insecure] [--resolve-ip RESOLVE_IP] [--format {text,json,ndjson}] [--quiet]

arguments:
  -h, --help            show this help message and exit
  --execute
  --force
  --control-context CONTROL_CONTEXT
                        Use a saved cluster context without switching the current context
  --control-url CONTROL_URL
                        Control API URL to use instead of the current login context
  --token TOKEN         Management token to use with --control-url
  --insecure            Skip TLS verification for the control API
  --resolve-ip RESOLVE_IP
                        Connect to this IP while keeping the control hostname as Host
  --format {text,json,ndjson}
                        Output format
  --quiet               Print only the final result or error

luma registry policy#

usage: luma registry policy [-h] [--mode {off,recommend,enforce}] [--keep-last KEEP_LAST] [--max-age-days MAX_AGE_DAYS] [--system-keep-last SYSTEM_KEEP_LAST] [--queue-grace-hours QUEUE_GRACE_HOURS] [--gc-grace-days GC_GRACE_DAYS] [--warning-percent WARNING_PERCENT] [--critical-percent CRITICAL_PERCENT] [--emergency-percent EMERGENCY_PERCENT] [--control-context CONTROL_CONTEXT] [--control-url CONTROL_URL] [--token TOKEN] [--insecure] [--resolve-ip RESOLVE_IP] [--format {text,json,ndjson}] [--quiet]

arguments:
  -h, --help            show this help message and exit
  --mode {off,recommend,enforce}
  --keep-last KEEP_LAST
  --max-age-days MAX_AGE_DAYS
  --system-keep-last SYSTEM_KEEP_LAST
  --queue-grace-hours QUEUE_GRACE_HOURS
  --gc-grace-days GC_GRACE_DAYS
  --warning-percent WARNING_PERCENT
  --critical-percent CRITICAL_PERCENT
  --emergency-percent EMERGENCY_PERCENT
  --control-context CONTROL_CONTEXT
                        Use a saved cluster context without switching the current context
  --control-url CONTROL_URL
                        Control API URL to use instead of the current login context
  --token TOKEN         Management token to use with --control-url
  --insecure            Skip TLS verification for the control API
  --resolve-ip RESOLVE_IP
                        Connect to this IP while keeping the control hostname as Host
  --format {text,json,ndjson}
                        Output format
  --quiet               Print only the final result or error

luma git-provider#

usage: luma git-provider [-h] {list,set,remove,repos,refs} ...

arguments:
  {list,set,remove,repos,refs}
    repos               List repositories visible to a saved provider credential
    refs                List branches and tags for a repository

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

luma git-provider list#

usage: luma git-provider list [-h] [--control-context CONTROL_CONTEXT] [--control-url CONTROL_URL] [--token TOKEN] [--insecure] [--resolve-ip RESOLVE_IP] [--format {text,json,ndjson}] [--quiet]

arguments:
  -h, --help            show this help message and exit
  --control-context CONTROL_CONTEXT
                        Use a saved cluster context without switching the current context
  --control-url CONTROL_URL
                        Control API URL to use instead of the current login context
  --token TOKEN         Management token to use with --control-url
  --insecure            Skip TLS verification for the control API
  --resolve-ip RESOLVE_IP
                        Connect to this IP while keeping the control hostname as Host
  --format {text,json,ndjson}
                        Output format
  --quiet               Print only the final result or error

luma git-provider set#

usage: luma git-provider set [-h] [--base-url BASE_URL] [--clone-base-url CLONE_BASE_URL] [--username USERNAME] [--git-token PROVIDER_TOKEN] [--token-stdin] [--control-context CONTROL_CONTEXT] [--control-url CONTROL_URL] [--token TOKEN] [--insecure] [--resolve-ip RESOLVE_IP] {github,gitea} account

arguments:
  {github,gitea}
  account               Account label, for example personal or work

arguments:
  -h, --help            show this help message and exit
  --base-url BASE_URL   API base URL; required for Gitea, defaults to GitHub API for github
  --clone-base-url CLONE_BASE_URL
                        Clone URL base; defaults to GitHub/Gitea base URL
  --username USERNAME   Git username for HTTPS token clone
  --git-token PROVIDER_TOKEN
                        Provider PAT/token; prefer --token-stdin
  --token-stdin         Read provider PAT/token from stdin
  --control-context CONTROL_CONTEXT
                        Use a saved cluster context without switching the current context
  --control-url CONTROL_URL
                        Control API URL to use instead of the current login context
  --token TOKEN         Management token to use with --control-url
  --insecure            Skip TLS verification for the control API
  --resolve-ip RESOLVE_IP
                        Connect to this IP while keeping the control hostname as Host

luma git-provider remove#

usage: luma git-provider remove [-h] [--control-context CONTROL_CONTEXT] [--control-url CONTROL_URL] [--token TOKEN] [--insecure] [--resolve-ip RESOLVE_IP] id

arguments:
  id                    Provider credential id, for example github:personal

arguments:
  -h, --help            show this help message and exit
  --control-context CONTROL_CONTEXT
                        Use a saved cluster context without switching the current context
  --control-url CONTROL_URL
                        Control API URL to use instead of the current login context
  --token TOKEN         Management token to use with --control-url
  --insecure            Skip TLS verification for the control API
  --resolve-ip RESOLVE_IP
                        Connect to this IP while keeping the control hostname as Host

luma git-provider repos#

usage: luma git-provider repos [-h] [--control-context CONTROL_CONTEXT] [--control-url CONTROL_URL] [--token TOKEN] [--insecure] [--resolve-ip RESOLVE_IP] [--format {text,json,ndjson}] [--quiet] id

arguments:
  id

arguments:
  -h, --help            show this help message and exit
  --control-context CONTROL_CONTEXT
                        Use a saved cluster context without switching the current context
  --control-url CONTROL_URL
                        Control API URL to use instead of the current login context
  --token TOKEN         Management token to use with --control-url
  --insecure            Skip TLS verification for the control API
  --resolve-ip RESOLVE_IP
                        Connect to this IP while keeping the control hostname as Host
  --format {text,json,ndjson}
                        Output format
  --quiet               Print only the final result or error

luma git-provider refs#

usage: luma git-provider refs [-h] [--control-context CONTROL_CONTEXT] [--control-url CONTROL_URL] [--token TOKEN] [--insecure] [--resolve-ip RESOLVE_IP] [--format {text,json,ndjson}] [--quiet] id repository

arguments:
  id
  repository            Repository full name, for example owner/name

arguments:
  -h, --help            show this help message and exit
  --control-context CONTROL_CONTEXT
                        Use a saved cluster context without switching the current context
  --control-url CONTROL_URL
                        Control API URL to use instead of the current login context
  --token TOKEN         Management token to use with --control-url
  --insecure            Skip TLS verification for the control API
  --resolve-ip RESOLVE_IP
                        Connect to this IP while keeping the control hostname as Host
  --format {text,json,ndjson}
                        Output format
  --quiet               Print only the final result or error

luma bootstrap#

usage: luma bootstrap [-h] {manager} ...

arguments:
  {manager}

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

luma bootstrap manager#

usage: luma bootstrap manager [-h] --domain DOMAIN [--node NODE] [--profile {cn-edge,egress-gateway,global-worker,home-node,single-node}] [--http-port HTTP_PORT] [--https-port HTTPS_PORT] [--skip-egress] [--overwrite-control-state]

arguments:
  -h, --help            show this help message and exit
  --domain DOMAIN
  --node NODE
  --profile {cn-edge,egress-gateway,global-worker,home-node,single-node}
  --http-port HTTP_PORT
                        Public Traefik HTTP port
  --https-port HTTPS_PORT
                        Public Traefik HTTPS port
  --skip-egress
  --overwrite-control-state

luma update#

usage: luma update [-h] [--domain DOMAIN] [--node NODE] [--profile {cn-edge,egress-gateway,global-worker,home-node,single-node}] [--http-port HTTP_PORT] [--https-port HTTPS_PORT] [--skip-egress] [--overwrite-control-state] [--install-ref INSTALL_REF] [--detach] [--control-context CONTROL_CONTEXT] [--control-url CONTROL_URL] [--token TOKEN] [--insecure] [--resolve-ip RESOLVE_IP] [target] ...

Update the local CLI. With no target, Luma hot-refreshes manager control only when local manager
state exists; clients and workers update CLI only.

arguments:
  [target]
    manager             force a manager control-plane refresh
    fleet               update Luma on registered non-manager nodes with ready agents

arguments:
  -h, --help            show this help message and exit
  --domain DOMAIN       Control domain. Defaults to the domain stored in Manager Control state
                        (/opt/luma/control/control.sqlite3 by default).
  --node NODE
  --profile {cn-edge,egress-gateway,global-worker,home-node,single-node}
  --http-port HTTP_PORT
                        Public Traefik HTTP port
  --https-port HTTPS_PORT
                        Public Traefik HTTPS port
  --skip-egress
  --overwrite-control-state
  --install-ref INSTALL_REF
                        Git ref passed to the install script as LUMA_INSTALL_REF
  --detach              Run a manager update in a detached transaction and write progress to a local
                        log
  --control-context CONTROL_CONTEXT
                        Use a saved cluster context without switching the current context
  --control-url CONTROL_URL
                        Control API URL to use instead of the current login context
  --token TOKEN         Management token to use with --control-url
  --insecure            Skip TLS verification for the control API
  --resolve-ip RESOLVE_IP
                        Connect to this IP while keeping the control hostname as Host

luma update manager#

usage: luma update manager [-h] [--domain DOMAIN] [--node NODE] [--profile {cn-edge,egress-gateway,global-worker,home-node,single-node}] [--http-port HTTP_PORT] [--https-port HTTPS_PORT] [--skip-egress] [--overwrite-control-state] [--install-ref INSTALL_REF] [--detach] [--control-context CONTROL_CONTEXT] [--control-url CONTROL_URL] [--token TOKEN] [--insecure] [--resolve-ip RESOLVE_IP]

arguments:
  -h, --help            show this help message and exit
  --domain DOMAIN       Control domain. Defaults to the domain stored in Manager Control state
                        (/opt/luma/control/control.sqlite3 by default).
  --node NODE
  --profile {cn-edge,egress-gateway,global-worker,home-node,single-node}
  --http-port HTTP_PORT
                        Public Traefik HTTP port
  --https-port HTTPS_PORT
                        Public Traefik HTTPS port
  --skip-egress
  --overwrite-control-state
  --install-ref INSTALL_REF
                        Git ref passed to the install script as LUMA_INSTALL_REF
  --detach              Run a manager update in a detached transaction and write progress to a local
                        log
  --control-context CONTROL_CONTEXT
                        Use a saved cluster context without switching the current context
  --control-url CONTROL_URL
                        Control API URL to use instead of the current login context
  --token TOKEN         Management token to use with --control-url
  --insecure            Skip TLS verification for the control API
  --resolve-ip RESOLVE_IP
                        Connect to this IP while keeping the control hostname as Host

luma update fleet#

usage: luma update fleet [-h] [--install-ref FLEET_INSTALL_REF] [--all] [--include-manager] [--timeout TIMEOUT] [--control-context CONTROL_CONTEXT] [--control-url CONTROL_URL] [--token TOKEN] [--insecure] [--resolve-ip RESOLVE_IP] [--format {text,json,ndjson}] [--quiet]

arguments:
  -h, --help            show this help message and exit
  --install-ref FLEET_INSTALL_REF
                        Git ref passed to the installer on every node
  --all                 Include offline nodes in the report as skipped
  --include-manager     Also update manager nodes through fleet tasks
  --timeout TIMEOUT     Per-node update timeout in seconds
  --control-context CONTROL_CONTEXT
                        Use a saved cluster context without switching the current context
  --control-url CONTROL_URL
                        Control API URL to use instead of the current login context
  --token TOKEN         Management token to use with --control-url
  --insecure            Skip TLS verification for the control API
  --resolve-ip RESOLVE_IP
                        Connect to this IP while keeping the control hostname as Host
  --format {text,json,ndjson}
                        Output format
  --quiet               Print only the final result or error

luma doctor#

usage: luma doctor [-h] [--control-context CONTROL_CONTEXT] [--control-url CONTROL_URL] [--token TOKEN] [--insecure] [--resolve-ip RESOLVE_IP] [--format {text,json,ndjson}] [--quiet] [--local] [--deep]

arguments:
  -h, --help            show this help message and exit
  --control-context CONTROL_CONTEXT
                        Use a saved cluster context without switching the current context
  --control-url CONTROL_URL
                        Control API URL to use instead of the current login context
  --token TOKEN         Management token to use with --control-url
  --insecure            Skip TLS verification for the control API
  --resolve-ip RESOLVE_IP
                        Connect to this IP while keeping the control hostname as Host
  --format {text,json,ndjson}
                        Output format
  --quiet               Print only the final result or error
  --local               Inspect local installation identity and dependency policy without contacting
                        Control or changing state
  --deep                Run slower live checks

luma manager#

usage: luma manager [-h] {ip-change} ...

arguments:
  {ip-change}
    ip-change  Recover the manager control plane after its public IPv4 address changes

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

luma manager ip-change#

usage: luma manager ip-change [-h] --old OLD_IP --new NEW_IP --domain DOMAIN [--dry-run]

arguments:
  -h, --help       show this help message and exit
  --old OLD_IP     Previous manager public IPv4 address
  --new NEW_IP     New manager public IPv4 address
  --domain DOMAIN  Control-plane hostname, without scheme
  --dry-run        Validate and show the recovery plan without changing anything

luma node#

usage: luma node [-h] {list,bootstrap,join,exit,remove,status,nomad-join} ...

arguments:
  {list,bootstrap,join,exit,remove,status,nomad-join}
    nomad-join          ask a ready node agent to install and join Nomad on that node

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

luma node list#

usage: luma node list [-h]

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

luma node bootstrap#

usage: luma node bootstrap [-h] --profile {cn-edge,egress-gateway,global-worker,home-node,single-node} [--skip-egress] node

arguments:
  node

arguments:
  -h, --help            show this help message and exit
  --profile {cn-edge,egress-gateway,global-worker,home-node,single-node}
  --skip-egress         Skip egress setup during bootstrap; run luma egress setup later

luma node join#

usage: luma node join [-h] --token TOKEN [--region REGION] [--name NAME] [--engine {nomad}] [--insecure] [--resolve-ip RESOLVE_IP] endpoint

arguments:
  endpoint

arguments:
  -h, --help            show this help message and exit
  --token TOKEN
  --region REGION       Built-in region (cn, global, home) or a region created with luma region
                        create
  --name NAME
  --engine {nomad}      Orchestrator to join; Nomad is the only supported engine
  --insecure            Skip TLS verification for self-signed control endpoints
  --resolve-ip RESOLVE_IP
                        Connect to this IP while keeping the endpoint hostname as Host

luma node exit#

usage: luma node exit [-h] [--endpoint ENDPOINT] [--token TOKEN] [--name NAME] [--insecure] [--resolve-ip RESOLVE_IP] [--tailscale] [--prune-docker]

arguments:
  -h, --help            show this help message and exit
  --endpoint ENDPOINT   Control endpoint; when set, unregister this node from Luma Control
  --token TOKEN         Management token or node join token used with --endpoint
  --name NAME           Luma node name to unregister; defaults to this node's registered label or
                        Docker name
  --insecure            Skip TLS verification for self-signed control endpoints
  --resolve-ip RESOLVE_IP
                        Connect to this IP while keeping the endpoint hostname as Host
  --tailscale           Also log out Tailscale on this node
  --prune-docker        Also prune unused Docker containers, networks, images, and volumes

luma node remove#

usage: luma node remove [-h] [--control-url CONTROL_URL] [--token TOKEN] [--insecure] [--resolve-ip RESOLVE_IP] name

arguments:
  name

arguments:
  -h, --help            show this help message and exit
  --control-url CONTROL_URL
                        Control API URL to use instead of the current login context
  --token TOKEN         Management token to use with --control-url
  --insecure            Skip TLS verification for self-signed control endpoints
  --resolve-ip RESOLVE_IP
                        Connect to this IP while keeping the endpoint hostname as Host

luma node status#

usage: luma node status [-h] [--control-context CONTROL_CONTEXT] [--control-url CONTROL_URL] [--token TOKEN] [--insecure] [--resolve-ip RESOLVE_IP] [--format {text,json,ndjson}] [--quiet] [name]

arguments:
  name                  Optional Luma node name, display name, hostname, or alias to show

arguments:
  -h, --help            show this help message and exit
  --control-context CONTROL_CONTEXT
                        Use a saved cluster context without switching the current context
  --control-url CONTROL_URL
                        Control API URL to use instead of the current login context
  --token TOKEN         Management token to use with --control-url
  --insecure            Skip TLS verification for the control API
  --resolve-ip RESOLVE_IP
                        Connect to this IP while keeping the control hostname as Host
  --format {text,json,ndjson}
                        Output format
  --quiet               Print only the final result or error

luma node nomad-join#

usage: luma node nomad-join [-h] [--region REGION] [--server-addr SERVER_ADDR] [--timeout TIMEOUT] [--control-context CONTROL_CONTEXT] [--control-url CONTROL_URL] [--token TOKEN] [--insecure] [--resolve-ip RESOLVE_IP] [--format {text,json,ndjson}] [--quiet] name

arguments:
  name

arguments:
  -h, --help            show this help message and exit
  --region REGION       Override the node's registered region
  --server-addr SERVER_ADDR
                        Nomad RPC address to join; defaults to the control-plane join address
  --timeout TIMEOUT     Join timeout in seconds
  --control-context CONTROL_CONTEXT
                        Use a saved cluster context without switching the current context
  --control-url CONTROL_URL
                        Control API URL to use instead of the current login context
  --token TOKEN         Management token to use with --control-url
  --insecure            Skip TLS verification for the control API
  --resolve-ip RESOLVE_IP
                        Connect to this IP while keeping the control hostname as Host
  --format {text,json,ndjson}
                        Output format
  --quiet               Print only the final result or error

luma region#

usage: luma region [-h] {list,create,remove} ...

arguments:
  {list,create,remove}
    list                List built-in and custom regions
    create              Create a custom scheduling region
    remove              Remove an unused custom region

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

luma region list#

usage: luma region list [-h] [--control-context CONTROL_CONTEXT] [--control-url CONTROL_URL] [--token TOKEN] [--insecure] [--resolve-ip RESOLVE_IP] [--format {text,json,ndjson}] [--quiet]

arguments:
  -h, --help            show this help message and exit
  --control-context CONTROL_CONTEXT
                        Use a saved cluster context without switching the current context
  --control-url CONTROL_URL
                        Control API URL to use instead of the current login context
  --token TOKEN         Management token to use with --control-url
  --insecure            Skip TLS verification for the control API
  --resolve-ip RESOLVE_IP
                        Connect to this IP while keeping the control hostname as Host
  --format {text,json,ndjson}
                        Output format
  --quiet               Print only the final result or error

luma region create#

usage: luma region create [-h] [--egress {proxy,direct}] [--control-context CONTROL_CONTEXT] [--control-url CONTROL_URL] [--token TOKEN] [--insecure] [--resolve-ip RESOLVE_IP] [--format {text,json,ndjson}] [--quiet] name

arguments:
  name

arguments:
  -h, --help            show this help message and exit
  --egress {proxy,direct}
                        Join/image-pull egress: proxy uses the manager gateway, direct does not
  --control-context CONTROL_CONTEXT
                        Use a saved cluster context without switching the current context
  --control-url CONTROL_URL
                        Control API URL to use instead of the current login context
  --token TOKEN         Management token to use with --control-url
  --insecure            Skip TLS verification for the control API
  --resolve-ip RESOLVE_IP
                        Connect to this IP while keeping the control hostname as Host
  --format {text,json,ndjson}
                        Output format
  --quiet               Print only the final result or error

luma region remove#

usage: luma region remove [-h] [--control-context CONTROL_CONTEXT] [--control-url CONTROL_URL] [--token TOKEN] [--insecure] [--resolve-ip RESOLVE_IP] [--format {text,json,ndjson}] [--quiet] name

arguments:
  name

arguments:
  -h, --help            show this help message and exit
  --control-context CONTROL_CONTEXT
                        Use a saved cluster context without switching the current context
  --control-url CONTROL_URL
                        Control API URL to use instead of the current login context
  --token TOKEN         Management token to use with --control-url
  --insecure            Skip TLS verification for the control API
  --resolve-ip RESOLVE_IP
                        Connect to this IP while keeping the control hostname as Host
  --format {text,json,ndjson}
                        Output format
  --quiet               Print only the final result or error

luma cloudflare#

usage: luma cloudflare [-h] {connect} ...

arguments:
  {connect}

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

luma cloudflare connect#

usage: luma cloudflare connect [-h] --zone ZONE

arguments:
  -h, --help   show this help message and exit
  --zone ZONE

luma egress#

usage: luma egress [-h] {setup,refresh} ...

arguments:
  {setup,refresh}

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

luma egress setup#

usage: luma egress setup [-h]

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

luma egress refresh#

usage: luma egress refresh [-h]

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

luma tailscale#

usage: luma tailscale [-h] {connect} ...

arguments:
  {connect}

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

luma tailscale connect#

usage: luma tailscale connect [-h]

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

luma service#

usage: luma service [-h] {new,list,inspect,events,history,logs,remove,restart} ...

arguments:
  {new,list,inspect,events,history,logs,remove,restart}
    list                List deployed services and replica health
    inspect             Inspect an application or exact deployed service
    events              Show recent runtime events for the latest task allocation
    history             Page build and deployment attempts (Nomad versions remain under luma
                        history)
    logs                Read application logs

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

luma service new#

usage: luma service new [-h] [--output OUTPUT]

arguments:
  -h, --help       show this help message and exit
  --output OUTPUT

luma service list#

usage: luma service list [-h] [--region REGION] [--stack STACK] [--control-context CONTROL_CONTEXT] [--control-url CONTROL_URL] [--token TOKEN] [--insecure] [--resolve-ip RESOLVE_IP] [--format {text,json,ndjson}] [--quiet]

arguments:
  -h, --help            show this help message and exit
  --region REGION       Filter by scheduling region
  --stack STACK         Filter by application/stack
  --control-context CONTROL_CONTEXT
                        Use a saved cluster context without switching the current context
  --control-url CONTROL_URL
                        Control API URL to use instead of the current login context
  --token TOKEN         Management token to use with --control-url
  --insecure            Skip TLS verification for the control API
  --resolve-ip RESOLVE_IP
                        Connect to this IP while keeping the control hostname as Host
  --format {text,json,ndjson}
                        Output format
  --quiet               Print only the final result or error

luma service inspect#

usage: luma service inspect [-h] [--control-context CONTROL_CONTEXT] [--control-url CONTROL_URL] [--token TOKEN] [--insecure] [--resolve-ip RESOLVE_IP] [--format {text,json,ndjson}] [--quiet] name

arguments:
  name                  Application/stack or full service name

arguments:
  -h, --help            show this help message and exit
  --control-context CONTROL_CONTEXT
                        Use a saved cluster context without switching the current context
  --control-url CONTROL_URL
                        Control API URL to use instead of the current login context
  --token TOKEN         Management token to use with --control-url
  --insecure            Skip TLS verification for the control API
  --resolve-ip RESOLVE_IP
                        Connect to this IP while keeping the control hostname as Host
  --format {text,json,ndjson}
                        Output format
  --quiet               Print only the final result or error

luma service events#

usage: luma service events [-h] [--control-context CONTROL_CONTEXT] [--control-url CONTROL_URL] [--token TOKEN] [--insecure] [--resolve-ip RESOLVE_IP] [--format {text,json,ndjson}] [--quiet] name

arguments:
  name                  Deployed service full name

arguments:
  -h, --help            show this help message and exit
  --control-context CONTROL_CONTEXT
                        Use a saved cluster context without switching the current context
  --control-url CONTROL_URL
                        Control API URL to use instead of the current login context
  --token TOKEN         Management token to use with --control-url
  --insecure            Skip TLS verification for the control API
  --resolve-ip RESOLVE_IP
                        Connect to this IP while keeping the control hostname as Host
  --format {text,json,ndjson}
                        Output format
  --quiet               Print only the final result or error

luma service history#

usage: luma service history [-h] [--id RECORD_ID] [--kind {build,deployment}] [--limit LIMIT] [--cursor CURSOR] [--status STATUS] [--source {build,cli,dashboard}] [--since SINCE] [--until UNTIL] [--control-context CONTROL_CONTEXT] [--control-url CONTROL_URL] [--token TOKEN] [--insecure] [--resolve-ip RESOLVE_IP] [--format {text,json,ndjson}] [--quiet] [name]

arguments:
  name                  Filter by application name

arguments:
  -h, --help            show this help message and exit
  --id RECORD_ID        Read a history record and its step log; requires --kind
  --kind {build,deployment}
                        Filter record type, or identify --id type
  --limit LIMIT         Records per page (1-100, default: 50)
  --cursor CURSOR       Opaque nextCursor from the preceding page with the same filters
  --status STATUS       Filter by exact recorded status
  --source {build,cli,dashboard}
                        Filter by history source
  --since SINCE         Created at or after Unix seconds or RFC3339 timestamp
  --until UNTIL         Created at or before Unix seconds or RFC3339 timestamp
  --control-context CONTROL_CONTEXT
                        Use a saved cluster context without switching the current context
  --control-url CONTROL_URL
                        Control API URL to use instead of the current login context
  --token TOKEN         Management token to use with --control-url
  --insecure            Skip TLS verification for the control API
  --resolve-ip RESOLVE_IP
                        Connect to this IP while keeping the control hostname as Host
  --format {text,json,ndjson}
                        Output format
  --quiet               Print only the final result or error

luma service logs#

usage: luma service logs [-h] [--tail TAIL] [--previous] [--allocation ALLOCATION] [--follow] [--control-context CONTROL_CONTEXT] [--control-url CONTROL_URL] [--token TOKEN] [--insecure] [--resolve-ip RESOLVE_IP] [--format {text,json,ndjson}] [--quiet] name

arguments:
  name                  Deployed service full name

arguments:
  -h, --help            show this help message and exit
  --tail TAIL           Recent line budget shared across all selected sources (1-500)
  --previous            Read stopped allocations instead of running allocations
  --allocation ALLOCATION
                        Only this allocation ID
  --follow, -f          Follow logs until interrupted; use text or ndjson
  --control-context CONTROL_CONTEXT
                        Use a saved cluster context without switching the current context
  --control-url CONTROL_URL
                        Control API URL to use instead of the current login context
  --token TOKEN         Management token to use with --control-url
  --insecure            Skip TLS verification for the control API
  --resolve-ip RESOLVE_IP
                        Connect to this IP while keeping the control hostname as Host
  --format {text,json,ndjson}
                        Output format
  --quiet               Print only the final result or error

luma service remove#

usage: luma service remove [-h] [--control-context CONTROL_CONTEXT] [--control-url CONTROL_URL] [--token TOKEN] [--insecure] [--resolve-ip RESOLVE_IP] [--format {text,json,ndjson}] [--quiet] [--skip-dns] [--skip-orchestrator] [--delete-storage] [--dry-run] [--timeout TIMEOUT] service

arguments:
  service               Deployed service or Compose application name

arguments:
  -h, --help            show this help message and exit
  --control-context CONTROL_CONTEXT
                        Use a saved cluster context without switching the current context
  --control-url CONTROL_URL
                        Control API URL to use instead of the current login context
  --token TOKEN         Management token to use with --control-url
  --insecure            Skip TLS verification for the control API
  --resolve-ip RESOLVE_IP
                        Connect to this IP while keeping the control hostname as Host
  --format {text,json,ndjson}
                        Output format
  --quiet               Print only the final result or error
  --skip-dns            Keep Cloudflare DNS records
  --skip-orchestrator   Keep the Nomad job running
  --delete-storage      Delete removable storage referenced by the recorded deployment
  --dry-run             Show what would be removed without changing the manager
  --timeout TIMEOUT     Seconds to wait for the control-plane remove response

luma service restart#

usage: luma service restart [-h] [--control-context CONTROL_CONTEXT] [--control-url CONTROL_URL] [--token TOKEN] [--insecure] [--resolve-ip RESOLVE_IP] [--format {text,json,ndjson}] [--quiet] [--service SERVICE] [--mode {recreate,task}] [--timeout TIMEOUT] stack

arguments:
  stack                 Deployed service or Compose application name

arguments:
  -h, --help            show this help message and exit
  --control-context CONTROL_CONTEXT
                        Use a saved cluster context without switching the current context
  --control-url CONTROL_URL
                        Control API URL to use instead of the current login context
  --token TOKEN         Management token to use with --control-url
  --insecure            Skip TLS verification for the control API
  --resolve-ip RESOLVE_IP
                        Connect to this IP while keeping the control hostname as Host
  --format {text,json,ndjson}
                        Output format
  --quiet               Print only the final result or error
  --service SERVICE     Task/service name inside a Compose application
  --mode {recreate,task}
                        recreate stops the allocation; task restarts in place
  --timeout TIMEOUT     Seconds to wait for the control-plane restart response

luma validate#

usage: luma validate [-h] [--engine {nomad}] [--format {text,json,ndjson}] [--quiet] service

arguments:
  service

arguments:
  -h, --help            show this help message and exit
  --engine {nomad}      Orchestrator to validate for; Nomad is the only supported engine
  --format {text,json,ndjson}
                        Output format
  --quiet               Print only the final result or error

luma render#

usage: luma render [-h] [--engine {nomad}] service

arguments:
  service

arguments:
  -h, --help        show this help message and exit
  --engine {nomad}  Orchestrator to render for; Nomad is the only supported engine

luma dns-sync#

usage: luma dns-sync [-h] service

arguments:
  service

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

luma deploy#

usage: luma deploy [-h] [--workflow-app WORKFLOW_APP] [--accept-workflow-change] [--workflow-note WORKFLOW_NOTE] [--control-context CONTROL_CONTEXT] [--control-url CONTROL_URL] [--token TOKEN] [--insecure] [--resolve-ip RESOLVE_IP] [--format {text,json,ndjson}] [--quiet] [--dry-run] [--skip-dns] [--skip-orchestrator] [--env DEPLOY_ENV_FILE] [--timeout TIMEOUT] [--commit] [--push] service

arguments:
  service

arguments:
  -h, --help            show this help message and exit
  --workflow-app WORKFLOW_APP
                        Application workflow to check (required when a repository matches several
                        applications)
  --accept-workflow-change
                        Continue after the user has explicitly approved the displayed workflow
                        differences
  --workflow-note WORKFLOW_NOTE
                        Record why this build/deploy workflow is used; do not include secrets
  --control-context CONTROL_CONTEXT
                        Use a saved cluster context without switching the current context
  --control-url CONTROL_URL
                        Control API URL to use instead of the current login context
  --token TOKEN         Management token to use with --control-url
  --insecure            Skip TLS verification for the control API
  --resolve-ip RESOLVE_IP
                        Connect to this IP while keeping the control hostname as Host
  --format {text,json,ndjson}
                        Output format
  --quiet               Print only the final result or error
  --dry-run
  --skip-dns
  --skip-orchestrator
  --env DEPLOY_ENV_FILE
                        Use this .env file as scoped deployment secrets for this service
  --timeout TIMEOUT     Seconds to wait for the control-plane deploy response
  --commit              Deprecated for control-plane deploy
  --push                Deprecated for control-plane deploy

luma import#

usage: luma import [-h] [--workflow-app WORKFLOW_APP] [--accept-workflow-change] [--workflow-note WORKFLOW_NOTE] [--provider-id PROVIDER_ID] [--repository REPOSITORY] [--build-node BUILD_NODE] [--ref REF] [--region REGION] [--exposure EXPOSURE] [--domain DOMAIN] [--port PORT] [--manifest MANIFEST] [--compose-sidecar COMPOSE_SIDECAR] [--env DEPLOY_ENV_FILE] [--platform PLATFORM] [--context BUILD_CONTEXT] [--dockerfile DOCKERFILE] [--registry-host REGISTRY_HOST] [--proxy-mode {auto,direct}] [--control-context CONTROL_CONTEXT] [--control-url CONTROL_URL] [--token TOKEN] [--insecure] [--resolve-ip RESOLVE_IP] [--format {text,json,ndjson}] [--quiet] [--timeout TIMEOUT] [repo]

Build and deploy from Git. Luma scans for single-service .luma.yml manifests and Compose sidecars
such as luma.compose.yml. For Compose imports, services with build: are built on the builder node,
pushed to the internal registry, and rewritten to image: before compose deploy.

arguments:
  repo                  Git repository URL or owner/name (owner/name expands to
                        https://github.com/owner/name.git); omit when using --provider-id +
                        --repository

arguments:
  -h, --help            show this help message and exit
  --workflow-app WORKFLOW_APP
                        Application workflow to check (required when a repository matches several
                        applications)
  --accept-workflow-change
                        Continue after the user has explicitly approved the displayed workflow
                        differences
  --workflow-note WORKFLOW_NOTE
                        Record why this build/deploy workflow is used; do not include secrets
  --provider-id PROVIDER_ID
                        Saved Git provider credential id to use for clone/list-backed imports
  --repository REPOSITORY
                        Repository full name for --provider-id, for example owner/name
  --build-node BUILD_NODE
                        Override the declared builder node used to clone and build the image
  --ref REF             Git branch or tag to build (default: repository default branch)
  --region REGION       Override region from the repo's service manifest or Compose sidecar
  --exposure EXPOSURE   Override exposure from the repo's .luma.yml for single-service imports
  --domain DOMAIN       Override domain from the repo's .luma.yml for single-service imports
  --port PORT           Override container port from the repo's .luma.yml for single-service imports
  --manifest MANIFEST   Use this Luma manifest when the repository does not contain one
  --compose-sidecar COMPOSE_SIDECAR
                        Select one repository-relative Luma Compose sidecar instead of auto-
                        discovery
  --env DEPLOY_ENV_FILE
                        Import this .env file as scoped deployment secrets for the imported
                        app/stack
  --platform PLATFORM   Build platform (default: linux/amd64 or the repo's build.platform)
  --context BUILD_CONTEXT
                        Docker build context within the repo (default: .)
  --dockerfile DOCKERFILE
                        Dockerfile path within the repo (default: Dockerfile)
  --registry-host REGISTRY_HOST
                        Registry host other nodes pull from (default: <build-node>:5000)
  --proxy-mode {auto,direct}
                        Builder outbound network mode: auto uses the node/region policy; direct
                        explicitly disables the build proxy
  --control-context CONTROL_CONTEXT
                        Use a saved cluster context without switching the current context
  --control-url CONTROL_URL
                        Control API URL to use instead of the current login context
  --token TOKEN         Management token to use with --control-url
  --insecure            Skip TLS verification for the control API
  --resolve-ip RESOLVE_IP
                        Connect to this IP while keeping the control hostname as Host
  --format {text,json,ndjson}
                        Output format
  --quiet               Print only the final result or error
  --timeout TIMEOUT     Seconds to wait for the build+deploy response

luma build#

usage: luma build [-h] {list,logs,retry,cancel,local,config} ...

arguments:
  {list,logs,retry,cancel,local,config}
    list                List recent repository import build runs
    logs                Show a build run's recorded step log
    retry               Retry a recorded build run
    cancel              Cancel an active repository import build
    local               Build a local checkout, push it to the project's Luma registry path, and
                        deploy it
    config              Declare builder nodes and internal registry defaults

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

luma build list#

usage: luma build list [-h] [--control-context CONTROL_CONTEXT] [--control-url CONTROL_URL] [--token TOKEN] [--insecure] [--resolve-ip RESOLVE_IP] [--format {text,json,ndjson}] [--quiet] [--limit LIMIT] [--cursor CURSOR] [--app APP] [--status STATUS] [--source {build,cli,dashboard}] [--since SINCE] [--until UNTIL]

arguments:
  -h, --help            show this help message and exit
  --control-context CONTROL_CONTEXT
                        Use a saved cluster context without switching the current context
  --control-url CONTROL_URL
                        Control API URL to use instead of the current login context
  --token TOKEN         Management token to use with --control-url
  --insecure            Skip TLS verification for the control API
  --resolve-ip RESOLVE_IP
                        Connect to this IP while keeping the control hostname as Host
  --format {text,json,ndjson}
                        Output format
  --quiet               Print only the final result or error
  --limit LIMIT         Records per page (1-100, default: 50)
  --cursor CURSOR       Opaque nextCursor from the preceding page with the same filters
  --app APP             Filter by application name
  --status STATUS       Filter by exact recorded status
  --source {build,cli,dashboard}
                        Filter by history source
  --since SINCE         Created at or after Unix seconds or RFC3339 timestamp
  --until UNTIL         Created at or before Unix seconds or RFC3339 timestamp

luma build logs#

usage: luma build logs [-h] [--limit LIMIT] [--cursor CURSOR] [--control-context CONTROL_CONTEXT] [--control-url CONTROL_URL] [--token TOKEN] [--insecure] [--resolve-ip RESOLVE_IP] [--format {text,json,ndjson}] [--quiet] id

arguments:
  id

arguments:
  -h, --help            show this help message and exit
  --limit LIMIT         Records per page (1-100, default: 50)
  --cursor CURSOR       Opaque nextCursor from the preceding page with the same filters
  --control-context CONTROL_CONTEXT
                        Use a saved cluster context without switching the current context
  --control-url CONTROL_URL
                        Control API URL to use instead of the current login context
  --token TOKEN         Management token to use with --control-url
  --insecure            Skip TLS verification for the control API
  --resolve-ip RESOLVE_IP
                        Connect to this IP while keeping the control hostname as Host
  --format {text,json,ndjson}
                        Output format
  --quiet               Print only the final result or error

luma build retry#

usage: luma build retry [-h] [--workflow-app WORKFLOW_APP] [--accept-workflow-change] [--workflow-note WORKFLOW_NOTE] [--control-context CONTROL_CONTEXT] [--control-url CONTROL_URL] [--token TOKEN] [--insecure] [--resolve-ip RESOLVE_IP] [--format {text,json,ndjson}] [--quiet] [--timeout TIMEOUT] [--env DEPLOY_ENV_FILE] id

arguments:
  id

arguments:
  -h, --help            show this help message and exit
  --workflow-app WORKFLOW_APP
                        Application workflow to check (required when a repository matches several
                        applications)
  --accept-workflow-change
                        Continue after the user has explicitly approved the displayed workflow
                        differences
  --workflow-note WORKFLOW_NOTE
                        Record why this build/deploy workflow is used; do not include secrets
  --control-context CONTROL_CONTEXT
                        Use a saved cluster context without switching the current context
  --control-url CONTROL_URL
                        Control API URL to use instead of the current login context
  --token TOKEN         Management token to use with --control-url
  --insecure            Skip TLS verification for the control API
  --resolve-ip RESOLVE_IP
                        Connect to this IP while keeping the control hostname as Host
  --format {text,json,ndjson}
                        Output format
  --quiet               Print only the final result or error
  --timeout TIMEOUT
  --env DEPLOY_ENV_FILE
                        Use this .env file as scoped deployment secrets for the retried import

luma build cancel#

usage: luma build cancel [-h] [--control-context CONTROL_CONTEXT] [--control-url CONTROL_URL] [--token TOKEN] [--insecure] [--resolve-ip RESOLVE_IP] [--format {text,json,ndjson}] [--quiet] id

arguments:
  id

arguments:
  -h, --help            show this help message and exit
  --control-context CONTROL_CONTEXT
                        Use a saved cluster context without switching the current context
  --control-url CONTROL_URL
                        Control API URL to use instead of the current login context
  --token TOKEN         Management token to use with --control-url
  --insecure            Skip TLS verification for the control API
  --resolve-ip RESOLVE_IP
                        Connect to this IP while keeping the control hostname as Host
  --format {text,json,ndjson}
                        Output format
  --quiet               Print only the final result or error

luma build local#

usage: luma build local [-h] [--workflow-app WORKFLOW_APP] [--accept-workflow-change] [--workflow-note WORKFLOW_NOTE] [--repo-url REPO_URL] [--compose-sidecar COMPOSE_SIDECAR] [--region REGION] [--exposure EXPOSURE] [--domain DOMAIN] [--port PORT] [--platform PLATFORM] [--builder BUILDER] [--proxy PROXY] [--context BUILD_CONTEXT] [--dockerfile DOCKERFILE] [--env DEPLOY_ENV_FILE] [--timeout TIMEOUT] [--control-context CONTROL_CONTEXT] [--control-url CONTROL_URL] [--token TOKEN] [--insecure] [--resolve-ip RESOLVE_IP] [--format {text,json,ndjson}] [--quiet] [path]

arguments:
  path

arguments:
  -h, --help            show this help message and exit
  --workflow-app WORKFLOW_APP
                        Application workflow to check (required when a repository matches several
                        applications)
  --accept-workflow-change
                        Continue after the user has explicitly approved the displayed workflow
                        differences
  --workflow-note WORKFLOW_NOTE
                        Record why this build/deploy workflow is used; do not include secrets
  --repo-url REPO_URL   Project Git URL (default: local origin remote)
  --compose-sidecar COMPOSE_SIDECAR
                        Select one repository-relative Luma Compose sidecar
  --region REGION       Override deployment region
  --exposure EXPOSURE   Override single-service exposure
  --domain DOMAIN       Override single-service domain
  --port PORT           Override single-service container port
  --platform PLATFORM   Build platform override
  --builder BUILDER     Existing local Docker Buildx builder
  --proxy PROXY         HTTP proxy for local image pulls and Dockerfile RUN steps
  --context BUILD_CONTEXT
                        Docker build context within the local project
  --dockerfile DOCKERFILE
                        Dockerfile path within the local project
  --env DEPLOY_ENV_FILE
                        Import this .env file as scoped deployment secrets
  --timeout TIMEOUT     Seconds allowed for the local build and deploy
  --control-context CONTROL_CONTEXT
                        Use a saved cluster context without switching the current context
  --control-url CONTROL_URL
                        Control API URL to use instead of the current login context
  --token TOKEN         Management token to use with --control-url
  --insecure            Skip TLS verification for the control API
  --resolve-ip RESOLVE_IP
                        Connect to this IP while keeping the control hostname as Host
  --format {text,json,ndjson}
                        Output format
  --quiet               Print only the final result or error

luma build config#

usage: luma build config [-h] [--node NODES] [--default-node DEFAULT_NODE] [--registry-host REGISTRY_HOST] [--push-host PUSH_HOST] [--direct-egress-node DIRECT_EGRESS_NODES] [--clear-direct-egress] [--control-context CONTROL_CONTEXT] [--control-url CONTROL_URL] [--token TOKEN] [--insecure] [--resolve-ip RESOLVE_IP] [--format {text,json,ndjson}] [--quiet]

arguments:
  -h, --help            show this help message and exit
  --node NODES          Declared builder node; repeat for multiple builders
  --default-node DEFAULT_NODE
                        Default builder node for luma import
  --registry-host REGISTRY_HOST
                        Registry host that target nodes pull from, for example 100.66.177.70:5000
  --push-host PUSH_HOST
                        Registry host BuildKit pushes to; use the builder Tailscale endpoint, not
                        localhost:5000
  --direct-egress-node DIRECT_EGRESS_NODES
                        Builder node with reliable direct internet access; repeat for multiple nodes
  --clear-direct-egress
                        Clear the direct-egress builder node list
  --control-context CONTROL_CONTEXT
                        Use a saved cluster context without switching the current context
  --control-url CONTROL_URL
                        Control API URL to use instead of the current login context
  --token TOKEN         Management token to use with --control-url
  --insecure            Skip TLS verification for the control API
  --resolve-ip RESOLVE_IP
                        Connect to this IP while keeping the control hostname as Host
  --format {text,json,ndjson}
                        Output format
  --quiet               Print only the final result or error

luma workflow#

usage: luma workflow [-h] {list,show,record,run} ...

arguments:
  {list,show,record,run}
    list                List recorded application workflows
    show                Show an application's build/deploy command and notes
    record              Explicitly set a workflow without deploying; put the Luma command after --
    run                 Run the recorded command from a local checkout using current credentials

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

luma workflow list#

usage: luma workflow list [-h] [--control-context CONTROL_CONTEXT] [--control-url CONTROL_URL] [--token TOKEN] [--insecure] [--resolve-ip RESOLVE_IP] [--format {text,json,ndjson}] [--quiet]

arguments:
  -h, --help            show this help message and exit
  --control-context CONTROL_CONTEXT
                        Use a saved cluster context without switching the current context
  --control-url CONTROL_URL
                        Control API URL to use instead of the current login context
  --token TOKEN         Management token to use with --control-url
  --insecure            Skip TLS verification for the control API
  --resolve-ip RESOLVE_IP
                        Connect to this IP while keeping the control hostname as Host
  --format {text,json,ndjson}
                        Output format
  --quiet               Print only the final result or error

luma workflow show#

usage: luma workflow show [-h] [--control-context CONTROL_CONTEXT] [--control-url CONTROL_URL] [--token TOKEN] [--insecure] [--resolve-ip RESOLVE_IP] [--format {text,json,ndjson}] [--quiet] name

arguments:
  name

arguments:
  -h, --help            show this help message and exit
  --control-context CONTROL_CONTEXT
                        Use a saved cluster context without switching the current context
  --control-url CONTROL_URL
                        Control API URL to use instead of the current login context
  --token TOKEN         Management token to use with --control-url
  --insecure            Skip TLS verification for the control API
  --resolve-ip RESOLVE_IP
                        Connect to this IP while keeping the control hostname as Host
  --format {text,json,ndjson}
                        Output format
  --quiet               Print only the final result or error

luma workflow record#

usage: luma workflow record [-h] [--note WORKFLOW_NOTE] [--control-context CONTROL_CONTEXT] [--control-url CONTROL_URL] [--token TOKEN] [--insecure] [--resolve-ip RESOLVE_IP] [--format {text,json,ndjson}] [--quiet] name recipe_command [recipe_command ...]

arguments:
  name
  recipe_command

arguments:
  -h, --help            show this help message and exit
  --note WORKFLOW_NOTE
  --control-context CONTROL_CONTEXT
                        Use a saved cluster context without switching the current context
  --control-url CONTROL_URL
                        Control API URL to use instead of the current login context
  --token TOKEN         Management token to use with --control-url
  --insecure            Skip TLS verification for the control API
  --resolve-ip RESOLVE_IP
                        Connect to this IP while keeping the control hostname as Host
  --format {text,json,ndjson}
                        Output format
  --quiet               Print only the final result or error

luma workflow run#

usage: luma workflow run [-h] [--path PATH] [--workflow-app WORKFLOW_APP] [--accept-workflow-change] [--workflow-note WORKFLOW_NOTE] [--control-context CONTROL_CONTEXT] [--control-url CONTROL_URL] [--token TOKEN] [--insecure] [--resolve-ip RESOLVE_IP] [--format {text,json,ndjson}] [--quiet] name

arguments:
  name

arguments:
  -h, --help            show this help message and exit
  --path PATH           Local project checkout (default: current directory)
  --workflow-app WORKFLOW_APP
                        Application workflow to check (required when a repository matches several
                        applications)
  --accept-workflow-change
                        Continue after the user has explicitly approved the displayed workflow
                        differences
  --workflow-note WORKFLOW_NOTE
                        Record why this build/deploy workflow is used; do not include secrets
  --control-context CONTROL_CONTEXT
                        Use a saved cluster context without switching the current context
  --control-url CONTROL_URL
                        Control API URL to use instead of the current login context
  --token TOKEN         Management token to use with --control-url
  --insecure            Skip TLS verification for the control API
  --resolve-ip RESOLVE_IP
                        Connect to this IP while keeping the control hostname as Host
  --format {text,json,ndjson}
                        Output format
  --quiet               Print only the final result or error

luma rollback#

usage: luma rollback [-h] [--to-version TO_VERSION] [--control-context CONTROL_CONTEXT] [--control-url CONTROL_URL] [--token TOKEN] [--insecure] [--resolve-ip RESOLVE_IP] [--format {text,json,ndjson}] [--quiet] name

arguments:
  name

arguments:
  -h, --help            show this help message and exit
  --to-version TO_VERSION
                        Target version (default: previous)
  --control-context CONTROL_CONTEXT
                        Use a saved cluster context without switching the current context
  --control-url CONTROL_URL
                        Control API URL to use instead of the current login context
  --token TOKEN         Management token to use with --control-url
  --insecure            Skip TLS verification for the control API
  --resolve-ip RESOLVE_IP
                        Connect to this IP while keeping the control hostname as Host
  --format {text,json,ndjson}
                        Output format
  --quiet               Print only the final result or error

luma history#

usage: luma history [-h] [--control-context CONTROL_CONTEXT] [--control-url CONTROL_URL] [--token TOKEN] [--insecure] [--resolve-ip RESOLVE_IP] [--format {text,json,ndjson}] [--quiet] name

arguments:
  name

arguments:
  -h, --help            show this help message and exit
  --control-context CONTROL_CONTEXT
                        Use a saved cluster context without switching the current context
  --control-url CONTROL_URL
                        Control API URL to use instead of the current login context
  --token TOKEN         Management token to use with --control-url
  --insecure            Skip TLS verification for the control API
  --resolve-ip RESOLVE_IP
                        Connect to this IP while keeping the control hostname as Host
  --format {text,json,ndjson}
                        Output format
  --quiet               Print only the final result or error

luma compose#

usage: luma compose [-h] {init,validate,render,deploy} ...

arguments:
  {init,validate,render,deploy}

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

luma compose init#

usage: luma compose init [-h] [--compose COMPOSE] [--output OUTPUT]

arguments:
  -h, --help         show this help message and exit
  --compose COMPOSE
  --output OUTPUT

luma compose validate#

usage: luma compose validate [-h] [--engine {nomad}] [--import-mode] [--control-context CONTROL_CONTEXT] [--control-url CONTROL_URL] [--token TOKEN] [--insecure] [--resolve-ip RESOLVE_IP] [--format {text,json,ndjson}] [--quiet] sidecar

arguments:
  sidecar

arguments:
  -h, --help            show this help message and exit
  --engine {nomad}      Orchestrator to validate for; Nomad is the only supported engine
  --import-mode         Allow Compose services with build: for luma import validation
  --control-context CONTROL_CONTEXT
                        Use a saved cluster context without switching the current context
  --control-url CONTROL_URL
                        Control API URL to use instead of the current login context
  --token TOKEN         Management token to use with --control-url
  --insecure            Skip TLS verification for the control API
  --resolve-ip RESOLVE_IP
                        Connect to this IP while keeping the control hostname as Host
  --format {text,json,ndjson}
                        Output format
  --quiet               Print only the final result or error

luma compose render#

usage: luma compose render [-h] [--engine {nomad}] [--control-context CONTROL_CONTEXT] [--control-url CONTROL_URL] [--token TOKEN] [--insecure] [--resolve-ip RESOLVE_IP] sidecar

arguments:
  sidecar

arguments:
  -h, --help            show this help message and exit
  --engine {nomad}      Orchestrator to render for; Nomad is the only supported engine
  --control-context CONTROL_CONTEXT
                        Use a saved cluster context without switching the current context
  --control-url CONTROL_URL
                        Control API URL to use instead of the current login context
  --token TOKEN         Management token to use with --control-url
  --insecure            Skip TLS verification for the control API
  --resolve-ip RESOLVE_IP
                        Connect to this IP while keeping the control hostname as Host

luma compose deploy#

usage: luma compose deploy [-h] [--workflow-app WORKFLOW_APP] [--accept-workflow-change] [--workflow-note WORKFLOW_NOTE] [--engine {nomad}] [--control-context CONTROL_CONTEXT] [--control-url CONTROL_URL] [--token TOKEN] [--insecure] [--resolve-ip RESOLVE_IP] [--format {text,json,ndjson}] [--quiet] [--dry-run] [--skip-dns] [--skip-orchestrator] [--env DEPLOY_ENV_FILE] [--timeout TIMEOUT] sidecar

arguments:
  sidecar

arguments:
  -h, --help            show this help message and exit
  --workflow-app WORKFLOW_APP
                        Application workflow to check (required when a repository matches several
                        applications)
  --accept-workflow-change
                        Continue after the user has explicitly approved the displayed workflow
                        differences
  --workflow-note WORKFLOW_NOTE
                        Record why this build/deploy workflow is used; do not include secrets
  --engine {nomad}      Orchestrator for local dry-run preview; live deploy follows the control-
                        plane config
  --control-context CONTROL_CONTEXT
                        Use a saved cluster context without switching the current context
  --control-url CONTROL_URL
                        Control API URL to use instead of the current login context
  --token TOKEN         Management token to use with --control-url
  --insecure            Skip TLS verification for the control API
  --resolve-ip RESOLVE_IP
                        Connect to this IP while keeping the control hostname as Host
  --format {text,json,ndjson}
                        Output format
  --quiet               Print only the final result or error
  --dry-run
  --skip-dns
  --skip-orchestrator
  --env DEPLOY_ENV_FILE
                        Use this .env file as scoped deployment secrets for this Compose application
  --timeout TIMEOUT

luma storage#

usage: luma storage [-h] {list,set,remove,apply,check,migrate} ...

arguments:
  {list,set,remove,apply,check,migrate}

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

luma storage list#

usage: luma storage list [-h] [--control-context CONTROL_CONTEXT] [--control-url CONTROL_URL] [--token TOKEN] [--insecure] [--resolve-ip RESOLVE_IP] [--format {text,json,ndjson}] [--quiet]

arguments:
  -h, --help            show this help message and exit
  --control-context CONTROL_CONTEXT
                        Use a saved cluster context without switching the current context
  --control-url CONTROL_URL
                        Control API URL to use instead of the current login context
  --token TOKEN         Management token to use with --control-url
  --insecure            Skip TLS verification for the control API
  --resolve-ip RESOLVE_IP
                        Connect to this IP while keeping the control hostname as Host
  --format {text,json,ndjson}
                        Output format
  --quiet               Print only the final result or error

luma storage set#

usage: luma storage set [-h] [--provider {nfs}] [--external] [--node NODE] [--path PATH] [--endpoint ENDPOINT] [--mount-options MOUNT_OPTIONS] [--region REGIONS] [--eligible-node NODES] [--timeout TIMEOUT] [--control-context CONTROL_CONTEXT] [--control-url CONTROL_URL] [--token TOKEN] [--insecure] [--resolve-ip RESOLVE_IP] name

arguments:
  name

arguments:
  -h, --help            show this help message and exit
  --provider {nfs}
  --external
  --node NODE
  --path PATH
  --endpoint ENDPOINT
  --mount-options MOUNT_OPTIONS
                        NFS mount options; defaults to
                        nfsvers=4,rw,soft,timeo=100,retrans=10,noresvport
  --region REGIONS
  --eligible-node NODES
  --timeout TIMEOUT     Wait for managed storage host preparation (default: 360s)
  --control-context CONTROL_CONTEXT
                        Use a saved cluster context without switching the current context
  --control-url CONTROL_URL
                        Control API URL to use instead of the current login context
  --token TOKEN         Management token to use with --control-url
  --insecure            Skip TLS verification for the control API
  --resolve-ip RESOLVE_IP
                        Connect to this IP while keeping the control hostname as Host

luma storage remove#

usage: luma storage remove [-h] [--timeout TIMEOUT] [--control-context CONTROL_CONTEXT] [--control-url CONTROL_URL] [--token TOKEN] [--insecure] [--resolve-ip RESOLVE_IP] name

arguments:
  name

arguments:
  -h, --help            show this help message and exit
  --timeout TIMEOUT     Wait for managed storage host cleanup (default: 360s)
  --control-context CONTROL_CONTEXT
                        Use a saved cluster context without switching the current context
  --control-url CONTROL_URL
                        Control API URL to use instead of the current login context
  --token TOKEN         Management token to use with --control-url
  --insecure            Skip TLS verification for the control API
  --resolve-ip RESOLVE_IP
                        Connect to this IP while keeping the control hostname as Host

luma storage apply#

usage: luma storage apply [-h] [--control-context CONTROL_CONTEXT] [--control-url CONTROL_URL] [--token TOKEN] [--insecure] [--resolve-ip RESOLVE_IP] [--dry-run] [--timeout TIMEOUT] sidecar

arguments:
  sidecar

arguments:
  -h, --help            show this help message and exit
  --control-context CONTROL_CONTEXT
                        Use a saved cluster context without switching the current context
  --control-url CONTROL_URL
                        Control API URL to use instead of the current login context
  --token TOKEN         Management token to use with --control-url
  --insecure            Skip TLS verification for the control API
  --resolve-ip RESOLVE_IP
                        Connect to this IP while keeping the control hostname as Host
  --dry-run
  --timeout TIMEOUT

luma storage check#

usage: luma storage check [-h] [--control-context CONTROL_CONTEXT] [--control-url CONTROL_URL] [--token TOKEN] [--insecure] [--resolve-ip RESOLVE_IP] [--format {text,json,ndjson}] [--quiet] sidecar

arguments:
  sidecar

arguments:
  -h, --help            show this help message and exit
  --control-context CONTROL_CONTEXT
                        Use a saved cluster context without switching the current context
  --control-url CONTROL_URL
                        Control API URL to use instead of the current login context
  --token TOKEN         Management token to use with --control-url
  --insecure            Skip TLS verification for the control API
  --resolve-ip RESOLVE_IP
                        Connect to this IP while keeping the control hostname as Host
  --format {text,json,ndjson}
                        Output format
  --quiet               Print only the final result or error

luma storage migrate#

usage: luma storage migrate [-h] --volume VOLUME --from-node FROM_NODE --from-volume FROM_VOLUME [--control-context CONTROL_CONTEXT] [--control-url CONTROL_URL] [--token TOKEN] [--insecure] [--resolve-ip RESOLVE_IP] [--format {text,json,ndjson}] [--quiet] sidecar

arguments:
  sidecar

arguments:
  -h, --help            show this help message and exit
  --volume VOLUME
  --from-node FROM_NODE
  --from-volume FROM_VOLUME
  --control-context CONTROL_CONTEXT
                        Use a saved cluster context without switching the current context
  --control-url CONTROL_URL
                        Control API URL to use instead of the current login context
  --token TOKEN         Management token to use with --control-url
  --insecure            Skip TLS verification for the control API
  --resolve-ip RESOLVE_IP
                        Connect to this IP while keeping the control hostname as Host
  --format {text,json,ndjson}
                        Output format
  --quiet               Print only the final result or error