CLI Reference

CLI Reference

squarepeg run [OPTIONS] IMAGE [COMMAND...]
squarepeg config show [OPTIONS]
squarepeg --version

Once IMAGE is reached, everything after it — including tokens that look like flags — is passed straight through to the container as COMMAND, exactly like docker run:

squarepeg run alpine ls --color -la     # --color and -la go to `ls`, not to squarepeg

squarepeg run — all flags

Container basics

Flag	Description
-e, --env KEY=VALUE	Set an environment variable in the container. Repeatable. A bare -e KEY (no =) inherits the value from your local shell's environment, docker-style — errors if that variable isn't set locally.
-v, --volume SPEC	Mount a volume. Repeatable. See the volume forms table below.
--name NAME	Pod/Job name. Must be a valid lowercase RFC1123 label (alphanumeric + -, ≤63 chars). If omitted, squarepeg generates one from the image name plus a random suffix (e.g. squarepeg-alpine-a1b2c3).
-w, --workdir PATH	Container working directory.
--entrypoint CMD	Override the image's ENTRYPOINT (maps to Kubernetes command). See why this exists.
-i, --interactive	Accepted, but stdin is never actually forwarded — the log endpoint squarepeg reads from is read-only. See Docker Compatibility.
-t, --tty	Sets tty: true on the container (better line-buffering/colour in streamed output). If passed without -i, squarepeg auto-enables stdin too and warns — some clusters reject tty without stdin, and a process that then blocks reading stdin will hang.
--rm	Accepted as a no-op — cleanup is already the default. Errors if combined with --keep.
--pull always|missing|never	Sets imagePullPolicy to Always / IfNotPresent / Never respectively.
--container-name NAME	Name of the container inside the Pod. Default main.

Resources

Flag	Units	Description
--cpus VALUE	docker-style (e.g. 0.5, 2)	Sets both CPU request and limit, converted to millicores (0.5 → 500m).
-m, --memory VALUE	docker-style (e.g. 512m, 1g)	Sets both memory request and limit, converted to the equivalent binary k8s quantity (512m → 512Mi — see why this matters).
--request-cpu VALUE	k8s-native (e.g. 500m)	CPU request only, passed through verbatim.
--limit-cpu VALUE	k8s-native	CPU limit only, passed through verbatim.
--request-memory VALUE	k8s-native (e.g. 512Mi)	Memory request only, passed through verbatim.
--limit-memory VALUE	k8s-native	Memory limit only, passed through verbatim.

Explicit --request-*/--limit-* flags override the --cpus/--memory shorthand for the side they name — e.g. --memory 1g --limit-memory 2g gives a 1Gi request and a 2Gi limit.

Where and how it runs

Flag	Description
--mode pod|job	Create a Pod (default) or a Job. See Execution Lifecycle for the difference.
-n, --namespace NAME	Target namespace. Falls back to config, then the kubeconfig context's namespace (or the in-cluster service account's namespace — see Execution Lifecycle → Connect to the cluster), then default.
--context NAME	kubeconfig context to use, instead of the current one. If this fails to load, squarepeg does not fall back to in-cluster config — see Execution Lifecycle → Connect to the cluster.
--timeout SECONDS	How long to wait for the container to start (image pull, scheduling, container creation) before giving up. Default 300. Once the container is running, log streaming and the wait for completion are unbounded — this timeout only bounds startup.

Lifecycle

Flag	Description
--keep	Don't delete the Pod/Job after it finishes. Prints the kubectl describe/kubectl logs commands to inspect it.
--dry-run	Print the fully-resolved manifest as YAML and exit, without creating anything or requiring a reachable cluster at all.
--dry-run-server	Like --dry-run, but additionally validates the manifest against the apiserver. (Not yet implemented — reserved for a future release.)
--quiet	Suppress squarepeg's own status/progress messages (still prints container output).

Config

Flag	Description
--config PATH	Load an additional config file layer. Repeatable; later --config flags win over earlier ones. See Configuration.
--no-default-config	Skip ~/.config/squarepeg/config.yaml even if it exists — useful for a hermetic, reproducible resolution (e.g. in CI or when debugging).
--profile NAME	Select a named profile from the merged config, deep-merged over everything else.

squarepeg config show

squarepeg config show [--config PATH]... [--no-default-config] [--profile NAME]

Prints:

• to stderr: every config file that was loaded, in the order it was merged (or no config files loaded if none were found).
• to stdout: the fully merged, resolved config as YAML — including ${VAR} interpolation already applied.

Use this to debug "why is my namespace/resource/whatever what it is" once you have more than one config layer in play.

Volume forms

Form	Example	Result
Anonymous	-v /data	emptyDir volume mounted at /data. Scratch space only — gone when the Pod/Job is deleted.
Named, config-defined	-v refdata:/ref	Looks up volumes.refdata in your resolved config (a PVC, emptyDir with a size limit, etc.) and mounts it at /ref.
Named, undeclared	-v scratch:/tmp/x	Falls back to emptyDir if scratch isn't declared in config — matches docker's "just works" ergonomics for named volumes, but doesn't persist between runs the way a real docker named volume would.
Host bind mount	-v /host/path:/container/path	Rejected by default — there's no "host" to bind to on a remote cluster. Errors with a suggestion to use a config-defined PVC-backed volume, or set allow_host_path_mounts: true in config if you're genuinely targeting a local cluster (e.g. kind/minikube).
Read-only/read-write suffix	-v refdata:/ref:ro	Any of the above, plus :ro or :rw to set readOnly on the mount.

Not every mounted volume comes from -v at all. A config's volumes.NAME entry can declare mount_path, which mounts it automatically on every run with no -v flag needed — see Configuration → Volumes. If a user's -v references a volume that's already auto-mounted this way, both mounts coexist in the container at their respective paths.

Exit codes

Code	Meaning
container's own exit code	The container ran and exited; squarepeg reports that code verbatim (including e.g. 137 for an OOM kill — squarepeg also prints the OOMKilled reason to stderr since a bare 137 is opaque).
2	Usage error: bad flag value, unsupported flag, malformed config.
125	squarepeg itself failed to run the container to completion (couldn't create the resource, image pull failure, startup timeout, couldn't determine the exit code, etc.) — matches docker run's own convention for "the runner failed", as distinct from the container's own exit code.
130	Interrupted (Ctrl+C / SIGTERM) — 128 + SIGINT, standard shell convention.

See Troubleshooting for the full table of specific failure conditions and what squarepeg tells you about each one.