Getting Started

Getting Started

Install

pip install squarepeg

This installs the squarepeg console script plus its runtime dependencies: click, kubernetes (the official Python client), and PyYAML.

Working on squarepeg itself instead of just using it? See Development for an editable install from a checkout of the repo.

Prerequisites

• A working kubectl-style kubeconfig — squarepeg uses the exact same resolution kubectl does ($KUBECONFIG, then ~/.kube/config, current context). If kubectl get pods works, squarepeg will too. (Running squarepeg itself as a container, with no kubeconfig at all? It falls back to the pod's own service account — see Execution Lifecycle → Connect to the cluster.)
• Permission in your target namespace to create/watch/delete Pods (and Jobs, if you use --mode job).

Your first run

squarepeg run alpine echo "hello from a pod"

squarepeg will:

1. Print which kubeconfig context and namespace it's using (to stderr, unless --quiet).
2. Build and create a Pod manifest.
3. Wait for the container to start, failing fast if the image can't be pulled.
4. Stream the container's stdout/stderr to your terminal as it runs.
5. Wait for the container to terminate.
6. Delete the Pod.
7. Exit with the container's exit code.

A few things to try immediately

See what would be created without touching the cluster:

squarepeg run --dry-run --cpus 0.5 -m 512m -e FOO=bar alpine echo hi

This prints the exact Pod manifest YAML — no cluster connection required at all. See Execution Lifecycle for details.

Run as a Job instead of a Pod:

squarepeg run --mode job alpine echo hi

Keep the resource around afterwards for debugging:

squarepeg run --keep --name debug-me alpine sh -c "exit 7"
kubectl describe pod debug-me

See your fully resolved config (useful once you have config files layered):

squarepeg config

Input / output

stdout	The container's stdout, streamed live as raw bytes — no line buffering, re-encoding, or decoding, so ANSI colour and \r progress bars come through correctly.
stderr	Interleaved into the same stream as stdout by default (docker logs-style splitting is opt-in via split_streams in config, and depends on a Kubernetes apiserver feature gate not universally enabled).
stdin	-i/-t are accepted, but stdin is never actually forwarded — squarepeg only reads the container's log output; there's no real interactive attach. A container that blocks waiting on stdin will hang.
squarepeg's own messages	Always printed to stderr, never mixed with container output — squarepeg run alpine cat file.txt > out.txt captures exactly the container's stdout. Suppress with --quiet. Coloured, and animated with a spinner on a real terminal for stages that can take a while (image pull, waiting for the container to start/finish, cleanup, orphan sweep) — see CLI Reference → Colour and progress output. Colour and animation are both automatically off when stderr isn't a terminal (e.g. under capsys/CI, or piped to a file), and both are fully suppressed by --quiet.
exit code	Mirrors the container's own exit code verbatim (including 137 for an OOM kill, with the OOMKilled reason additionally printed to stderr since a bare 137 is opaque). 125 means squarepeg itself failed to run the container to completion, not the container's own code.

See Docker Compatibility for the full list of divergences from docker run, and Execution Lifecycle → Stream logs for how log streaming actually works under the hood.

Next steps

• CLI Reference for the full flag list.
• Configuration once you want to stop repeating --cpus/--memory/namespace/etc. on every invocation, or need to set Kubernetes fields squarepeg has no dedicated flag for (node selectors, tolerations, service accounts, PVCs, ...).
• Docker Compatibility to see exactly which docker run flags are supported, and what to do instead for the ones that aren't.