Pi SSH Command Cheat Sheet

Common commands for checking Wi-Fi, network, services, Cloudflare Tunnel, CUPS, printer readiness, logs, and local print-server health on the Raspberry Pi.

Start With Diagnostics Wi-Fi Services Logs Printer
Tip: Run read-only checks first. Restart commands are marked with sudo, and destructive commands are marked with careful.

Start Here: One-command Diagnostics

Best first command when SSH still works. It captures Wi-Fi, DNS, services, journals, CUPS, USB printer presence, and tunnel status.

sudoFull project diagnostics

Use this when the repo is installed under /opt.

sudo bash /opt/clayproject-print-server/scripts/pi-diagnose.sh

sudoSave diagnostics to a file

Useful when debugging remotely or sharing output later.

sudo bash /opt/clayproject-print-server/scripts/pi-diagnose.sh 2>&1 | tee ~/print-server-diagnostics.txt

sudoDiagnostics from repo checkout

Use this if you are in the cloned project directory.

sudo bash scripts/pi-diagnose.sh

System Basics

safeWho and where am I?

Basic identity, hostname, OS, uptime, time sync.

whoami
hostname
uname -a
uptime
timedatectl status --no-pager

safeDisk, memory, CPU load

Quick resource check for low storage or memory pressure.

df -h
free -h
top -b -n 1 | head -40

safeProcesses related to printing

Look for the API server, CUPS, Ghostscript, and cloudflared.

ps aux | grep -E 'clayproject|cups|cloudflared|gs' | grep -v grep

Wi-Fi and Saved Networks

safeCurrent SSID

Shows the Wi-Fi network the Pi is currently using.

iwgetid -r

safeWi-Fi link details

Signal strength, connected AP, bitrate, and interface details.

iw dev wlan0 link
ip -brief addr show wlan0

safeNetworkManager overview

Device state and saved Wi-Fi connection profiles.

nmcli device status
nmcli -f NAME,TYPE,AUTOCONNECT connection show

sudoShow saved Wi-Fi password

Replace the connection name with the exact name from nmcli connection show.

sudo nmcli -s -g 802-11-wireless-security.psk connection show "Your-WiFi-SSID"

safeScan nearby Wi-Fi networks

Useful if the expected studio network is not visible.

nmcli device wifi list

safewpa_supplicant fallback

Only useful on older Raspberry Pi OS setups.

wpa_cli -i wlan0 status
sudo sed -n '/network={/,/}/p' /etc/wpa_supplicant/wpa_supplicant.conf

DNS, Routing, and Internet

safeAddresses and routes

See the Pi's IP addresses and default gateway.

ip -brief addr
ip route

safeDNS checks

Confirms DNS resolution for the public hostname and Cloudflare.

getent hosts printer.clayproject.at
getent hosts cloudflare.com

safeInternet connectivity

Cloudflare trace shows outbound HTTPS connectivity and location info.

curl -fsS --max-time 10 https://www.cloudflare.com/cdn-cgi/trace

safeListening ports

Checks whether the local API is listening on port 3000.

ss -tlnp | grep -E '(:3000|cloudflared)' || ss -tlnp

Service Status

safeMain services

Print server API, Cloudflare Tunnel, and CUPS status.

systemctl --no-pager status clayproject-print-server cloudflared cups

safeShort active/inactive view

Compact status for quick checks.

systemctl is-active clayproject-print-server cloudflared cups
systemctl is-enabled clayproject-print-server cloudflared cups

sudoRestart services

Use after changing config or when a service is stuck.

sudo systemctl restart clayproject-print-server
sudo systemctl restart cloudflared
sudo systemctl restart cups

sudoEnable services at boot

Use this if services do not start after reboot.

sudo systemctl enable cloudflared clayproject-print-server cups

Journals and Logs

safeFollow live logs

Press Ctrl+C to stop following.

journalctl -u clayproject-print-server -f
journalctl -u cups -f
journalctl -u cloudflared -f

safeRecent print-server logs

Most useful when local /health or /ready fails.

journalctl -u clayproject-print-server -n 120 --no-pager

safeRecent Cloudflare logs

Use for 1033 errors, reconnect loops, or auth/config issues.

journalctl -u cloudflared -n 160 --no-pager

safeRecent CUPS logs

Use for stuck jobs, printer offline, or USB printer issues.

journalctl -u cups -n 120 --no-pager

Print-server HTTP Health

safeLocal health checks

/health checks process and CUPS. /ready checks printer readiness.

curl -s http://127.0.0.1:3000/health | jq
curl -s http://127.0.0.1:3000/ready | jq

safeVerbose local checks

Use when the compact command is not enough.

curl -sv --max-time 10 http://127.0.0.1:3000/health
curl -sv --max-time 10 http://127.0.0.1:3000/ready

safePublic tunnel health

If local works but public fails, focus on cloudflared.

curl -sv --max-time 20 https://printer.clayproject.at/health

Cloudflare Tunnel

safeTunnel status and logs

First commands for public hostname failures.

systemctl --no-pager status cloudflared
journalctl -u cloudflared -n 120 --no-pager

sudoTunnel details

Shows the configured tunnel and route information.

sudo cloudflared tunnel list
sudo cloudflared tunnel info clayproject-print-server

sudoRe-setup cloudflared

Use if the tunnel points at the wrong hostname/origin.

sudo bash /opt/clayproject-print-server/scripts/pi-setup-cloudflared.sh

CUPS and Printer

safePrinter state

Checks the configured CUPS printer and its URI.

lpstat -p PM-241-BT
lpstat -v PM-241-BT

safePrint queue

Shows pending or stuck jobs.

lpstat -o

safeUSB printer presence

The Phomemo USB ID used by this project is 2e3c:5750.

lsusb
lsusb -d 2e3c:5750

carefulCancel all print jobs

This clears every queued CUPS job.

cancel -a

Config Files

sudoPrint server environment

Shows local config. Avoid sharing raw secrets from this output.

sudo sed -E 's/(API_KEY=).*/\1<redacted>/; s/(PRINT_SERVER_API_KEY=).*/\1<redacted>/' /etc/clayproject-print-server/env

sudoCloudflared config

Confirms hostname, tunnel, credentials file, and origin service.

sudo sed -E 's/(credentials-file:[[:space:]]*).*/\1<redacted>/' /etc/cloudflared/config.yml

sudoEdit print-server env

Restart the service after changing this file.

sudo nano /etc/clayproject-print-server/env
sudo systemctl restart clayproject-print-server

Recovery Actions

These change runtime state. Use them after reading status and logs.

sudoField kit restart

Restart the core stack, then run diagnostics.

sudo systemctl restart cloudflared clayproject-print-server cups
sudo bash /opt/clayproject-print-server/scripts/pi-diagnose.sh

sudoReboot Pi

Last resort when services are stuck or USB state looks broken.

sudo reboot

carefulStop public access

Safe rollback if you need the public tunnel offline.

sudo systemctl stop cloudflared
sudo systemctl stop clayproject-print-server

Remote Access

safeTailscale status on Pi

Independent fallback path from Cloudflare Tunnel.

systemctl --no-pager status tailscaled
tailscale status
tailscale ip

safeConnect from Mac via Tailscale

Run this on your Mac, not inside the Pi SSH session.

tailscale status
tailscale ssh <pi-user>@clayproject-print-server

sudoSet up Tailscale SSH

Use once if Tailscale SSH is not configured yet.

sudo bash /opt/clayproject-print-server/scripts/pi-setup-tailscale-ssh.sh

For deeper explanations, see docs/runbook.md. This page is static and can be opened directly in a browser.