` | Sets a custom title for the static page (deprecated: use --config-file). | | `--output-path <output-path>` | Sets the output path for the generated static page. | | `--description <description>` | Page description for SEO. | | `--keywords <keywords>` | Comma-separated keywords for SEO. | | `--author <author>` | Page author. | | `--theme-color <color>` | Theme color for mobile browsers. | | `--canonical-url <url>` | Canonical URL for SEO. | | `--thumbnail <url>` | Open Graph thumbnail image URL. | | `--locale <locale>` | Page locale (default: en-US). | | `--site-name <name>` | Site name for Open Graph. | | `--head-scripts <paths>` | Comma-separated paths to scripts for head section. | | `--body-scripts <paths>` | Comma-separated paths to scripts for body section. | | `--styles <paths>` | Comma-separated paths to stylesheets. | | `--favicon <path>` | Favicon path. | | `--apple-touch-icon <path>` | Apple touch icon path. | | `--manifest <path>` | Web manifest path. | | `--head-components <paths>` | Comma-separated SSR head component paths. | | `--body-components <paths>` | Comma-separated SSR body component paths. | | `--build-path <build-path>` | Sets a custom build path for static documents or assets. | | `--env <env>` | Sets the environment for the static build (e.g., "development", "production"). | | `--minify` | Minify HTML output (default: true for production). | | `--no-minify` | Disable HTML minification. | | `--config-file <path>` | Path to JSON configuration file. | | `--generate-config [path]` | Generate a template configuration file. | | `--lang <lang>` | HTML lang attribute (default: en). | | `--dir <dir>` | HTML dir attribute (default: ltr). | | `--dev` | Sets the development cli context | | `--run-sv [port]` | Start a standalone Express static server to preview the static build (default port: 5000). | | `-h, --help` | display help for command | --- ### underpost config Manages Underpost configurations using various operators. **Usage:** `underpost config [options] <operator> [key] [value]` #### Arguments | Argument | Description | | --- | --- | | `operator` | The configuration operation to perform. Options: set, delete, get, list, clean, isInsideContainer. | | `key` | Optional: The specific configuration key to manage. | | `value` | Optional: The value to set for the configuration key. | #### Options | Option | Description | | --- | --- | | `--plain` | Prints the configuration value in plain text. | | `--filter <keyword>` | Filters the list by matching key or value (only for list operation). | | `--deploy-id <deploy-id>` | Sets the deployment configuration ID for the operation context. | | `--build` | Sets the build context for the operation. | | `--copy` | Copies the configuration value to the clipboard (only for get operation). | | `-h, --help` | display help for command | --- ### underpost root Displays the root path of the npm installation. **Usage:** `underpost root [options]` #### Options | Option | Description | | --- | --- | | `-h, --help` | display help for command | --- ### underpost ip Displays the current public machine IP addresses. **Usage:** `underpost ip [options] [ips]` #### Arguments | Argument | Description | | --- | --- | | `ips` | Optional args comma-separated list of IP to process. | #### Options | Option | Description | | --- | --- | | `--dhcp` | Fetches and displays the current Dynamic Host Configuration Protocol server IP address. | | `--copy` | Copies the IP addresses to the clipboard. | | `--ban-ingress-add` | Adds IP addresses to banned ingress list. | | `--ban-ingress-remove` | Removes IP addresses from banned ingress list. | | `--ban-ingress-list` | Lists all banned ingress IP addresses. | | `--ban-ingress-clear` | Clears all banned ingress IP addresses. | | `--ban-egress-add` | Adds IP addresses to banned egress list. | | `--ban-egress-remove` | Removes IP addresses from banned egress list. | | `--ban-egress-list` | Lists all banned egress IP addresses. | | `--ban-egress-clear` | Clears all banned egress IP addresses. | | `--ban-both-add` | Adds IP addresses to both banned ingress and egress lists. | | `--ban-both-remove` | Removes IP addresses from both banned ingress and egress lists. | | `--mac` | Prints the MAC address of the main network interface. | | `-h, --help` | display help for command | --- ### underpost cluster Manages Kubernetes clusters, defaulting to Kind cluster initialization. **Usage:** `underpost cluster [options] [pod-name]` #### Arguments | Argument | Description | | --- | --- | | `pod-name` | Optional: Filters information by a specific pod name. | #### Options | Option | Description | | --- | --- | | `--reset` | Deletes all clusters and prunes all related data and caches. | | `--reset-mongodb` | Performs a hard cleanup of only MongoDB-related resources (StatefulSet, PVCs/PVs, Secrets, ConfigMaps, caches) without restarting the whole node. | | `--mariadb` | Initializes the cluster with a MariaDB statefulset. | | `--mysql` | Initializes the cluster with a MySQL statefulset. | | `--mongodb` | Initializes the cluster with a MongoDB statefulset. | | `--service-host <host>` | Set custom host/IP for exposed MongoDB and Valkey clients. | | `--postgresql` | Initializes the cluster with a PostgreSQL statefulset. | | `--mongodb4` | Initializes the cluster with a MongoDB 4.4 service. | | `--valkey` | Initializes the cluster with a Valkey service. | | `--ipfs` | Initializes the cluster with an ipfs-cluster statefulset. | | `--contour` | Initializes the cluster with Project Contour base HTTPProxy and Envoy. | | `--node-port` | Exposes enabled ready services (e.g. MongoDB 4.4, Valkey) to the host/public network via their NodePort Service manifest. | | `--node-selector <k8s-node-name>` | Pins the just-deployed StatefulSet (MongoDB 4.4 / Valkey) to the given Kubernetes node once it is ready (via a kubernetes.io/hostname nodeSelector). | | `--cert-manager` | Initializes the cluster with a Let's Encrypt production ClusterIssuer. | | `--dedicated-gpu` | Initializes the cluster with dedicated GPU base resources and environment settings. | | `--ns-use <ns-name>` | Switches the current Kubernetes context to the specified namespace (creates if it doesn't exist). | | `--kubeadm` | Initializes the cluster using kubeadm for control plane management. | | `--pod-network-cidr <cidr>` | Sets custom pod network CIDR for kubeadm cluster initialization (defaults to "192.168.0.0/16"). | | `--control-plane-endpoint <endpoint>` | Sets custom control plane endpoint for kubeadm cluster initialization (defaults to "localhost:6443"). | | `--grafana` | Initializes the cluster with a Grafana deployment. | | `--prom [hosts]` | Initializes the cluster with a Prometheus Operator deployment and monitor scrap for specified hosts. | | `--dev` | Initializes a development-specific cluster configuration. | | `--list-pods` | Displays detailed information about all pods. | | `--pull-image` | Sets an optional associated image to pull during initialization. | | `--init-host` | Installs necessary Kubernetes node CLI tools (e.g., kind, kubeadm, docker, podman, helm). | | `--uninstall-host` | Uninstalls all host components installed by init-host. | | `--config` | Sets the base Kubernetes node configuration. | | `--chown` | Sets the appropriate ownership for Kubernetes kubeconfig files. | | `--k3s` | Initializes the cluster using K3s (Lightweight Kubernetes). | | `--hosts <hosts>` | A comma-separated list of cluster hostnames or IP addresses. | | `--remove-volume-host-paths` | Removes specified volume host paths after execution. | | `--reset-mode <mode>` | Reset mode for --reset --k3s: "drain" (stop services, keep K3s installed) or "full" (uninstall + cleanup). Default: "full". | | `--namespace <namespace>` | Kubernetes namespace for cluster operations (defaults to "default"). | | `--replicas <replicas>` | Sets a custom number of replicas for statefulset deployments. | | `-h, --help` | display help for command | --- ### underpost deploy Manages application deployments, defaulting to deploying development pods. **Usage:** `underpost deploy [options] [deploy-list] [env]` #### Arguments | Argument | Description | | --- | --- | | `deploy-list` | A comma-separated list of deployment IDs (e.g., "default-a,default-b"). | | `env` | Optional: The environment for deployment (e.g., "development", "production"). Defaults to "development". | #### Options | Option | Description | | --- | --- | | `--remove` | Deletes specified deployments and their associated services. | | `--sync` | Synchronizes deployment environment variables, ports, and replica counts. | | `--info-router` | Displays the current router structure and configuration. | | `--expose` | Exposes services matching the provided deployment ID list. | | `--cert` | Resets TLS/SSL certificate secrets for deployments. | | `--cert-hosts <hosts>` | Resets TLS/SSL certificate secrets for specified hosts. | | `--self-signed` | Use a pre-created self-signed TLS secret (kubernetes.io/tls) instead of cert-manager. The secret must already exist in the namespace with the same name as the host. Enables TLS in the Contour HTTPProxy virtualhost without requiring a production ClusterIssuer. | | `--node <node>` | Sets optional node for deployment operations. | | `--ssh-key-path <path>` | Private key path for node SSH operations. Currently used when shipping a hostPath volume to a remote target node over SSH. Defaults to engine-private/deploy/id_rsa. | | `--build-manifest` | Builds Kubernetes YAML manifests, including deployments, services, proxies, and secrets. | | `--replicas <replicas>` | Sets a custom number of replicas for deployments. | | `--image <image>` | Sets a custom image for deployments. | | `--versions <deployment-versions>` | A comma-separated list of custom deployment versions. | | `--traffic <traffic-versions>` | A comma-separated list of custom deployment traffic weights. | | `--timeout-response <duration>` | Sets HTTPProxy per-route response timeout (e.g., "1s", "300ms", "infinity"). | | `--timeout-idle <duration>` | Sets HTTPProxy per-route idle timeout (e.g., "10s", "infinity"). | | `--retry-count <count>` | Sets HTTPProxy per-route retry count (e.g., 3). | | `--retry-per-try-timeout <duration>` | Sets HTTPProxy retry per-try timeout (e.g., "150ms"). | | `--disable-update-deployment` | Disables updates to deployments. | | `--disable-runtime-probes` | Omits the internal-status HTTP probes from generated deployment manifests. | | `--tcp-probes` | Generates legacy TCP socket probes instead of HTTP internal-status probes (migration). | | `--disable-update-proxy` | Disables updates to proxies. | | `--disable-deployment-proxy` | Disables proxies of deployments. | | `--disable-update-volume` | Disables updates to volume mounts during deployment. | | `--status` | Retrieves current network traffic data from resource deployments and the host machine network configuration. | | `--kubeadm` | Enables the kubeadm context for deployment operations. | | `--k3s` | Enables the k3s context for deployment operations. | | `--kind` | Enables the kind context for deployment operations. | | `--git-clean` | Runs git clean on volume mount paths before copying. | | `--disable-update-underpost-config` | Disables updates to Underpost configuration during deployment. | | `--namespace <namespace>` | Kubernetes namespace for deployment operations (defaults to "default"). | | `--kind-type <kind-type>` | Specifies the Kind cluster type for deployment operations. | | `--port <port>` | Sets up port forwarding from local to remote ports. | | `--expose-port <port>` | Sets the local:remote port to expose when --expose is active (overrides auto-detected service port). | | `--expose-local-port <port>` | Sets a different local port for --expose (e.g. 80) while keeping the remote service port. Useful for /etc/hosts local access without specifying a port in the browser. | | `--local-proxy` | Forward all service TCP ports locally and start the Node.js path-routing proxy. Enables full path-based routing (e.g. /wp alongside /) without needing --expose-local-port. Requires --expose. | | `--cmd <cmd>` | Custom initialization command for deployment (comma-separated commands). | | `--skip-full-build` | Skip client bundle rebuild; container will pull pre-built bundle via pull-bundle instead. | | `--pull-bundle` | Explicitly pull the pre-built client bundle from Cloudinary inside the container. Use together with --skip-full-build. | | `--image-pull-policy <policy>` | Override container imagePullPolicy in the generated deployment manifest (Always, IfNotPresent, Never). Defaults to Never for localhost/ images and IfNotPresent otherwise. | | `--tls` | Enables TLS for the local proxy started by --expose --local-proxy. The proxy will serve HTTPS on port 443 using self-signed certificates resolved from the local SSL store. Use together with --expose and --local-proxy. | | `-h, --help` | display help for command | --- ### underpost secret Manages secrets for various platforms. **Usage:** `underpost secret [options] <platform>` #### Arguments | Argument | Description | | --- | --- | | `platform` | The secret management platform. Options: underpost, globalSecretClean. | #### Options | Option | Description | | --- | --- | | `--init` | Initializes the secrets platform environment. | | `--create-from-file <path-env-file>` | Creates secrets from a specified environment file. | | `--create-from-env` | Creates secrets from container environment variables (envFrom: secretRef). | | `--global-clean` | Removes all filesystem traces of secrets (engine-private, .env, conf cache). | | `--list` | Lists all available secrets for the platform. | | `-h, --help` | display help for command | --- ### underpost image Manages Docker images, including building, saving, and loading into Kubernetes clusters. **Usage:** `underpost image [options]` #### Options | Option | Description | | --- | --- | | `--build` | Builds a Docker image using Podman, optionally saves it as a tar archive, and loads it into a specified Kubernetes cluster (Kind, Kubeadm, or K3s). | | `--ls` | Lists all available Underpost Dockerfile images. | | `--rm <image-id>` | Removes specified Underpost Dockerfile images. | | `--path [path]` | The path to the Dockerfile directory. | | `--image-name [image-name]` | Sets a custom name for the Docker image. | | `--image-path [image-path]` | Sets the output path for the tar image archive. | | `--dockerfile-name [dockerfile-name]` | Sets a custom name for the Dockerfile. | | `--podman-save` | Exports the built image as a tar file using Podman. | | `--pull-base` | Pulls base images and builds a "rockylinux9-underpost" image. | | `--spec` | Get current cached list of container images used by all pods | | `--namespace <namespace>` | Kubernetes namespace for image operations (defaults to "default"). | | `--kind` | Set kind cluster env image context management. | | `--kubeadm` | Set kubeadm cluster env image context management. | | `--k3s` | Set k3s cluster env image context management. | | `--node-name` | Set node name for kubeadm or k3s cluster env image context management. | | `--reset` | Performs a build without using the cache. | | `--dev` | Use development mode. | | `--pull-dockerhub <dockerhub-image>` | Sets a custom Docker Hub image for base image pulls. | | `-h, --help` | display help for command | --- ### underpost install Quickly imports Underpost npm dependencies by copying them. **Usage:** `underpost install [options]` #### Options | Option | Description | | --- | --- | | `-h, --help` | display help for command | --- ### underpost db Manages database operations with support for MariaDB and MongoDB, including import/export, multi-pod targeting, and Git integration. **Usage:** `underpost db [options] [deploy-list]` #### Arguments | Argument | Description | | --- | --- | | `deploy-list` | A comma-separated list of deployment IDs (e.g., "default-a,default-b"). | #### Options | Option | Description | | --- | --- | | `--import` | Imports container backups from specified repositories. | | `--export` | Exports container backups to specified repositories. | | `--pod-name <pod-name>` | Comma-separated list of pod names or patterns (supports wildcards like "mariadb-*"). | | `--all-pods` | Target all matching pods instead of just the first one. | | `--primary-pod` | Automatically detect and use MongoDB primary pod (MongoDB only). | | `--primary-pod-ensure <pod-name>` | Ensure setup of MongoDB replica set primary pod before operations. | | `--stats` | Display database statistics (collection/table names with document/row counts). | | `--collections <collections>` | Comma-separated list of database collections to operate on. | | `--out-path <out-path>` | Specifies a custom output path for backups. | | `--drop` | Drops the specified databases or collections before importing. | | `--preserveUUID` | Preserves UUIDs during database import operations. | | `--git` | Enables Git integration for backup version control (clone, pull, commit, push to GitHub). | | `--force-clone` | Forces cloning of the Git repository, overwriting local changes. | | `--hosts <hosts>` | Comma-separated list of database hosts to filter operations. | | `--paths <paths>` | Comma-separated list of paths to filter database operations. | | `--ns <ns-name>` | Kubernetes namespace context for database operations (defaults to "default"). | | `--macro-rollback-export <n-commits-reset>` | Exports a macro rollback script that reverts the last n commits (Git integration required). | | `--clean-fs-collection` | Cleans orphaned File documents from collections that are not referenced by any models. | | `--clean-fs-dry-run` | Dry run mode - shows what would be deleted without actually deleting (use with --clean-fs-collection). | | `--dev` | Sets the development cli context | | `--kubeadm` | Enables the kubeadm context for database operations. | | `--kind` | Enables the kind context for database operations. | | `--k3s` | Enables the k3s context for database operations. | | `--repo-backup` | Backs up repositories (git commit+push) inside deployment pods via kubectl exec. | | `-h, --help` | display help for command | --- ### underpost metadata Manages cluster metadata operations, including import and export. **Usage:** `underpost metadata [options] [deploy-id] [host] [path]` #### Arguments | Argument | Description | | --- | --- | | `deploy-id` | The deployment ID to manage metadata. | | `host` | The host to manage metadata. | | `path` | The path to manage metadata. | #### Options | Option | Description | | --- | --- | | `--import` | Imports from local storage. | | `--export` | Exports to local storage. | | `--crons` | Apply to cron data collection | | `--instances` | Apply to instance data collection | | `--generate` | Generate cluster metadata | | `--itc` | Apply under container execution context | | `--dev` | Sets the development cli context | | `-h, --help` | display help for command | --- ### underpost cron Manages cron jobs: execute jobs directly or generate and apply K8s CronJob manifests. **Usage:** `underpost cron [options] [deploy-list] [job-list]` #### Arguments | Argument | Description | | --- | --- | | `deploy-list` | A comma-separated list of deployment IDs (e.g., "default-a,default-b"). | | `job-list` | A comma-separated list of job IDs. Options: dns,backup. Defaults to all available jobs. | #### Options | Option | Description | | --- | --- | | `--generate-k8s-cronjobs` | Generates Kubernetes CronJob YAML manifests from cron configuration. | | `--apply` | Applies generated K8s CronJob manifests to the cluster via kubectl. | | `--setup-start [deploy-id]` | Updates deploy-id package.json start script and generates+applies its K8s CronJob manifests. | | `--namespace <namespace>` | Kubernetes namespace for the CronJob resources (default: "default"). | | `--image <image>` | Custom container image for the CronJob pods. | | `--git` | Pass --git flag to cron job execution. | | `--cmd <cmd>` | Optional pre-script commands to run before cron execution. | | `--dev` | Use local ./ base path instead of global underpost installation. | | `--k3s` | Use k3s cluster context (apply directly on host). | | `--kind` | Use kind cluster context (apply via kind-worker container). | | `--kubeadm` | Use kubeadm cluster context (apply directly on host). | | `--dry-run` | Preview cron jobs without executing them. | | `--create-job-now` | After applying manifests, immediately create a Job from each CronJob (requires --apply). | | `-h, --help` | display help for command | --- ### underpost fs Manages file storage, defaulting to file upload operations. **Usage:** `underpost fs [options] [path]` #### Arguments | Argument | Description | | --- | --- | | `path` | The absolute or relative directory path for file operations. | #### Options | Option | Description | | --- | --- | | `--rm` | Removes the specified file. | | `--git` | Displays current Git changes related to file storage. | | `--recursive` | Uploads files recursively from the specified path. | | `--deploy-id <deploy-id>` | Specifies the deployment configuration ID for file operations. | | `--pull` | Downloads the specified file. | | `--omit-unzip` | With --pull, keeps the downloaded .zip file and skips extraction. | | `--force` | Forces the action, overriding any warnings or conflicts. | | `--storage-file-path <storage-file-path>` | Specifies a custom file storage path. | | `-h, --help` | display help for command | --- ### underpost test Manages and runs tests, defaulting to the current Underpost default test suite. **Usage:** `underpost test [options] [deploy-list]` #### Arguments | Argument | Description | | --- | --- | | `deploy-list` | A comma-separated list of deployment IDs (e.g., "default-a,default-b"). | #### Options | Option | Description | | --- | --- | | `--itc` | Executes tests within the container execution context. | | `--sh` | Copies the container entrypoint shell command to the clipboard. | | `--logs` | Displays container logs for test debugging. | | `--pod-name <pod-name>` | Optional: Specifies the pod name for test execution. | | `--pod-status <pod-status>` | Optional: Filters tests by pod status. | | `--kind-type <kind-type>` | Optional: Specifies the Kind cluster type for tests. | | `-h, --help` | display help for command | --- ### underpost monitor Manages health server monitoring for specified deployments. **Usage:** `underpost monitor [options] <deploy-id> [env]` #### Arguments | Argument | Description | | --- | --- | | `deploy-id` | The deployment configuration ID to monitor. | | `env` | Optional: The environment to monitor (e.g., "development", "production"). Defaults to "development". | #### Options | Option | Description | | --- | --- | | `--ms-interval <ms-interval>` | Sets a custom millisecond interval for monitoring checks. | | `--now` | Executes the monitor script immediately. | | `--single` | Disables recurrence, running the monitor script only once. | | `--replicas <replicas>` | Sets a custom number of replicas for monitoring. Defaults to 1. | | `--type <type>` | Sets a custom monitor type. | | `--sync` | Synchronizes with current proxy deployments and traffic configurations. | | `--namespace <namespace>` | Sets the Kubernetes namespace for the deployment. Defaults to "default". | | `--timeout-response <duration>` | Sets HTTPProxy per-route response timeout (e.g., "5s"). | | `--timeout-idle <duration>` | Sets HTTPProxy per-route idle timeout (e.g., "10s", "infinity"). | | `--retry-count <count>` | Sets HTTPProxy per-route retry count (e.g., 3). | | `--retry-per-try-timeout <duration>` | Sets HTTPProxy retry per-try timeout (e.g., "150ms"). | | `--disable-private-conf-update` | Disables updates to private configuration during execution. | | `--versions <deployment-versions>` | Specifies the deployment versions to monitor. eg. "blue,green", "green" | | `--ready-deployment` | Run in ready deployment monitor mode. | | `--promote` | Promotes the deployment after monitoring. | | `-h, --help` | display help for command | --- ### underpost ssh Manages SSH credentials and sessions for remote access to cluster nodes or services. **Usage:** `underpost ssh [options]` #### Options | Option | Description | | --- | --- | | `--deploy-id <deploy-id>` | Sets deploy id context for ssh operations. | | `--generate` | Generates new ssh credential and stores it in current private keys file storage. | | `--user <user>` | Sets custom ssh user | | `--password <password>` | Sets custom ssh password | | `--host <host>` | Sets custom ssh host | | `--port <port>` | Sets custom ssh port | | `--filter <filter>` | Filters ssh user credentials from current private keys file storage. | | `--groups <groups>` | Sets comma-separated ssh user groups for the ssh user credential. | | `--user-add` | Adds a new ssh user credential to current private keys file storage. | | `--user-remove` | Removes an existing ssh user credential from current private keys file storage. | | `--user-ls` | Lists all ssh user credentials from current private keys file storage. | | `--start` | Starts an SSH session with the specified credentials. | | `--reset` | Resets ssh configuration and deletes all stored credentials. | | `--keys-list` | Lists all ssh keys from current private keys file storage. | | `--hosts-list` | Lists all ssh hosts from current private keys file storage. | | `--disable-password` | Disables password authentication for the SSH session. | | `--key-test` | Tests the SSH key using ssh-keygen. | | `--stop` | Stops the SSH service. | | `--status` | Checks the status of the SSH service. | | `--connect-uri` | Displays the connection URI. | | `--copy` | Copies the connection URI to clipboard. | | `-h, --help` | display help for command | --- ### underpost run Runs specified scripts using various runners. **Usage:** `underpost run [options] <runner-id> [path]` #### Arguments | Argument | Description | | --- | --- | | `runner-id` | The runner ID to run. Options: dev-cluster,etc-hosts,ipfs-expose,metadata,svc-ls,svc-rm,ssh-deploy-info,node-move,dev-hosts-expose,dev-hosts-restore,cluster-build,template-deploy,template-deploy-local,docker-image,clean,pull,release-deploy,ssh-deploy,ide,crypto-policy,sync,stop,ssh-deploy-stop,ssh-deploy-db-rollback,ssh-deploy-db,ssh-deploy-db-status,tz,get-proxy,instance-promote,instance,instance-build-manifest,ls-deployments,host-update,install-crio,dd-container,ip-info,db-client,git-conf,promote,metrics,cluster,deploy,disk-clean,disk-devices,disk-usage,dev,service,sh,log,ps,pid-info,background,ports,deploy-test,tf-vae-test,spark-template,pull-rocky-image,rmi,kill,generate-pass,secret,underpost-config,gpu-env,tf-gpu-test,deploy-job,push-bundle,pull-bundle,build-cluster-deployment-manifests,monitor-ui,shared-dir,shared-dir-add-user. | | `path` | The input value, identifier, or path for the operation. | #### Options | Option | Description | | --- | --- | | `--cmd <command-list>` | Comma-separated list of commands to execute. | | `--args <args-array>` | Array of arguments to pass to the command. | | `--dev` | Sets the development context environment for the script. | | `--build` | Set builder context runner | | `--replicas <replicas>` | Sets a custom number of replicas for deployment. | | `--pod-name <pod-name>` | Optional: Specifies the pod name for execution. | | `--node-name <node-name>` | Optional: Specifies the node name for execution. | | `--ssh-key-path <path>` | Optional: Private key path for node SSH operations, forwarded to volume shipping over SSH. Defaults to engine-private/deploy/id_rsa. | | `--port <port>` | Optional: Specifies the port for execution. | | `--etc-hosts` | Enables etc-hosts context for the runner execution. | | `--volume-host-path <volume-host-path>` | Optional: Specifies the volume host path for test execution. | | `--volume-mount-path <volume-mount-path>` | Optional: Specifies the volume mount path for test execution. | | `--volume-type <volume-type>` | Optional: Specifies the volume type for test execution. | | `--image-name <image-name>` | Optional: Specifies the image name for test execution. | | `--container-name <container-name>` | Optional: Specifies the container name for test execution. | | `--namespace <namespace>` | Optional: Specifies the namespace for test execution. | | `--tty` | Enables TTY for the container in deploy-job. | | `--stdin` | Keeps STDIN open for the container in deploy-job. | | `--restart-policy <policy>` | Sets the restart policy for the job in deploy-job. | | `--runtime-class-name <name>` | Sets the runtime class name for the job in deploy-job. | | `--image-pull-policy <policy>` | Sets the image pull policy for the job in deploy-job. | | `--api-version <version>` | Sets the API version for the job manifest in deploy-job. | | `--labels <labels>` | Optional: Specifies a comma-separated list of key-value pairs for labels (e.g., "app=my-app,env=prod"). | | `--claim-name <name>` | Optional: Specifies the claim name for volume mounting in deploy-job. | | `--kind-type <kind-type>` | Specifies the kind of Kubernetes resource (e.g., Job, Deployment) for deploy-job. | | `--force` | Forces operation, overriding any warnings or conflicts. | | `--tls` | Enables TLS for the runner execution. | | `--reset` | Resets the runner state before execution. | | `--dev-proxy-port-offset <port-offset>` | Sets a custom port offset for development proxy. | | `--host-network` | Enables host network mode for the runner execution. | | `--requests-memory <requests-memory>` | Requests memory limit for the runner execution. | | `--requests-cpu <requests-cpu>` | Requests CPU limit for the runner execution. | | `--limits-memory <limits-memory>` | Sets memory limit for the runner execution. | | `--limits-cpu <limits-cpu>` | Sets CPU limit for the runner execution. | | `--resource-template-id <resource-template-id >` | Specifies a resource template ID for the runner execution. | | `--expose` | Enables service exposure for the runner execution. | | `--conf-server-path <conf-server-path>` | Sets a custom configuration server path. | | `--underpost-root <underpost-root>` | Sets a custom Underpost root path. | | `--cmd-cron-jobs <cmd-cron-jobs>` | Pre-script commands to run before cron job execution. | | `--deploy-id-cron-jobs <deploy-id-cron-jobs>` | Specifies deployment IDs to synchronize cron jobs with during execution. | | `--timezone <timezone>` | Sets the timezone for the runner execution. | | `--kubeadm` | Sets the kubeadm cluster context for the runner execution. | | `--k3s` | Sets the k3s cluster context for the runner execution. | | `--kind` | Sets the kind cluster context for the runner execution. | | `--git-clean` | Runs git clean on volume mount paths before copying. | | `--deploy-id <deploy-id>` | Sets deploy id context for the runner execution. | | `--user <user>` | Sets user context for the runner execution. | | `--hosts <hosts>` | Comma-separated list of hosts for the runner execution. | | `--instance-id <instance-id>` | Sets instance id context for the runner execution. | | `--pid <process-id>` | Sets process id context for the runner execution. | | `--timeout-response <duration>` | Sets HTTPProxy per-route response timeout (e.g., "1s", "300ms", "infinity"). | | `--timeout-idle <duration>` | Sets HTTPProxy per-route idle timeout (e.g., "10s", "infinity"). | | `--retry-count <count>` | Sets HTTPProxy per-route retry count (e.g., 3). | | `--retry-per-try-timeout <duration>` | Sets HTTPProxy retry per-try timeout (e.g., "150ms"). | | `--disable-private-conf-update` | Disables updates to private configuration during execution. | | `--logs` | Streams logs during the runner execution. | | `--monitor-status <status>` | Sets the status to monitor for pod/resource (default: "Running"). | | `--monitor-status-kind-type <kind-type>` | Sets the Kubernetes resource kind type to monitor (default: "pods"). | | `--monitor-status-delta-ms <milliseconds>` | Sets the polling interval in milliseconds for status monitoring (default: 1000). | | `--monitor-status-max-attempts <attempts>` | Sets the maximum number of status check attempts (default: 600). | | `--dry-run` | Preview operations without executing them. | | `--from-n-commit <n>` | Number of commits back to use for message propagation in template-deploy (default: 1, last commit only). | | `--create-job-now` | After applying cron manifests, immediately create a Job from each CronJob (forwarded to cron runner). | | `--host-aliases <host-aliases>` | Adds entries to the Pod /etc/hosts via hostAliases. Format: semicolon-separated entries of "ip=hostname1,hostname2" (e.g., "127.0.0.1=foo.local,bar.local;10.1.2.3=foo.remote,bar.remote"). | | `--copy` | Copies the runner output to the clipboard (supported by: generate-pass, template-deploy-local). | | `--skip-full-build` | Skip client bundle rebuild; triggers pull-bundle in container startup (supported by: sync, template-deploy). | | `--pull-bundle` | Explicitly download the pre-built client bundle from Cloudinary inside the container (supported by: sync, template-deploy). Use together with --skip-full-build. | | `--remove` | Remove/teardown resources | | `--test` | Enables test/generic-purpose mode for the runner (e.g. use self-signed TLS instead of cert-manager). | | `-h, --help` | display help for command | --- ### underpost docker-compose General-purpose Docker Compose development pipeline (mirrors the Kubernetes dev stack). **Usage:** `underpost docker-compose [options] [target]` #### Arguments | Argument | Description | | --- | --- | | `target` | Optional service name for --logs, --shell, --restart, or --build. | #### Options | Option | Description | | --- | --- | | `--install` | Install Docker Engine and the Compose v2 plugin on RHEL/Rocky hosts. | | `--reset` | Comprehensive teardown (equivalent to cluster --reset): removes all stack containers, the network, named volumes (destroys data), orphans, and generated artifacts. | | `--force` | Force reinstall (--install), remove volumes (--down), or also drop the env-file (--reset). | | `--deploy-id <deploy-id>` | Deployment to run as the app container (default: dd-default). 'dd-default' self-bootstraps a fresh engine; any other id runs the standard 'underpost start' command (mirrors src/cli/deploy.js). | | `--env <env>` | Deployment environment for non-default deploy ids (default: development). | | `--generate` | Render dynamic supporting files (nginx router config, env-file, app-command override). | | `--up` | Start the full stack detached (regenerates config first). | | `--down` | Stop and remove containers (and orphans). | | `--volumes` | With --down, also remove named volumes (destroys persisted data). | | `--restart` | Restart services (optionally a single [target]). | | `--build` | With --up rebuild images; alone, rebuilds images with --no-cache. | | `--pull` | Pull upstream images for all services. | | `--logs` | Follow logs for all services (optionally a single [target]). | | `--status` | Show a formatted status table of services. | | `--shell` | Open an interactive shell in [target] (default: app). | | `--exec <subcommand>` | General-purpose passthrough docker compose subcommand. | | `--compose-file <path>` | Path to the compose file (default: docker-compose.yml). | | `--env-file <path>` | Path to the compose env-file (default: docker/compose.env). | | `--nginx-conf <path>` | Path to the generated nginx config (default: docker/nginx/default.conf). | | `-h, --help` | display help for command | --- ### underpost lxd Manages LXD virtual machines as K3s nodes (control plane or workers). **Usage:** `underpost lxd [options] [vm-id]` #### Arguments | Argument | Description | | --- | --- | | `vm-id` | VM identifier shared by current-VM flags like --vm-create, --vm-delete, --vm-init, --vm-info, and --vm-test. | #### Options | Option | Description | | --- | --- | | `--init` | Initializes LXD on the current machine via preseed. | | `--reset` | Host-safe reset: removes proxy devices, stops/deletes VMs, drops admin-profile and lxdbr0. Does NOT touch the LXD snap or storage pools. | | `--purge` | DESTRUCTIVE: gracefully shuts down the LXD daemon (60s timeout), then removes the LXD snap. Combine with --reset to wipe per-VM state first. Safe replacement for the prior aggressive teardown. | | `--shutdown` | Pre-host-reboot procedure: gracefully stops every VM and the LXD daemon. Run BEFORE any reboot/poweroff to keep the host bootable. | | `--restore` | Symmetric to --shutdown: starts the LXD daemon, waits for it to be responsive, then starts every VM. VMs created via admin-profile have boot.autostart=false, so this is the explicit "bring the lab back up" command. | | `--install` | Installs the LXD snap. | | `--dev` | Use local paths instead of the global npm installation. | | `--create-virtual-network` | Creates the lxdbr0 bridge network. | | `--ipv4-address <cidr>` | IPv4 address/CIDR for the lxdbr0 bridge network (default: "10.250.250.1/24"). | | `--create-admin-profile` | Creates the admin-profile for VM management. | | `--control` | Initialize the target VM as a K3s control plane node. | | `--worker` | Initialize the target VM as a K3s worker node. | | `--vm-create` | Copy the LXC launch command for the command argument [vm-id] to the clipboard. | | `--vm-delete` | SAFELY stop and delete the command argument [vm-id] (removes proxy devices first, then stops, then deletes). Safe to re-run. | | `--vm-init` | Bring the command argument [vm-id] up as a K3s node end-to-end: OS base setup, mirror /home/dd/engine into the VM, then K3s role install via the local engine (use with --control or --worker). | | `--vm-info` | Display full configuration and status for the command argument [vm-id]. | | `--vm-test` | Run connectivity and health checks on the command argument [vm-id]. | | `--vm-sync-engine` | Re-copy the host engine source into the command argument [vm-id], overriding whatever is currently there (equivalent to the engine-bootstrap step of --vm-init in isolation). | | `--root-size <gb-size>` | Root disk size in GiB for --vm-create (default: 32). | | `--join-node <nodes>` | Join a K3s worker to a control plane. Standalone format: "workerName,controlName". When used with --vm-init --worker, provide just the control node name for auto-join. | | `--expose <vm-name:ports>` | Proxy host ports to a VM (e.g., "k3s-control:80,443"). | | `--node-port <port>` | Customizes the VM-side (connect) port for --expose, so the host listens on the given port but proxies to this NodePort inside the VM (e.g. expose host 27017 -> VM NodePort 32017). | | `--delete-expose <vm-name:ports>` | Remove proxied ports from a VM (e.g., "k3s-control:80,443"). | | `--copy` | For two-phase flows that surface a command for the user to execute (e.g. --create-admin-profile phase 1), copy the command to the clipboard instead of printing it to the terminal. | | `--namespace <namespace>` | Kubernetes namespace context (defaults to "default"). | | `--maas-project <project>` | LXD project managed by MAAS (e.g. "k3s-cluster"). When set, all lxc commands target this project so MAAS enumerates the VMs in its machines UI. | | `--move-to-project` | Stop the [vm-id] VM in the default project, move it to --maas-project, then start it so MAAS picks it up. Requires --maas-project. | | `-h, --help` | display help for command | --- ### underpost baremetal Manages baremetal server operations, including installation, database setup, commissioning, and user management. **Usage:** `underpost baremetal [options] [workflow-id]` #### Options | Option | Description | | --- | --- | | `--ip-address <ip-address>` | The IP address of the control server or the local machine. | | `--hostname <hostname>` | The hostname of the target baremetal machine. | | `--ip-file-server <ip-file-server>` | The IP address of the file server (NFS/TFTP). | | `--ip-config <ip-config>` | IP configuration string for the baremetal machine. | | `--netmask <netmask>` | Netmask of network. | | `--dns-server <dns-server>` | DNS server IP address. | | `--control-server-install` | Installs the baremetal control server. | | `--control-server-uninstall` | Uninstalls the baremetal control server. | | `--control-server-restart` | Restarts the baremetal control server. | | `--control-server-db-install` | Installs up the database for the baremetal control server. | | `--control-server-db-uninstall` | Uninstalls the database for the baremetal control server. | | `--create-machine` | Creates a new baremetal machine entry in the database. | | `--mac <mac>` | Specifies the MAC address for baremetal machine operations. Use "random" for random MAC, "hardware" to use device's actual MAC (no spoofing), or specify a MAC address. | | `--ipxe` | Chainloads iPXE to normalize identity before commissioning. | | `--ipxe-rebuild` | Forces rebuild of iPXE binary with embedded boot script. | | `--ipxe-build-iso <iso-path>` | Builds a standalone iPXE ISO with embedded script for the specified workflow ID. | | `--install-packer` | Installs Packer CLI. | | `--packer-maas-image-template <template-path>` | Creates a new image folder from canonical/packer-maas template path (requires workflow-id). | | `--packer-workflow-id <workflow-id>` | Specifies the workflow ID for Packer MAAS image operations. | | `--packer-maas-image-build` | Builds a MAAS image using Packer for the workflow specified by --packer-workflow-id. | | `--packer-maas-image-upload` | Uploads an existing MAAS image artifact without rebuilding for the workflow specified by --packer-workflow-id. | | `--packer-maas-image-cached` | Continue last build without removing artifacts (used with --packer-maas-image-build). | | `--remove-machines <system-ids>` | Removes baremetal machines by comma-separated system IDs, or use "all" | | `--clear-discovered` | Clears all discovered baremetal machines from the database. | | `--commission` | Init workflow for commissioning a physical machine. | | `--install-disk [device]` | Explicit target install disk for Rocky deployment (e.g. /dev/nvme0n1). Omit or leave empty to auto-detect the internal disk. | | `--no-auto-install` | Disables the ephemeral runtime AUTO_INSTALL fallback (controller must trigger install). | | `--no-remote-install` | Skips the controller-side remote install orchestration over SSH. | | `--worker` | Post-install infra role: join the deployed node as a Kubernetes worker (requires --control <ip>). Without this flag the node is set up as a control-plane. | | `--control <ip>` | Control-plane IP the worker node joins (used with --worker for kubeadm infra setup). | | `--ssh-key-dir <dir>` | Directory holding the SSH key pair used for commissioning/orchestration (expects <dir>/id_rsa and <dir>/id_rsa.pub). Overrides the workflow "sshKeyDir"; defaults to engine-private/deploy. Supports a leading ~. | | `--deploy-id <deploy-id>` | Deployment ID whose user key pair is used for SSH (key from engine-private/conf/<deploy-id>/users/<user>/id_rsa). Same user↔deployId↔key convention as the ssh command. | | `--user <user>` | SSH user paired with --deploy-id for key resolution and the login user on an existing control-plane (defaults to root). Mirrors the ssh command --user. | | `--engine-repo <url>` | Custom engine repo cloned + normalized to /home/dd/engine on the node (default: <GITHUB_USERNAME>/engine). | | `--engine-branch <branch>` | Branch of the engine repo to clone on the node. | | `--engine-private-repo <url>` | Custom private repo cloned + normalized to /home/dd/engine/engine-private on the node (default: <GITHUB_USERNAME>/engine-<id>-private). | | `--engine-private-branch <branch>` | Branch of the engine-private repo to clone on the node. | | `--bootstrap-http-server-run` | Runs a temporary bootstrap HTTP server for generic purposes such as serving iPXE scripts or ISO images during commissioning. | | `--bootstrap-http-server-path <path>` | Sets a custom bootstrap HTTP server path for baremetal commissioning. | | `--bootstrap-http-server-port <port>` | Sets a custom bootstrap HTTP server port for baremetal commissioning. | | `--iso-url <url>` | Uses a custom ISO URL for baremetal machine commissioning. | | `--nfs-build` | Builds an NFS root filesystem for a workflow id config architecture using QEMU emulation. | | `--nfs-mount` | Mounts the NFS root filesystem for a workflow id config architecture. | | `--nfs-reset` | Resets the NFS server completely, closing all connections before reloading exports. | | `--nfs-unmount` | Unmounts the NFS root filesystem for a workflow id config architecture. | | `--nfs-build-server` | Builds the NFS server for a workflow id config architecture. | | `--nfs-sh` | Copies QEMU emulation root entrypoint shell command to the clipboard. | | `--cloud-init` | Sets the kernel parameters and sets the necessary seed users on the HTTP server. | | `--cloud-init-update` | Updates cloud init for a workflow id config architecture. | | `--ubuntu-tools-build` | Builds ubuntu tools for chroot environment. | | `--ubuntu-tools-test` | Tests ubuntu tools in chroot environment. | | `--rocky-tools-build` | Builds rocky linux tools for chroot environment. | | `--rocky-tools-test` | Tests rocky linux tools in chroot environment. | | `--bootcmd <bootcmd-list>` | Comma-separated list of boot commands to execute. | | `--runcmd <runcmd-list>` | Comma-separated list of run commands to execute. | | `--logs <log-id>` | Displays logs for log id: dhcp,dhcp-lease,dhcp-lan,cloud-init,cloud-init-machine,cloud-init-config | | `--dev` | Sets the development context environment for baremetal operations. | | `--ls` | Lists available boot resources and machines. | | `--resume-infra-setup` | Skip commissioning, OS install, and all bootstrapping; resume only the SSH-based infra setup (kubeadm join/init) on a node that already has the OS installed and is reachable via SSH. | | `--resume-join` | Skip everything except the kubeadm join command. Assumes engine, Node.js, CRI-O, kubelet, and kubeadm are already installed. Only retrieves a fresh join token from the control-plane and runs kubeadm join. | | `-h, --help` | display help for command | --- ### underpost release Release orchestrator for building new versions and deploying releases of the Underpost CLI. **Usage:** `underpost release [options] [version]` #### Arguments | Argument | Description | | --- | --- | | `version` | The new version string to set (e.g., "3.1.4"). Defaults to current version. | #### Options | Option | Description | | --- | --- | | `--build` | Builds a new version: tests template, bumps versions, rebuilds manifests and configs. | | `--deploy` | Deploys the release: syncs secrets, commits, and pushes to remote repositories. | | `--ci-push <deploy-id>` | Local equivalent of engine-*.ci.yml: builds dd-{deploy-id} and pushes to the engine-{deploy-id} repository. Accepts the suffix (e.g., "cyberia"), "dd-cyberia", or "engine-cyberia". | | `--message <message>` | Commit message for --ci-push or --pwa-build (defaults to last commit of the engine repository). | | `--pwa-build` | Runs the pwa-microservices-template update flow: always re-clones, syncs engine sources, installs, builds, and pushes. | | `--dry-run` | For --build: previews version-bump changes (per-file substitution counts) without writing files or running downstream commands. | | `--mongo-host <host>` | For --build: override DB_HOST in the template .env.example for the smoke test (e.g., "192.168.1.82:27017"). | | `--mongo-user <user>` | For --build: override DB_USER in the template .env.example for the smoke test. | | `--mongo-password <password>` | For --build: override DB_PASSWORD in the template .env.example for the smoke test. | | `--valkey-host <host>` | For --build: override VALKEY_HOST in the template .env.example for the smoke test (e.g., "192.168.1.82"). | | `-h, --help` | display help for command

## Underpost CLI > underpost ci/cd cli v3.2.30 **Usage:** `underpost [options] [command]` ### Global options | Option | Description | | --- | --- | | `-V, --version` | output the version number | | `-h, --help` | display help for command | ### Commands | Command | Description | | --- | --- | | [`new`](#underpost-new) | Initializes a new Underpost project, service, or configuration. | | [`client`](#underpost-client) | Builds client assets, single replicas, and/or syncs environment ports. | | [`start`](#underpost-start) | Initiates application servers, build pipelines, or other defined services based on the deployment ID. | | [`clone`](#underpost-clone) | Clones a specified GitHub repository into the current directory. | | [`pull`](#underpost-pull) | Pulls the latest changes from a specified GitHub repository. | | [`cmt`](#underpost-cmt) | Manages commits to a GitHub repository, supporting various commit types and options. | | [`push`](#underpost-push) | Pushes committed changes from a local repository to a remote GitHub repository. | | [`env`](#underpost-env) | Sets environment variables and configurations related to a specific deployment ID. | | [`static`](#underpost-static) | Manages static build of page, bundles, and documentation with comprehensive customization options. | | [`config`](#underpost-config) | Manages Underpost configurations using various operators. | | [`root`](#underpost-root) | Displays the root path of the npm installation. | | [`ip`](#underpost-ip) | Displays the current public machine IP addresses. | | [`cluster`](#underpost-cluster) | Manages Kubernetes clusters, defaulting to Kind cluster initialization. | | [`deploy`](#underpost-deploy) | Manages application deployments, defaulting to deploying development pods. | | [`secret`](#underpost-secret) | Manages secrets for various platforms. | | [`image`](#underpost-image) | Manages Docker images, including building, saving, and loading into Kubernetes clusters. | | [`install`](#underpost-install) | Quickly imports Underpost npm dependencies by copying them. | | [`db`](#underpost-db) | Manages database operations with support for MariaDB and MongoDB, including import/export, multi-pod targeting, and Git integration. | | [`metadata`](#underpost-metadata) | Manages cluster metadata operations, including import and export. | | [`cron`](#underpost-cron) | Manages cron jobs: execute jobs directly or generate and apply K8s CronJob manifests. | | [`fs`](#underpost-fs) | Manages file storage, defaulting to file upload operations. | | [`test`](#underpost-test) | Manages and runs tests, defaulting to the current Underpost default test suite. | | [`monitor`](#underpost-monitor) | Manages health server monitoring for specified deployments. | | [`ssh`](#underpost-ssh) | Manages SSH credentials and sessions for remote access to cluster nodes or services. | | [`run`](#underpost-run) | Runs specified scripts using various runners. | | [`docker-compose`](#underpost-docker-compose) | General-purpose Docker Compose development pipeline (mirrors the Kubernetes dev stack). | | [`lxd`](#underpost-lxd) | Manages LXD virtual machines as K3s nodes (control plane or workers). | | [`baremetal`](#underpost-baremetal) | Manages baremetal server operations, including installation, database setup, commissioning, and user management. | | [`release`](#underpost-release) | Release orchestrator for building new versions and deploying releases of the Underpost CLI. | ## Command reference ### underpost new Initializes a new Underpost project, service, or configuration. **Usage:** `underpost new [options] [app-name]` #### Arguments | Argument | Description | | --- | --- | | `app-name` | The name of the new project. | #### Options | Option | Description | | --- | --- | | `--deploy-id ` | Create deploy ID conf env files | | `--sub-conf ` | Create sub conf env files | | `--cluster` | Create deploy ID cluster files and sync to current cluster | | `--build-repos` | Create deploy ID repositories | | `--build` | Build the deployment to pwa-microservices-template (requires --deploy-id) | | `--clean-template` | Clean the build directory (pwa-microservices-template) | | `--sync-conf` | Sync configuration to private repositories (requires --deploy-id) | | `--sync-start` | Sync start scripts in deploy ID package.json with root package.json (use 'dd' as --deploy-id to sync all dd.router) | | `--purge` | Remove deploy ID conf and all related repositories (requires --deploy-id) | | `--dev` | Sets the development cli context | | `--default-conf` | Create default deploy ID conf env files | | `--conf-workflow-id ` | Set custom configuration workflow ID for conf generation | | `-h, --help` | display help for command | --- ### underpost client Builds client assets, single replicas, and/or syncs environment ports. **Usage:** `underpost client [options] [deploy-id] [sub-conf] [host] [path]` #### Arguments | Argument | Description | | --- | --- | | `deploy-id` | The deployment ID to build. (default: "dd-default") | | `sub-conf` | The sub-configuration for the build. (default: "") | | `host` | Comma-separated hosts to filter the build. (default: "") | | `path` | Comma-separated paths to filter the build. (default: "") | #### Options | Option | Description | | --- | --- | | `--sync-env-port` | Sync environment port assignments across all deploy IDs | | `--single-replica` | Build single replica folders instead of full client | | `--build-zip` | Create zip files of the builds | | `--split ` | Split generated zip files into parts of the specified size in MB | | `--unzip ` | Extract a built client zip or split zip parts using the given build prefix | | `--merge-zip ` | Merge split ZIP parts back into a single ZIP file for the given build prefix | | `--lite-build` | Skip full build (default is full build) | | `--icons-build` | Build icons | | `-h, --help` | display help for command | --- ### underpost start Initiates application servers, build pipelines, or other defined services based on the deployment ID. **Usage:** `underpost start [options] [env]` #### Arguments | Argument | Description | | --- | --- | | `deploy-id` | The unique identifier for the deployment configuration. | | `env` | Optional: The environment to start (e.g., "development", "production"). Defaults to "development". | #### Options | Option | Description | | --- | --- | | `--run` | Starts application servers and monitors their health. | | `--build` | Triggers the client-side application build process. | | `--underpost-quickly-install` | Uses Underpost Quickly Install for dependency installation. | | `--skip-pull-base` | Skips cloning repositories, uses current workspace code directly. | | `--skip-full-build` | Skips the full client bundle build during deployment. | | `--pull-bundle` | Downloads the pre-built client bundle from Cloudinary via pull-bundle before starting. Use together with --skip-full-build to skip the local build entirely. | | `--private-test-repo` | During --build, clone the private test source repo (engine-test-) instead of the production engine- repo. | | `-h, --help` | display help for command | --- ### underpost clone Clones a specified GitHub repository into the current directory. **Usage:** `underpost clone [options] ` #### Arguments | Argument | Description | | --- | --- | | `uri` | The URI of the GitHub repository (e.g., "username/repository"). | #### Options | Option | Description | | --- | --- | | `--bare` | Performs a bare clone, downloading only the .git files. | | `--g8` | Uses the g8 repository extension for cloning. | | `-h, --help` | display help for command | --- ### underpost pull Pulls the latest changes from a specified GitHub repository. **Usage:** `underpost pull [options] ` #### Arguments | Argument | Description | | --- | --- | | `path` | The absolute or relative directory path where the repository is located. | | `uri` | The URI of the GitHub repository (e.g., "username/repository"). | #### Options | Option | Description | | --- | --- | | `--g8` | Uses the g8 repository extension for pulling. | | `-h, --help` | display help for command | --- ### underpost cmt Manages commits to a GitHub repository, supporting various commit types and options. **Usage:** `underpost cmt [options] [path] [commit-type] [module-tag] [message]` #### Arguments | Argument | Description | | --- | --- | | `path` | The absolute or relative directory path of the repository. | | `commit-type` | The type of commit to perform. Options: feat, fix, docs, style, refactor, perf, ci, cd, infra, build, test, chore, revert, backup. | | `module-tag` | Optional: Sets a specific module tag for the commit. | | `message` | Optional: Provides an additional custom message for the commit. | #### Options | Option | Description | | --- | --- | | `--log [latest-n]` | Shows commit history from the specified number of latest n path commits. | | `--last-msg ` | Displays the last n commit message. | | `--empty` | Allows committing with empty files. | | `--copy` | Copies the generated commit message to the clipboard. | | `--info` | Displays information about available commit types. | | `--diff` | Shows the current git diff changes. | | `--edit` | Edit last commit. | | `--deploy-id ` | Sets the deployment configuration ID for the commit context. | | `--cached` | Commit staged changes only or context. | | `--hashes ` | Comma-separated list of specific file hashes of commits. | | `--extension ` | specific file extensions of commits. | | `--changelog [latest-n]` | Print plain the changelog of the specified number of latest n commits, if no number is provided it will get the changelog to latest ci integration | | `--changelog-build` | Builds a CHANGELOG.md file based on the commit history | | `--changelog-min-version ` | Sets the minimum version limit for --changelog-build (default: 2.85.0) | | `--changelog-no-hash` | Excludes commit hashes from the generated changelog entries (used with --changelog-build). | | `--unpush` | With --log, automatically sets range to unpushed commits ahead of remote. | | `-b` | Shows the current Git branch name. | | `-p [branch]` | Shows the reflog for the specified branch. | | `--bc ` | Shows branches that contain the specified commit. | | `--is-remote-repo ` | Checks whether a remote Git repository URL is reachable. Prints true or false. | | `--has-changes` | Prints "1" if there are staged or unstaged git changes in the repository, empty string otherwise. | | `--remote-url` | Prints the current git remote URL (origin) in plain text. | | `--switch-repo ` | Switches the git remote (origin) to and force-pulls the target branch, overwriting the current working tree (discards local commits and tracked changes). Accepts a full URL or "owner/repo". | | `--target-branch ` | Target branch for --switch-repo (default: master). | | `-h, --help` | display help for command | --- ### underpost push Pushes committed changes from a local repository to a remote GitHub repository. **Usage:** `underpost push [options] ` #### Arguments | Argument | Description | | --- | --- | | `path` | The absolute or relative directory path of the repository. | | `uri` | The URI of the GitHub repository (e.g., "username/repository"). | #### Options | Option | Description | | --- | --- | | `-f` | Forces the push, overwriting the remote repository history. | | `--g8` | Uses the g8 repository extension for pushing. | | `-h, --help` | display help for command | --- ### underpost env Sets environment variables and configurations related to a specific deployment ID. **Usage:** `underpost env [options] [deploy-id] [env] [subConf]` #### Arguments | Argument | Description | | --- | --- | | `deploy-id` | The deployment configuration ID. Use 'clean' to restore default environment settings. Use 'root' to load underpost root env. Use 'current' to get plain current deploy Id. | | `env` | Optional: The environment to set (e.g., "production", "development"). Defaults to "production". | | `subConf` | Optional: The sub configuration to set. | #### Options | Option | Description | | --- | --- | | `-h, --help` | display help for command | --- ### underpost static Manages static build of page, bundles, and documentation with comprehensive customization options. **Usage:** `underpost static [options]` #### Options | Option | Description | | --- | --- | | `--page ` | Build custom static pages. | | `--title ` | Sets a custom title for the static page (deprecated: use --config-file). | | `--output-path <output-path>` | Sets the output path for the generated static page. | | `--description <description>` | Page description for SEO. | | `--keywords <keywords>` | Comma-separated keywords for SEO. | | `--author <author>` | Page author. | | `--theme-color <color>` | Theme color for mobile browsers. | | `--canonical-url <url>` | Canonical URL for SEO. | | `--thumbnail <url>` | Open Graph thumbnail image URL. | | `--locale <locale>` | Page locale (default: en-US). | | `--site-name <name>` | Site name for Open Graph. | | `--head-scripts <paths>` | Comma-separated paths to scripts for head section. | | `--body-scripts <paths>` | Comma-separated paths to scripts for body section. | | `--styles <paths>` | Comma-separated paths to stylesheets. | | `--favicon <path>` | Favicon path. | | `--apple-touch-icon <path>` | Apple touch icon path. | | `--manifest <path>` | Web manifest path. | | `--head-components <paths>` | Comma-separated SSR head component paths. | | `--body-components <paths>` | Comma-separated SSR body component paths. | | `--build-path <build-path>` | Sets a custom build path for static documents or assets. | | `--env <env>` | Sets the environment for the static build (e.g., "development", "production"). | | `--minify` | Minify HTML output (default: true for production). | | `--no-minify` | Disable HTML minification. | | `--config-file <path>` | Path to JSON configuration file. | | `--generate-config [path]` | Generate a template configuration file. | | `--lang <lang>` | HTML lang attribute (default: en). | | `--dir <dir>` | HTML dir attribute (default: ltr). | | `--dev` | Sets the development cli context | | `--run-sv [port]` | Start a standalone Express static server to preview the static build (default port: 5000). | | `-h, --help` | display help for command | --- ### underpost config Manages Underpost configurations using various operators. **Usage:** `underpost config [options] <operator> [key] [value]` #### Arguments | Argument | Description | | --- | --- | | `operator` | The configuration operation to perform. Options: set, delete, get, list, clean, isInsideContainer. | | `key` | Optional: The specific configuration key to manage. | | `value` | Optional: The value to set for the configuration key. | #### Options | Option | Description | | --- | --- | | `--plain` | Prints the configuration value in plain text. | | `--filter <keyword>` | Filters the list by matching key or value (only for list operation). | | `--deploy-id <deploy-id>` | Sets the deployment configuration ID for the operation context. | | `--build` | Sets the build context for the operation. | | `--copy` | Copies the configuration value to the clipboard (only for get operation). | | `-h, --help` | display help for command | --- ### underpost root Displays the root path of the npm installation. **Usage:** `underpost root [options]` #### Options | Option | Description | | --- | --- | | `-h, --help` | display help for command | --- ### underpost ip Displays the current public machine IP addresses. **Usage:** `underpost ip [options] [ips]` #### Arguments | Argument | Description | | --- | --- | | `ips` | Optional args comma-separated list of IP to process. | #### Options | Option | Description | | --- | --- | | `--dhcp` | Fetches and displays the current Dynamic Host Configuration Protocol server IP address. | | `--copy` | Copies the IP addresses to the clipboard. | | `--ban-ingress-add` | Adds IP addresses to banned ingress list. | | `--ban-ingress-remove` | Removes IP addresses from banned ingress list. | | `--ban-ingress-list` | Lists all banned ingress IP addresses. | | `--ban-ingress-clear` | Clears all banned ingress IP addresses. | | `--ban-egress-add` | Adds IP addresses to banned egress list. | | `--ban-egress-remove` | Removes IP addresses from banned egress list. | | `--ban-egress-list` | Lists all banned egress IP addresses. | | `--ban-egress-clear` | Clears all banned egress IP addresses. | | `--ban-both-add` | Adds IP addresses to both banned ingress and egress lists. | | `--ban-both-remove` | Removes IP addresses from both banned ingress and egress lists. | | `--mac` | Prints the MAC address of the main network interface. | | `-h, --help` | display help for command | --- ### underpost cluster Manages Kubernetes clusters, defaulting to Kind cluster initialization. **Usage:** `underpost cluster [options] [pod-name]` #### Arguments | Argument | Description | | --- | --- | | `pod-name` | Optional: Filters information by a specific pod name. | #### Options | Option | Description | | --- | --- | | `--reset` | Deletes all clusters and prunes all related data and caches. | | `--reset-mongodb` | Performs a hard cleanup of only MongoDB-related resources (StatefulSet, PVCs/PVs, Secrets, ConfigMaps, caches) without restarting the whole node. | | `--mariadb` | Initializes the cluster with a MariaDB statefulset. | | `--mysql` | Initializes the cluster with a MySQL statefulset. | | `--mongodb` | Initializes the cluster with a MongoDB statefulset. | | `--service-host <host>` | Set custom host/IP for exposed MongoDB and Valkey clients. | | `--postgresql` | Initializes the cluster with a PostgreSQL statefulset. | | `--mongodb4` | Initializes the cluster with a MongoDB 4.4 service. | | `--valkey` | Initializes the cluster with a Valkey service. | | `--ipfs` | Initializes the cluster with an ipfs-cluster statefulset. | | `--contour` | Initializes the cluster with Project Contour base HTTPProxy and Envoy. | | `--node-port` | Exposes enabled ready services (e.g. MongoDB 4.4, Valkey) to the host/public network via their NodePort Service manifest. | | `--node-selector <k8s-node-name>` | Pins the just-deployed StatefulSet (MongoDB 4.4 / Valkey) to the given Kubernetes node once it is ready (via a kubernetes.io/hostname nodeSelector). | | `--cert-manager` | Initializes the cluster with a Let's Encrypt production ClusterIssuer. | | `--dedicated-gpu` | Initializes the cluster with dedicated GPU base resources and environment settings. | | `--ns-use <ns-name>` | Switches the current Kubernetes context to the specified namespace (creates if it doesn't exist). | | `--kubeadm` | Initializes the cluster using kubeadm for control plane management. | | `--pod-network-cidr <cidr>` | Sets custom pod network CIDR for kubeadm cluster initialization (defaults to "192.168.0.0/16"). | | `--control-plane-endpoint <endpoint>` | Sets custom control plane endpoint for kubeadm cluster initialization (defaults to "localhost:6443"). | | `--grafana` | Initializes the cluster with a Grafana deployment. | | `--prom [hosts]` | Initializes the cluster with a Prometheus Operator deployment and monitor scrap for specified hosts. | | `--dev` | Initializes a development-specific cluster configuration. | | `--list-pods` | Displays detailed information about all pods. | | `--pull-image` | Sets an optional associated image to pull during initialization. | | `--init-host` | Installs necessary Kubernetes node CLI tools (e.g., kind, kubeadm, docker, podman, helm). | | `--uninstall-host` | Uninstalls all host components installed by init-host. | | `--config` | Sets the base Kubernetes node configuration. | | `--chown` | Sets the appropriate ownership for Kubernetes kubeconfig files. | | `--k3s` | Initializes the cluster using K3s (Lightweight Kubernetes). | | `--hosts <hosts>` | A comma-separated list of cluster hostnames or IP addresses. | | `--remove-volume-host-paths` | Removes specified volume host paths after execution. | | `--reset-mode <mode>` | Reset mode for --reset --k3s: "drain" (stop services, keep K3s installed) or "full" (uninstall + cleanup). Default: "full". | | `--namespace <namespace>` | Kubernetes namespace for cluster operations (defaults to "default"). | | `--replicas <replicas>` | Sets a custom number of replicas for statefulset deployments. | | `-h, --help` | display help for command | --- ### underpost deploy Manages application deployments, defaulting to deploying development pods. **Usage:** `underpost deploy [options] [deploy-list] [env]` #### Arguments | Argument | Description | | --- | --- | | `deploy-list` | A comma-separated list of deployment IDs (e.g., "default-a,default-b"). | | `env` | Optional: The environment for deployment (e.g., "development", "production"). Defaults to "development". | #### Options | Option | Description | | --- | --- | | `--remove` | Deletes specified deployments and their associated services. | | `--sync` | Synchronizes deployment environment variables, ports, and replica counts. | | `--info-router` | Displays the current router structure and configuration. | | `--expose` | Exposes services matching the provided deployment ID list. | | `--cert` | Resets TLS/SSL certificate secrets for deployments. | | `--cert-hosts <hosts>` | Resets TLS/SSL certificate secrets for specified hosts. | | `--self-signed` | Use a pre-created self-signed TLS secret (kubernetes.io/tls) instead of cert-manager. The secret must already exist in the namespace with the same name as the host. Enables TLS in the Contour HTTPProxy virtualhost without requiring a production ClusterIssuer. | | `--node <node>` | Sets optional node for deployment operations. | | `--ssh-key-path <path>` | Private key path for node SSH operations. Currently used when shipping a hostPath volume to a remote target node over SSH. Defaults to engine-private/deploy/id_rsa. | | `--build-manifest` | Builds Kubernetes YAML manifests, including deployments, services, proxies, and secrets. | | `--replicas <replicas>` | Sets a custom number of replicas for deployments. | | `--image <image>` | Sets a custom image for deployments. | | `--versions <deployment-versions>` | A comma-separated list of custom deployment versions. | | `--traffic <traffic-versions>` | A comma-separated list of custom deployment traffic weights. | | `--timeout-response <duration>` | Sets HTTPProxy per-route response timeout (e.g., "1s", "300ms", "infinity"). | | `--timeout-idle <duration>` | Sets HTTPProxy per-route idle timeout (e.g., "10s", "infinity"). | | `--retry-count <count>` | Sets HTTPProxy per-route retry count (e.g., 3). | | `--retry-per-try-timeout <duration>` | Sets HTTPProxy retry per-try timeout (e.g., "150ms"). | | `--disable-update-deployment` | Disables updates to deployments. | | `--disable-runtime-probes` | Omits the internal-status HTTP probes from generated deployment manifests. | | `--tcp-probes` | Generates legacy TCP socket probes instead of HTTP internal-status probes (migration). | | `--disable-update-proxy` | Disables updates to proxies. | | `--disable-deployment-proxy` | Disables proxies of deployments. | | `--disable-update-volume` | Disables updates to volume mounts during deployment. | | `--status` | Retrieves current network traffic data from resource deployments and the host machine network configuration. | | `--kubeadm` | Enables the kubeadm context for deployment operations. | | `--k3s` | Enables the k3s context for deployment operations. | | `--kind` | Enables the kind context for deployment operations. | | `--git-clean` | Runs git clean on volume mount paths before copying. | | `--disable-update-underpost-config` | Disables updates to Underpost configuration during deployment. | | `--namespace <namespace>` | Kubernetes namespace for deployment operations (defaults to "default"). | | `--kind-type <kind-type>` | Specifies the Kind cluster type for deployment operations. | | `--port <port>` | Sets up port forwarding from local to remote ports. | | `--expose-port <port>` | Sets the local:remote port to expose when --expose is active (overrides auto-detected service port). | | `--expose-local-port <port>` | Sets a different local port for --expose (e.g. 80) while keeping the remote service port. Useful for /etc/hosts local access without specifying a port in the browser. | | `--local-proxy` | Forward all service TCP ports locally and start the Node.js path-routing proxy. Enables full path-based routing (e.g. /wp alongside /) without needing --expose-local-port. Requires --expose. | | `--cmd <cmd>` | Custom initialization command for deployment (comma-separated commands). | | `--skip-full-build` | Skip client bundle rebuild; container will pull pre-built bundle via pull-bundle instead. | | `--pull-bundle` | Explicitly pull the pre-built client bundle from Cloudinary inside the container. Use together with --skip-full-build. | | `--image-pull-policy <policy>` | Override container imagePullPolicy in the generated deployment manifest (Always, IfNotPresent, Never). Defaults to Never for localhost/ images and IfNotPresent otherwise. | | `--tls` | Enables TLS for the local proxy started by --expose --local-proxy. The proxy will serve HTTPS on port 443 using self-signed certificates resolved from the local SSL store. Use together with --expose and --local-proxy. | | `-h, --help` | display help for command | --- ### underpost secret Manages secrets for various platforms. **Usage:** `underpost secret [options] <platform>` #### Arguments | Argument | Description | | --- | --- | | `platform` | The secret management platform. Options: underpost, globalSecretClean. | #### Options | Option | Description | | --- | --- | | `--init` | Initializes the secrets platform environment. | | `--create-from-file <path-env-file>` | Creates secrets from a specified environment file. | | `--create-from-env` | Creates secrets from container environment variables (envFrom: secretRef). | | `--global-clean` | Removes all filesystem traces of secrets (engine-private, .env, conf cache). | | `--list` | Lists all available secrets for the platform. | | `-h, --help` | display help for command | --- ### underpost image Manages Docker images, including building, saving, and loading into Kubernetes clusters. **Usage:** `underpost image [options]` #### Options | Option | Description | | --- | --- | | `--build` | Builds a Docker image using Podman, optionally saves it as a tar archive, and loads it into a specified Kubernetes cluster (Kind, Kubeadm, or K3s). | | `--ls` | Lists all available Underpost Dockerfile images. | | `--rm <image-id>` | Removes specified Underpost Dockerfile images. | | `--path [path]` | The path to the Dockerfile directory. | | `--image-name [image-name]` | Sets a custom name for the Docker image. | | `--image-path [image-path]` | Sets the output path for the tar image archive. | | `--dockerfile-name [dockerfile-name]` | Sets a custom name for the Dockerfile. | | `--podman-save` | Exports the built image as a tar file using Podman. | | `--pull-base` | Pulls base images and builds a "rockylinux9-underpost" image. | | `--spec` | Get current cached list of container images used by all pods | | `--namespace <namespace>` | Kubernetes namespace for image operations (defaults to "default"). | | `--kind` | Set kind cluster env image context management. | | `--kubeadm` | Set kubeadm cluster env image context management. | | `--k3s` | Set k3s cluster env image context management. | | `--node-name` | Set node name for kubeadm or k3s cluster env image context management. | | `--reset` | Performs a build without using the cache. | | `--dev` | Use development mode. | | `--pull-dockerhub <dockerhub-image>` | Sets a custom Docker Hub image for base image pulls. | | `-h, --help` | display help for command | --- ### underpost install Quickly imports Underpost npm dependencies by copying them. **Usage:** `underpost install [options]` #### Options | Option | Description | | --- | --- | | `-h, --help` | display help for command | --- ### underpost db Manages database operations with support for MariaDB and MongoDB, including import/export, multi-pod targeting, and Git integration. **Usage:** `underpost db [options] [deploy-list]` #### Arguments | Argument | Description | | --- | --- | | `deploy-list` | A comma-separated list of deployment IDs (e.g., "default-a,default-b"). | #### Options | Option | Description | | --- | --- | | `--import` | Imports container backups from specified repositories. | | `--export` | Exports container backups to specified repositories. | | `--pod-name <pod-name>` | Comma-separated list of pod names or patterns (supports wildcards like "mariadb-*"). | | `--all-pods` | Target all matching pods instead of just the first one. | | `--primary-pod` | Automatically detect and use MongoDB primary pod (MongoDB only). | | `--primary-pod-ensure <pod-name>` | Ensure setup of MongoDB replica set primary pod before operations. | | `--stats` | Display database statistics (collection/table names with document/row counts). | | `--collections <collections>` | Comma-separated list of database collections to operate on. | | `--out-path <out-path>` | Specifies a custom output path for backups. | | `--drop` | Drops the specified databases or collections before importing. | | `--preserveUUID` | Preserves UUIDs during database import operations. | | `--git` | Enables Git integration for backup version control (clone, pull, commit, push to GitHub). | | `--force-clone` | Forces cloning of the Git repository, overwriting local changes. | | `--hosts <hosts>` | Comma-separated list of database hosts to filter operations. | | `--paths <paths>` | Comma-separated list of paths to filter database operations. | | `--ns <ns-name>` | Kubernetes namespace context for database operations (defaults to "default"). | | `--macro-rollback-export <n-commits-reset>` | Exports a macro rollback script that reverts the last n commits (Git integration required). | | `--clean-fs-collection` | Cleans orphaned File documents from collections that are not referenced by any models. | | `--clean-fs-dry-run` | Dry run mode - shows what would be deleted without actually deleting (use with --clean-fs-collection). | | `--dev` | Sets the development cli context | | `--kubeadm` | Enables the kubeadm context for database operations. | | `--kind` | Enables the kind context for database operations. | | `--k3s` | Enables the k3s context for database operations. | | `--repo-backup` | Backs up repositories (git commit+push) inside deployment pods via kubectl exec. | | `-h, --help` | display help for command | --- ### underpost metadata Manages cluster metadata operations, including import and export. **Usage:** `underpost metadata [options] [deploy-id] [host] [path]` #### Arguments | Argument | Description | | --- | --- | | `deploy-id` | The deployment ID to manage metadata. | | `host` | The host to manage metadata. | | `path` | The path to manage metadata. | #### Options | Option | Description | | --- | --- | | `--import` | Imports from local storage. | | `--export` | Exports to local storage. | | `--crons` | Apply to cron data collection | | `--instances` | Apply to instance data collection | | `--generate` | Generate cluster metadata | | `--itc` | Apply under container execution context | | `--dev` | Sets the development cli context | | `-h, --help` | display help for command | --- ### underpost cron Manages cron jobs: execute jobs directly or generate and apply K8s CronJob manifests. **Usage:** `underpost cron [options] [deploy-list] [job-list]` #### Arguments | Argument | Description | | --- | --- | | `deploy-list` | A comma-separated list of deployment IDs (e.g., "default-a,default-b"). | | `job-list` | A comma-separated list of job IDs. Options: dns,backup. Defaults to all available jobs. | #### Options | Option | Description | | --- | --- | | `--generate-k8s-cronjobs` | Generates Kubernetes CronJob YAML manifests from cron configuration. | | `--apply` | Applies generated K8s CronJob manifests to the cluster via kubectl. | | `--setup-start [deploy-id]` | Updates deploy-id package.json start script and generates+applies its K8s CronJob manifests. | | `--namespace <namespace>` | Kubernetes namespace for the CronJob resources (default: "default"). | | `--image <image>` | Custom container image for the CronJob pods. | | `--git` | Pass --git flag to cron job execution. | | `--cmd <cmd>` | Optional pre-script commands to run before cron execution. | | `--dev` | Use local ./ base path instead of global underpost installation. | | `--k3s` | Use k3s cluster context (apply directly on host). | | `--kind` | Use kind cluster context (apply via kind-worker container). | | `--kubeadm` | Use kubeadm cluster context (apply directly on host). | | `--dry-run` | Preview cron jobs without executing them. | | `--create-job-now` | After applying manifests, immediately create a Job from each CronJob (requires --apply). | | `-h, --help` | display help for command | --- ### underpost fs Manages file storage, defaulting to file upload operations. **Usage:** `underpost fs [options] [path]` #### Arguments | Argument | Description | | --- | --- | | `path` | The absolute or relative directory path for file operations. | #### Options | Option | Description | | --- | --- | | `--rm` | Removes the specified file. | | `--git` | Displays current Git changes related to file storage. | | `--recursive` | Uploads files recursively from the specified path. | | `--deploy-id <deploy-id>` | Specifies the deployment configuration ID for file operations. | | `--pull` | Downloads the specified file. | | `--omit-unzip` | With --pull, keeps the downloaded .zip file and skips extraction. | | `--force` | Forces the action, overriding any warnings or conflicts. | | `--storage-file-path <storage-file-path>` | Specifies a custom file storage path. | | `-h, --help` | display help for command | --- ### underpost test Manages and runs tests, defaulting to the current Underpost default test suite. **Usage:** `underpost test [options] [deploy-list]` #### Arguments | Argument | Description | | --- | --- | | `deploy-list` | A comma-separated list of deployment IDs (e.g., "default-a,default-b"). | #### Options | Option | Description | | --- | --- | | `--itc` | Executes tests within the container execution context. | | `--sh` | Copies the container entrypoint shell command to the clipboard. | | `--logs` | Displays container logs for test debugging. | | `--pod-name <pod-name>` | Optional: Specifies the pod name for test execution. | | `--pod-status <pod-status>` | Optional: Filters tests by pod status. | | `--kind-type <kind-type>` | Optional: Specifies the Kind cluster type for tests. | | `-h, --help` | display help for command | --- ### underpost monitor Manages health server monitoring for specified deployments. **Usage:** `underpost monitor [options] <deploy-id> [env]` #### Arguments | Argument | Description | | --- | --- | | `deploy-id` | The deployment configuration ID to monitor. | | `env` | Optional: The environment to monitor (e.g., "development", "production"). Defaults to "development". | #### Options | Option | Description | | --- | --- | | `--ms-interval <ms-interval>` | Sets a custom millisecond interval for monitoring checks. | | `--now` | Executes the monitor script immediately. | | `--single` | Disables recurrence, running the monitor script only once. | | `--replicas <replicas>` | Sets a custom number of replicas for monitoring. Defaults to 1. | | `--type <type>` | Sets a custom monitor type. | | `--sync` | Synchronizes with current proxy deployments and traffic configurations. | | `--namespace <namespace>` | Sets the Kubernetes namespace for the deployment. Defaults to "default". | | `--timeout-response <duration>` | Sets HTTPProxy per-route response timeout (e.g., "5s"). | | `--timeout-idle <duration>` | Sets HTTPProxy per-route idle timeout (e.g., "10s", "infinity"). | | `--retry-count <count>` | Sets HTTPProxy per-route retry count (e.g., 3). | | `--retry-per-try-timeout <duration>` | Sets HTTPProxy retry per-try timeout (e.g., "150ms"). | | `--disable-private-conf-update` | Disables updates to private configuration during execution. | | `--versions <deployment-versions>` | Specifies the deployment versions to monitor. eg. "blue,green", "green" | | `--ready-deployment` | Run in ready deployment monitor mode. | | `--promote` | Promotes the deployment after monitoring. | | `-h, --help` | display help for command | --- ### underpost ssh Manages SSH credentials and sessions for remote access to cluster nodes or services. **Usage:** `underpost ssh [options]` #### Options | Option | Description | | --- | --- | | `--deploy-id <deploy-id>` | Sets deploy id context for ssh operations. | | `--generate` | Generates new ssh credential and stores it in current private keys file storage. | | `--user <user>` | Sets custom ssh user | | `--password <password>` | Sets custom ssh password | | `--host <host>` | Sets custom ssh host | | `--port <port>` | Sets custom ssh port | | `--filter <filter>` | Filters ssh user credentials from current private keys file storage. | | `--groups <groups>` | Sets comma-separated ssh user groups for the ssh user credential. | | `--user-add` | Adds a new ssh user credential to current private keys file storage. | | `--user-remove` | Removes an existing ssh user credential from current private keys file storage. | | `--user-ls` | Lists all ssh user credentials from current private keys file storage. | | `--start` | Starts an SSH session with the specified credentials. | | `--reset` | Resets ssh configuration and deletes all stored credentials. | | `--keys-list` | Lists all ssh keys from current private keys file storage. | | `--hosts-list` | Lists all ssh hosts from current private keys file storage. | | `--disable-password` | Disables password authentication for the SSH session. | | `--key-test` | Tests the SSH key using ssh-keygen. | | `--stop` | Stops the SSH service. | | `--status` | Checks the status of the SSH service. | | `--connect-uri` | Displays the connection URI. | | `--copy` | Copies the connection URI to clipboard. | | `-h, --help` | display help for command | --- ### underpost run Runs specified scripts using various runners. **Usage:** `underpost run [options] <runner-id> [path]` #### Arguments | Argument | Description | | --- | --- | | `runner-id` | The runner ID to run. Options: dev-cluster,etc-hosts,ipfs-expose,metadata,svc-ls,svc-rm,ssh-deploy-info,node-move,dev-hosts-expose,dev-hosts-restore,cluster-build,template-deploy,template-deploy-local,docker-image,clean,pull,release-deploy,ssh-deploy,ide,crypto-policy,sync,stop,ssh-deploy-stop,ssh-deploy-db-rollback,ssh-deploy-db,ssh-deploy-db-status,tz,get-proxy,instance-promote,instance,instance-build-manifest,ls-deployments,host-update,install-crio,dd-container,ip-info,db-client,git-conf,promote,metrics,cluster,deploy,disk-clean,disk-devices,disk-usage,dev,service,sh,log,ps,pid-info,background,ports,deploy-test,tf-vae-test,spark-template,pull-rocky-image,rmi,kill,generate-pass,secret,underpost-config,gpu-env,tf-gpu-test,deploy-job,push-bundle,pull-bundle,build-cluster-deployment-manifests,monitor-ui,shared-dir,shared-dir-add-user. | | `path` | The input value, identifier, or path for the operation. | #### Options | Option | Description | | --- | --- | | `--cmd <command-list>` | Comma-separated list of commands to execute. | | `--args <args-array>` | Array of arguments to pass to the command. | | `--dev` | Sets the development context environment for the script. | | `--build` | Set builder context runner | | `--replicas <replicas>` | Sets a custom number of replicas for deployment. | | `--pod-name <pod-name>` | Optional: Specifies the pod name for execution. | | `--node-name <node-name>` | Optional: Specifies the node name for execution. | | `--ssh-key-path <path>` | Optional: Private key path for node SSH operations, forwarded to volume shipping over SSH. Defaults to engine-private/deploy/id_rsa. | | `--port <port>` | Optional: Specifies the port for execution. | | `--etc-hosts` | Enables etc-hosts context for the runner execution. | | `--volume-host-path <volume-host-path>` | Optional: Specifies the volume host path for test execution. | | `--volume-mount-path <volume-mount-path>` | Optional: Specifies the volume mount path for test execution. | | `--volume-type <volume-type>` | Optional: Specifies the volume type for test execution. | | `--image-name <image-name>` | Optional: Specifies the image name for test execution. | | `--container-name <container-name>` | Optional: Specifies the container name for test execution. | | `--namespace <namespace>` | Optional: Specifies the namespace for test execution. | | `--tty` | Enables TTY for the container in deploy-job. | | `--stdin` | Keeps STDIN open for the container in deploy-job. | | `--restart-policy <policy>` | Sets the restart policy for the job in deploy-job. | | `--runtime-class-name <name>` | Sets the runtime class name for the job in deploy-job. | | `--image-pull-policy <policy>` | Sets the image pull policy for the job in deploy-job. | | `--api-version <version>` | Sets the API version for the job manifest in deploy-job. | | `--labels <labels>` | Optional: Specifies a comma-separated list of key-value pairs for labels (e.g., "app=my-app,env=prod"). | | `--claim-name <name>` | Optional: Specifies the claim name for volume mounting in deploy-job. | | `--kind-type <kind-type>` | Specifies the kind of Kubernetes resource (e.g., Job, Deployment) for deploy-job. | | `--force` | Forces operation, overriding any warnings or conflicts. | | `--tls` | Enables TLS for the runner execution. | | `--reset` | Resets the runner state before execution. | | `--dev-proxy-port-offset <port-offset>` | Sets a custom port offset for development proxy. | | `--host-network` | Enables host network mode for the runner execution. | | `--requests-memory <requests-memory>` | Requests memory limit for the runner execution. | | `--requests-cpu <requests-cpu>` | Requests CPU limit for the runner execution. | | `--limits-memory <limits-memory>` | Sets memory limit for the runner execution. | | `--limits-cpu <limits-cpu>` | Sets CPU limit for the runner execution. | | `--resource-template-id <resource-template-id >` | Specifies a resource template ID for the runner execution. | | `--expose` | Enables service exposure for the runner execution. | | `--conf-server-path <conf-server-path>` | Sets a custom configuration server path. | | `--underpost-root <underpost-root>` | Sets a custom Underpost root path. | | `--cmd-cron-jobs <cmd-cron-jobs>` | Pre-script commands to run before cron job execution. | | `--deploy-id-cron-jobs <deploy-id-cron-jobs>` | Specifies deployment IDs to synchronize cron jobs with during execution. | | `--timezone <timezone>` | Sets the timezone for the runner execution. | | `--kubeadm` | Sets the kubeadm cluster context for the runner execution. | | `--k3s` | Sets the k3s cluster context for the runner execution. | | `--kind` | Sets the kind cluster context for the runner execution. | | `--git-clean` | Runs git clean on volume mount paths before copying. | | `--deploy-id <deploy-id>` | Sets deploy id context for the runner execution. | | `--user <user>` | Sets user context for the runner execution. | | `--hosts <hosts>` | Comma-separated list of hosts for the runner execution. | | `--instance-id <instance-id>` | Sets instance id context for the runner execution. | | `--pid <process-id>` | Sets process id context for the runner execution. | | `--timeout-response <duration>` | Sets HTTPProxy per-route response timeout (e.g., "1s", "300ms", "infinity"). | | `--timeout-idle <duration>` | Sets HTTPProxy per-route idle timeout (e.g., "10s", "infinity"). | | `--retry-count <count>` | Sets HTTPProxy per-route retry count (e.g., 3). | | `--retry-per-try-timeout <duration>` | Sets HTTPProxy retry per-try timeout (e.g., "150ms"). | | `--disable-private-conf-update` | Disables updates to private configuration during execution. | | `--logs` | Streams logs during the runner execution. | | `--monitor-status <status>` | Sets the status to monitor for pod/resource (default: "Running"). | | `--monitor-status-kind-type <kind-type>` | Sets the Kubernetes resource kind type to monitor (default: "pods"). | | `--monitor-status-delta-ms <milliseconds>` | Sets the polling interval in milliseconds for status monitoring (default: 1000). | | `--monitor-status-max-attempts <attempts>` | Sets the maximum number of status check attempts (default: 600). | | `--dry-run` | Preview operations without executing them. | | `--from-n-commit <n>` | Number of commits back to use for message propagation in template-deploy (default: 1, last commit only). | | `--create-job-now` | After applying cron manifests, immediately create a Job from each CronJob (forwarded to cron runner). | | `--host-aliases <host-aliases>` | Adds entries to the Pod /etc/hosts via hostAliases. Format: semicolon-separated entries of "ip=hostname1,hostname2" (e.g., "127.0.0.1=foo.local,bar.local;10.1.2.3=foo.remote,bar.remote"). | | `--copy` | Copies the runner output to the clipboard (supported by: generate-pass, template-deploy-local). | | `--skip-full-build` | Skip client bundle rebuild; triggers pull-bundle in container startup (supported by: sync, template-deploy). | | `--pull-bundle` | Explicitly download the pre-built client bundle from Cloudinary inside the container (supported by: sync, template-deploy). Use together with --skip-full-build. | | `--remove` | Remove/teardown resources | | `--test` | Enables test/generic-purpose mode for the runner (e.g. use self-signed TLS instead of cert-manager). | | `-h, --help` | display help for command | --- ### underpost docker-compose General-purpose Docker Compose development pipeline (mirrors the Kubernetes dev stack). **Usage:** `underpost docker-compose [options] [target]` #### Arguments | Argument | Description | | --- | --- | | `target` | Optional service name for --logs, --shell, --restart, or --build. | #### Options | Option | Description | | --- | --- | | `--install` | Install Docker Engine and the Compose v2 plugin on RHEL/Rocky hosts. | | `--reset` | Comprehensive teardown (equivalent to cluster --reset): removes all stack containers, the network, named volumes (destroys data), orphans, and generated artifacts. | | `--force` | Force reinstall (--install), remove volumes (--down), or also drop the env-file (--reset). | | `--deploy-id <deploy-id>` | Deployment to run as the app container (default: dd-default). 'dd-default' self-bootstraps a fresh engine; any other id runs the standard 'underpost start' command (mirrors src/cli/deploy.js). | | `--env <env>` | Deployment environment for non-default deploy ids (default: development). | | `--generate` | Render dynamic supporting files (nginx router config, env-file, app-command override). | | `--up` | Start the full stack detached (regenerates config first). | | `--down` | Stop and remove containers (and orphans). | | `--volumes` | With --down, also remove named volumes (destroys persisted data). | | `--restart` | Restart services (optionally a single [target]). | | `--build` | With --up rebuild images; alone, rebuilds images with --no-cache. | | `--pull` | Pull upstream images for all services. | | `--logs` | Follow logs for all services (optionally a single [target]). | | `--status` | Show a formatted status table of services. | | `--shell` | Open an interactive shell in [target] (default: app). | | `--exec <subcommand>` | General-purpose passthrough docker compose subcommand. | | `--compose-file <path>` | Path to the compose file (default: docker-compose.yml). | | `--env-file <path>` | Path to the compose env-file (default: docker/compose.env). | | `--nginx-conf <path>` | Path to the generated nginx config (default: docker/nginx/default.conf). | | `-h, --help` | display help for command | --- ### underpost lxd Manages LXD virtual machines as K3s nodes (control plane or workers). **Usage:** `underpost lxd [options] [vm-id]` #### Arguments | Argument | Description | | --- | --- | | `vm-id` | VM identifier shared by current-VM flags like --vm-create, --vm-delete, --vm-init, --vm-info, and --vm-test. | #### Options | Option | Description | | --- | --- | | `--init` | Initializes LXD on the current machine via preseed. | | `--reset` | Host-safe reset: removes proxy devices, stops/deletes VMs, drops admin-profile and lxdbr0. Does NOT touch the LXD snap or storage pools. | | `--purge` | DESTRUCTIVE: gracefully shuts down the LXD daemon (60s timeout), then removes the LXD snap. Combine with --reset to wipe per-VM state first. Safe replacement for the prior aggressive teardown. | | `--shutdown` | Pre-host-reboot procedure: gracefully stops every VM and the LXD daemon. Run BEFORE any reboot/poweroff to keep the host bootable. | | `--restore` | Symmetric to --shutdown: starts the LXD daemon, waits for it to be responsive, then starts every VM. VMs created via admin-profile have boot.autostart=false, so this is the explicit "bring the lab back up" command. | | `--install` | Installs the LXD snap. | | `--dev` | Use local paths instead of the global npm installation. | | `--create-virtual-network` | Creates the lxdbr0 bridge network. | | `--ipv4-address <cidr>` | IPv4 address/CIDR for the lxdbr0 bridge network (default: "10.250.250.1/24"). | | `--create-admin-profile` | Creates the admin-profile for VM management. | | `--control` | Initialize the target VM as a K3s control plane node. | | `--worker` | Initialize the target VM as a K3s worker node. | | `--vm-create` | Copy the LXC launch command for the command argument [vm-id] to the clipboard. | | `--vm-delete` | SAFELY stop and delete the command argument [vm-id] (removes proxy devices first, then stops, then deletes). Safe to re-run. | | `--vm-init` | Bring the command argument [vm-id] up as a K3s node end-to-end: OS base setup, mirror /home/dd/engine into the VM, then K3s role install via the local engine (use with --control or --worker). | | `--vm-info` | Display full configuration and status for the command argument [vm-id]. | | `--vm-test` | Run connectivity and health checks on the command argument [vm-id]. | | `--vm-sync-engine` | Re-copy the host engine source into the command argument [vm-id], overriding whatever is currently there (equivalent to the engine-bootstrap step of --vm-init in isolation). | | `--root-size <gb-size>` | Root disk size in GiB for --vm-create (default: 32). | | `--join-node <nodes>` | Join a K3s worker to a control plane. Standalone format: "workerName,controlName". When used with --vm-init --worker, provide just the control node name for auto-join. | | `--expose <vm-name:ports>` | Proxy host ports to a VM (e.g., "k3s-control:80,443"). | | `--node-port <port>` | Customizes the VM-side (connect) port for --expose, so the host listens on the given port but proxies to this NodePort inside the VM (e.g. expose host 27017 -> VM NodePort 32017). | | `--delete-expose <vm-name:ports>` | Remove proxied ports from a VM (e.g., "k3s-control:80,443"). | | `--copy` | For two-phase flows that surface a command for the user to execute (e.g. --create-admin-profile phase 1), copy the command to the clipboard instead of printing it to the terminal. | | `--namespace <namespace>` | Kubernetes namespace context (defaults to "default"). | | `--maas-project <project>` | LXD project managed by MAAS (e.g. "k3s-cluster"). When set, all lxc commands target this project so MAAS enumerates the VMs in its machines UI. | | `--move-to-project` | Stop the [vm-id] VM in the default project, move it to --maas-project, then start it so MAAS picks it up. Requires --maas-project. | | `-h, --help` | display help for command | --- ### underpost baremetal Manages baremetal server operations, including installation, database setup, commissioning, and user management. **Usage:** `underpost baremetal [options] [workflow-id]` #### Options | Option | Description | | --- | --- | | `--ip-address <ip-address>` | The IP address of the control server or the local machine. | | `--hostname <hostname>` | The hostname of the target baremetal machine. | | `--ip-file-server <ip-file-server>` | The IP address of the file server (NFS/TFTP). | | `--ip-config <ip-config>` | IP configuration string for the baremetal machine. | | `--netmask <netmask>` | Netmask of network. | | `--dns-server <dns-server>` | DNS server IP address. | | `--control-server-install` | Installs the baremetal control server. | | `--control-server-uninstall` | Uninstalls the baremetal control server. | | `--control-server-restart` | Restarts the baremetal control server. | | `--control-server-db-install` | Installs up the database for the baremetal control server. | | `--control-server-db-uninstall` | Uninstalls the database for the baremetal control server. | | `--create-machine` | Creates a new baremetal machine entry in the database. | | `--mac <mac>` | Specifies the MAC address for baremetal machine operations. Use "random" for random MAC, "hardware" to use device's actual MAC (no spoofing), or specify a MAC address. | | `--ipxe` | Chainloads iPXE to normalize identity before commissioning. | | `--ipxe-rebuild` | Forces rebuild of iPXE binary with embedded boot script. | | `--ipxe-build-iso <iso-path>` | Builds a standalone iPXE ISO with embedded script for the specified workflow ID. | | `--install-packer` | Installs Packer CLI. | | `--packer-maas-image-template <template-path>` | Creates a new image folder from canonical/packer-maas template path (requires workflow-id). | | `--packer-workflow-id <workflow-id>` | Specifies the workflow ID for Packer MAAS image operations. | | `--packer-maas-image-build` | Builds a MAAS image using Packer for the workflow specified by --packer-workflow-id. | | `--packer-maas-image-upload` | Uploads an existing MAAS image artifact without rebuilding for the workflow specified by --packer-workflow-id. | | `--packer-maas-image-cached` | Continue last build without removing artifacts (used with --packer-maas-image-build). | | `--remove-machines <system-ids>` | Removes baremetal machines by comma-separated system IDs, or use "all" | | `--clear-discovered` | Clears all discovered baremetal machines from the database. | | `--commission` | Init workflow for commissioning a physical machine. | | `--install-disk [device]` | Explicit target install disk for Rocky deployment (e.g. /dev/nvme0n1). Omit or leave empty to auto-detect the internal disk. | | `--no-auto-install` | Disables the ephemeral runtime AUTO_INSTALL fallback (controller must trigger install). | | `--no-remote-install` | Skips the controller-side remote install orchestration over SSH. | | `--worker` | Post-install infra role: join the deployed node as a Kubernetes worker (requires --control <ip>). Without this flag the node is set up as a control-plane. | | `--control <ip>` | Control-plane IP the worker node joins (used with --worker for kubeadm infra setup). | | `--ssh-key-dir <dir>` | Directory holding the SSH key pair used for commissioning/orchestration (expects <dir>/id_rsa and <dir>/id_rsa.pub). Overrides the workflow "sshKeyDir"; defaults to engine-private/deploy. Supports a leading ~. | | `--deploy-id <deploy-id>` | Deployment ID whose user key pair is used for SSH (key from engine-private/conf/<deploy-id>/users/<user>/id_rsa). Same user↔deployId↔key convention as the ssh command. | | `--user <user>` | SSH user paired with --deploy-id for key resolution and the login user on an existing control-plane (defaults to root). Mirrors the ssh command --user. | | `--engine-repo <url>` | Custom engine repo cloned + normalized to /home/dd/engine on the node (default: <GITHUB_USERNAME>/engine). | | `--engine-branch <branch>` | Branch of the engine repo to clone on the node. | | `--engine-private-repo <url>` | Custom private repo cloned + normalized to /home/dd/engine/engine-private on the node (default: <GITHUB_USERNAME>/engine-<id>-private). | | `--engine-private-branch <branch>` | Branch of the engine-private repo to clone on the node. | | `--bootstrap-http-server-run` | Runs a temporary bootstrap HTTP server for generic purposes such as serving iPXE scripts or ISO images during commissioning. | | `--bootstrap-http-server-path <path>` | Sets a custom bootstrap HTTP server path for baremetal commissioning. | | `--bootstrap-http-server-port <port>` | Sets a custom bootstrap HTTP server port for baremetal commissioning. | | `--iso-url <url>` | Uses a custom ISO URL for baremetal machine commissioning. | | `--nfs-build` | Builds an NFS root filesystem for a workflow id config architecture using QEMU emulation. | | `--nfs-mount` | Mounts the NFS root filesystem for a workflow id config architecture. | | `--nfs-reset` | Resets the NFS server completely, closing all connections before reloading exports. | | `--nfs-unmount` | Unmounts the NFS root filesystem for a workflow id config architecture. | | `--nfs-build-server` | Builds the NFS server for a workflow id config architecture. | | `--nfs-sh` | Copies QEMU emulation root entrypoint shell command to the clipboard. | | `--cloud-init` | Sets the kernel parameters and sets the necessary seed users on the HTTP server. | | `--cloud-init-update` | Updates cloud init for a workflow id config architecture. | | `--ubuntu-tools-build` | Builds ubuntu tools for chroot environment. | | `--ubuntu-tools-test` | Tests ubuntu tools in chroot environment. | | `--rocky-tools-build` | Builds rocky linux tools for chroot environment. | | `--rocky-tools-test` | Tests rocky linux tools in chroot environment. | | `--bootcmd <bootcmd-list>` | Comma-separated list of boot commands to execute. | | `--runcmd <runcmd-list>` | Comma-separated list of run commands to execute. | | `--logs <log-id>` | Displays logs for log id: dhcp,dhcp-lease,dhcp-lan,cloud-init,cloud-init-machine,cloud-init-config | | `--dev` | Sets the development context environment for baremetal operations. | | `--ls` | Lists available boot resources and machines. | | `--resume-infra-setup` | Skip commissioning, OS install, and all bootstrapping; resume only the SSH-based infra setup (kubeadm join/init) on a node that already has the OS installed and is reachable via SSH. | | `--resume-join` | Skip everything except the kubeadm join command. Assumes engine, Node.js, CRI-O, kubelet, and kubeadm are already installed. Only retrieves a fresh join token from the control-plane and runs kubeadm join. | | `-h, --help` | display help for command | --- ### underpost release Release orchestrator for building new versions and deploying releases of the Underpost CLI. **Usage:** `underpost release [options] [version]` #### Arguments | Argument | Description | | --- | --- | | `version` | The new version string to set (e.g., "3.1.4"). Defaults to current version. | #### Options | Option | Description | | --- | --- | | `--build` | Builds a new version: tests template, bumps versions, rebuilds manifests and configs. | | `--deploy` | Deploys the release: syncs secrets, commits, and pushes to remote repositories. | | `--ci-push <deploy-id>` | Local equivalent of engine-*.ci.yml: builds dd-{deploy-id} and pushes to the engine-{deploy-id} repository. Accepts the suffix (e.g., "cyberia"), "dd-cyberia", or "engine-cyberia". | | `--message <message>` | Commit message for --ci-push or --pwa-build (defaults to last commit of the engine repository). | | `--pwa-build` | Runs the pwa-microservices-template update flow: always re-clones, syncs engine sources, installs, builds, and pushes. | | `--dry-run` | For --build: previews version-bump changes (per-file substitution counts) without writing files or running downstream commands. | | `--mongo-host <host>` | For --build: override DB_HOST in the template .env.example for the smoke test (e.g., "192.168.1.82:27017"). | | `--mongo-user <user>` | For --build: override DB_USER in the template .env.example for the smoke test. | | `--mongo-password <password>` | For --build: override DB_PASSWORD in the template .env.example for the smoke test. | | `--valkey-host <host>` | For --build: override VALKEY_HOST in the template .env.example for the smoke test (e.g., "192.168.1.82"). | | `-h, --help` | display help for command | ---