Pillar CLI

Build from source

For users with access to a Pillar source checkout, building requires Go 1.25 or newer. From the repository root, run:

cd apps/cli
go build -o pillar ./cmd/pillar
./pillar help
./pillar version --json

Run the CLI on the Linux storage host you want to inspect, with the Docker command available and permission to access its daemon. A binary built on another operating system or architecture is not automatically suitable for that host. The examples use ./pillar from the build directory.

Available commands

./pillar version

Print the CLI version. Does not access Docker.

./pillar preflight

Identify the host platform and check Docker daemon access. This preliminary check does not validate storage-device access or Observer kernel support.

./pillar status

Inspect the pillar-agent and pillar-observer containers. A running container does not by itself establish successful pairing or a fresh heartbeat.

./pillar logs agent --tail 100

Read a bounded snapshot of Agent logs. Use observer instead of agent for Observer logs.

./pillar install agent --claim-stdin --api-url <url>

Pair this host: verify the signed release, pull and launch the Agent, wait for a heartbeat, then remove the one-time claim token from the running container's config. The one-time claim token for --claim-stdin is generated in Settings → Agent Pairing; the hosted install command fetches and runs the CLI for you.

./pillar install observer

Best-effort install of the optional Observer sidecar alongside an already-installed Agent.

./pillar update agent

Verify and atomically activate a newer signed Agent release, with automatic rollback on a failed health check.

./pillar rollback agent

Return the Agent to its last known-good release.

./pillar config agent get

Inspect Agent configuration (proxy, auto-update, health-check timeout). Proxy URLs are redacted before display.

./pillar config agent set PILLAR_AUTO_UPDATE=true

Validate and apply Agent configuration changes with automatic rollback if a container restart fails.

./pillar uninstall agent --yes --purge

Remove the Agent installation, all containers and images, configuration, and (with --purge) the credential volume. The node becomes stale on the dashboard until manually removed.

Logs default to 100 lines; --tail accepts 0 through 10000. Read-only commands default to a 15-second timeout; install/update/rollback default to 15 minutes, since a manifest fetch, an image pull, and a heartbeat wait can all be slow. Continuous log streaming is not available.

./pillar status --json --timeout 30s
./pillar logs observer --tail 200 --timeout 30s

Results and automation

Use --json for the versioned pillar.cli/v1 response envelope. Exit code 0 means success, 1 means an operational failure (including a failed install, update, or rollback), and 2 means invalid usage or an unavailable command. Check the exit code and reported findings before proceeding.

If Docker cannot be reached, check that its daemon is running and that your user has access. A missing Agent or Observer container is different from a Docker access failure. Confirm pairing and current telemetry separately in the Pillar dashboard.

Platform limits

Platform detection covers Ubuntu, Debian, generic Linux, Unraid, TrueNAS SCALE, and Synology DSM. Detection is not certification of installation, reboot persistence, updates, or Observer support. Review the preflight findings for your host; NAS versions and available Docker services differ.

A verified install/update/rollback on a supported platform still requires Docker and the same host access `docker run` would need. For current runtime requirements and Observer capabilities, see the Agent & Observer reference.