The Terminal Guide

copal The installer, on the machine itself: re-run any stage, update Copal, and see what is installed.

Copal · Copal's own · stage 3 · Move the root filesystem onto the card, or a disk of its own

On Copal: Stage 3 leaves this copy on every Copal machine, so the whole install -- eighteen stages -- can be re-run, one stage or all of them, and updated from the repository without the Mac.

Use

With no arguments it shows the stage menu. --stage N re-runs chosen stages; -U updates Copal's scripts from the repository (or from a local checkout); --check says whether an update exists. Updating changes what the stages will do; it does not run them. copal fleet is the fleet console.

Examples

Options

--stage N,...

run only these stages (add --auto to answer their questions)

--auto

every stage, unattended, resuming across reboots

-U [REF]

update from the repository; REF a branch, tag or commit

-U --from PATH

update from a checkout on this machine

--check [REF]

whether an update is available; changes nothing

--version

the installed version and its source

fleet VERB ...

the fleet console, from the checkout in ~/code/copal

Notes

• Every stage is written to be run again: a re-run repairs or updates what it set up and leaves the rest alone.
• An update keeps the previous copy as copal-init.sh.bak.
• -U REF pins a version: a tag or commit goes back to an older Copal.
• copal fleet runs tools/copal-fleet.sh from the checkout in ~/code/copal (or $COPAL_CHECKOUT), because the console needs the checkout around it. On the Mac or Linux host that holds the fleet's authority, make install-fleet in the checkout adds the same command.

See also copal-store, copal-config, copal-code

copal-apps Copal Apps: the window for browsing Copal's programs by shelf, installing them, and watching installs happen.

Copal · Copal's own · stage 18 · The Copal Store, and OpenShot compiled

On Copal: The graphical face of copal-store. It never installs anything itself and never needs root: Install opens a terminal running doas copal-store install, and the window follows the progress. At the full monty's first login it opens on the slideshow of the queued programs arriving.

Use

Open it from the menu or the command line. Shelves on the left, programs with their status in the middle, one program in full on the right: its picture, two sentences, where it comes from and how it installs. While an install runs, it shows each program arriving with three progress bars.

Examples

Options

ID

open on that program

--progress

the running install's slideshow: the run, the program, the step

--follow

the same, but only when an install is queued or running

Notes

• Everything it shows comes from copal-store (copal-store rows, copal-store playbook ID) and the event stream it writes to /var/log/copal/events: the terminal and the window always agree.
• Pictures are the gallery's, fetched once into ~/.cache/copal-apps; a program without one shows its icon.
• It needs a desktop (GTK); on a console, copal-store alone gives the same shelves as terminal menus.

See also copal-store, copal-install, copal-menu

copal-audio-start Start the sound server -- PipeWire, WirePlumber and the PulseAudio shim -- for this login.

Copal · Copal's own · stage 10 · Wireless, audio, capture and disks

On Copal: On Copal there is no systemd to start PipeWire per user, and it must not run as a system service. This starts the three parts once per session, skipping any already running, and does nothing at all on a machine without PipeWire.

Use

The i3 session runs it at startup. Run it by hand when a program says there is no sound server; it is safe to run again.

Examples

Options

Notes

• It starts pipewire, then wireplumber (the session manager, which connects devices) and pipewire-pulse (so PulseAudio programs play), each only if installed and not already running for your user.
• Their output goes to copal-audio.log in $XDG_RUNTIME_DIR (or /tmp), which is cleared at reboot.
• Stage 10 installs PipeWire and writes this; the i3 session's startup file is what calls it.

See also wpctl, pipewire, pactl

copal-autologin What tty1 runs instead of the login prompt when the desktop starts at boot.

Copal · Copal's own · stage 4 · X.Org, i3, a terminal and a browser

On Copal: Autologin without a display manager: getty skips the name, this logs the admin user straight in. It also raises the memory-lock and real-time limits audio programs want, which nothing else on Copal can do, because logins here do not go through PAM.

Use

You do not run it. Stage 4 offers to start the desktop at boot; saying yes writes this and points tty1 at it in /etc/inittab.

Examples

Options

Notes

• The inittab line is getty -n -l /usr/local/bin/copal-autologin; it runs login -f for the admin user, so no password is asked on tty1. That is the point, and also the cost: whoever is at the keyboard is in.
• It sets ulimit -l unlimited (locked memory, which keeps Ardour's and JACK's buffers out of swap) and ulimit -r 95 (real-time priority); the desktop inherits both.
• After logging in, ~/.profile waits five seconds and runs copal-session; Ctrl-C in those seconds gives you a shell instead.
• Deleting /etc/copal/autostart-desktop stops the desktop starting at boot, but the autologin stays: tty1 logs in to a shell. Undoing that means putting tty1's getty line in /etc/inittab back.

See also copal-session, getty, ulimit

copal-bar Start the desktop's bar and widgets with whichever shell the machine has: quickshell, else waybar.

Copal · Copal's own · stage 4 · X.Org, i3, a terminal and a browser

On Copal: The theme's bar is written for quickshell, which Alpine does not package, so waybar stands in. copal-bar is the one place that decides, and prefers quickshell: install it and the next login uses the real thing, with nothing else changed.

Use

The session starts it; you run it by hand only to restart a bar that has gone. It starts the bar and the desktop widgets.

Examples

Options

Notes

• The waybar configuration is in ~/.config/waybar; copal-theme rewrites its colours, so keep your own changes to layout and modules.
• If neither shell is installed it says so where it will be seen, rather than leaving a desktop with no bar and no explanation.

See also copal-widgets, copal-theme

copal-build Compile the checkouts in ~/code and install what they make into ~/.local/bin, by the shape of each project.

Copal · Copal's own · stage 7 · Compilers, editors, Claude Code and the ~/code checkouts

On Copal: "Built" should mean "installed": on PATH, in the menus, with a man page. copal-build reads each checkout's shape -- CMake, Cargo, Go, npm, or a cc65 Makefile -- and builds it the way that shape builds, so a fork or a project it has never heard of works the same.

Use

With no argument it builds every checkout in ~/code; name some to build only those. list shows each checkout's shape and whether what it made is on PATH.

Examples

Options

(none)

build every checkout

NAME...

build only these (directory names under ~/code)

list

each checkout, its shape, and the programs it made

clean NAME...

delete build/, native/build/ and target/; keep the checkout

-h, --help

the usage

Notes

• Programs go to ~/.local/bin, which is on PATH from ~/.profile. Each gets a menu entry, and, from its README, a man page in ~/.local/share/man (man ytq), by copal-readme-man.
• It never modifies a tracked file, because that would make every later git pull fail: npm uses ci where there is a lockfile, and a Plus/4 program uses its committed .prg and .d64 instead of recompiling. COPAL_BUILD_PLUS4=1 recompiles anyway (needs cc65).
• Parallel jobs are the CPU count, capped at one per 512 MB of memory, so a small board does not swap.
• copal itself is not built: it is a script (make redeploy in ~/code/copal). A checkout with none of the shapes is left alone.
• COPAL_CODE and COPAL_PREFIX change ~/code and ~/.local.

See also copal-code, copal-readme-man, cargo, cmake

copal-camera Open the camera application, whichever one this machine has.

Copal · Copal's own · stage 4 · X.Org, i3, a terminal and a browser

On Copal: One answer to "the camera", asked from three places -- the Camera entry in copal-menu, Super+Shift+B on both desktops, and the camera role in a copal-desk layout. Birdshot first, from ~/code; then other camera programs.

Use

Run it, or press Super+Shift+B; it opens the first camera program it finds: birdshot's window, else birdshot's browser viewfinder, else another installed camera application. --which says which, and opens nothing.

Examples

Options

--which

print the command it would run; exit 1 if there is none

Notes

• $CAMERA overrides the choice, as $BROWSER does for the browser: set it in ~/.profile.local and every place that opens "the camera" follows.
• Birdshot is one of the checkouts stage 7 builds into ~/.local/bin; copal-camera looks there even when the session did not read ~/.profile.

See also birdshot, copal-desk

copal-center One window listing the whole catalogue, installed or not, with the action for each.

Copal · Copal's own · stage 4 · X.Org, i3, a terminal and a browser

On Copal: Super+Shift+C: the catalogue at a glance. It opens Copal Apps where that exists, and the store's own window where it does not.

Use

Open it with Super+Shift+C or by name. Each row is a program with its status and section; choosing one runs it if installed, or installs it.

Examples

Options

Notes

• It is the older window of the two; Copal Apps (copal-apps) is the richer one, and copal-center hands over to it where it is installed.

See also copal-apps, copal-store, copal-install

copal-clip One clipboard, one set of keys, every window -- with a history, and a bridge to the VM host.

Copal · Copal's own · stage 4 · X.Org, i3, a terminal and a browser

On Copal: Super+C, Super+X and Super+V copy, cut and paste in every program, terminal included, the way Cmd-C does on a Mac. It keeps a clipboard history, and in a VM shares the clipboard with the host.

Use

The desktop binds the keys; you rarely run it by name. From a shell, store puts text on the clipboard and show prints it, which makes it the pipe between the clipboard and commands.

Examples

Options

copy / cut / paste

the Super+C / Super+X / Super+V actions

history

choose from the clipboard history

store

put stdin on the clipboard

show

print the clipboard

watch

record the history (the session starts this)

bridge

share the clipboard with the VM host (the session starts this)

Notes

• In a UTM or QEMU guest, copy and paste with the Mac works only while copal-clip bridge and spice-vdagent are running; both are started from hyprland.conf. If it stops working, check those two first.
• The history keeps the last 100 entries, in ~/.cache/copal/clipboard; delete that folder to clear it.

See also wl-copy, ytq

copal-code Keep the source checkouts in ~/code: clone what is listed, pull what is there, then build it all.

Copal · Copal's own · stage 7 · Compilers, editors, Claude Code and the ~/code checkouts

On Copal: A Copal machine arrives ready to work on its own projects. The list of repositories lives on the boot partition, where you can edit it from any computer before the card is even booted; this makes ~/code match it, and hands over to copal-build.

Use

Run it as yourself, with no argument: it clones anything listed that is missing, pulls (fast-forward only) anything that is there, and builds. add and rm edit the list and need doas.

Examples

Options

(none), sync

clone what is missing, pull what is there, then copal-build

list

each listed repository, and whether it is cloned

add URL...

add to the list (needs doas)

rm NAME...

remove from the list (needs doas); keeps the checkout

path

where the list is

Notes

• The list is copal-repos on the boot partition (/boot), one URL per line, # for comments.
• ~/code/copal, the repository the machine was built from, is always included and cannot be removed; repoint it with git remote set-url.
• Cloning tries SSH first, without prompting, and falls back to HTTPS; a machine with no SSH key yet still gets its checkouts. copal-guide code explains adding a key.
• A pull never forces: a checkout with local changes is warned about and left alone. A directory in the way that is not a checkout is skipped.
• Machines installed before 24 September 2026 have the Yodacon builder under this name; running stage 7 again installs this one, and the builder as copal-yodacon.

See also copal-build, git, copal-guide

copal-config System settings for Copal: users, host name, time zone, keyboard, SSH, services, boot and storage.

Copal · Copal's own · stage 4 · X.Org, i3, a terminal and a browser

On Copal: raspi-config's job, done with Copal's own tools: the settings a Pi owner changes, in one place, in a window on the desktop or in the terminal on a console.

Use

Run it; it opens a window where there is a display and terminal menus where there is not. Choose a screen, change a setting. Most settings write to /etc, so it asks for doas when it needs to.

Examples

Options

--tui

the terminal interface, even with a display

--help

the usage

Notes

• Its screens: users (add one, groups), hostname, timezone, keymap, ssh, services (what starts at boot), boot, storage, and about.
• Each screen uses the same tools a shell would -- setup-timezone, rc-update, copal-ssh -- so a change made here and one made by hand agree.
• It works with GTK (yad), curses (dialog), or plain prompts, whichever the machine has.

See also copal-ssh, setup-alpine, rc-update

copal-debug Turn on Copal's debug collection: one folder, /var/log/copal, holding everything worth reading about a fault.

Copal · Copal's own · written on every run of the installer

On Copal: Off by default, because on a working machine the extra writes buy nothing. When something is wrong, one command gathers a snapshot of the machine and links to every relevant log in one place -- readable over SSH, or bundled into one file to send to someone.

Use

doas copal-debug on 1d starts collecting and switches itself off after a day. copal-debug alone says whether it is on and what it has gathered. bundle makes a .tar.gz to copy off the machine.

Examples

Options

status

whether it is on, and what is in the folder (the default)

on [TIME]

start collecting; TIME (1d, 12h, 30m, or seconds) ends it

off

stop collecting, leave the folder

collect

refresh the snapshot

bundle

tar the folder, links resolved, into /tmp

purge

delete /var/log/copal

expire

switch off if the deadline has passed (cron runs this)

Notes

• The folder holds sysinfo.txt (kernel, consoles, graphics, input, gettys, services, which Copal), dmesg.log, and links to the install transcript, the system log, Xorg's log and the last desktop session. A broken link is a finding: xorg.log pointing nowhere means X never started.
• COPAL_DEBUG=1 or =0 in the environment overrides the switch for one command. The switch itself is the file /etc/copal/debug.
• With debug on, copal-startx keeps ten session logs instead of two.

See also copal-logs, copal-startx, copal-gpu

copal-desk Put the workspaces into a known shape in one step: editor, terminal, browser, each where it belongs.

Copal · Copal's own · stage 4 · X.Org, i3, a terminal and a browser

On Copal: Super+Shift+D. Muscle memory needs things in the same place, so a layout file names what opens on which workspace, and one key lays the desk out. Deliberately not an autostart: you can decline it on the morning you want an empty machine.

Use

Run it (or press Super+Shift+D) and it opens what the layout names on the workspaces it names, without pulling your eyes along. The default layout is code; others are files you can write.

Examples

Options

NAME

lay out that layout (default: code)

--list

the layouts available

--show NAME

print a layout without running it

Notes

• Layouts are NAME.layout files in /usr/local/share/copal/layouts (Copal's) and ~/.config/copal/layouts (yours, which wins over a system one of the same name).
• The code layout: the editor and a terminal on 2, an agent on 3, the browser on 5, and an empty 1 to start from.
• It works on both desktops: Hyprland places each window as it opens; i3 switches workspace first.

See also copal-camera, hyprctl

copal-desktop Choose which desktop takes the screen at the next login: Hyprland (Wayland) or X11.

Copal · Copal's own · stage 4 · X.Org, i3, a terminal and a browser

On Copal: The choice is two settings that must agree: the word in /etc/copal/session, and whether X's setuid server is armed. Setting them in one command means they can never disagree -- and Wayland gets to disarm a root-privileged binary nothing is using.

Use

status (or no argument) shows what is set. wayland and x11 change it, and need doas; the change takes effect at the next login.

Examples

Options

status

the session word, and the X server's state (the default)

wayland

Hyprland at the next login; X's setuid server disarmed

x11

startx at the next login; X's setuid server re-armed

Notes

• wayland refuses, changing nothing, if Hyprland is not installed.
• Disarming removes the setuid bit from /usr/libexec/Xorg.wrap. Xwayland, which runs X programs inside Hyprland, is a separate binary and is not affected.

See also copal-session, copal-startx

copal-fleet A fleet machine's own half of the fleet: what it announces, what it reports, and whether it has been enrolled.

Copal · Copal's own · stage 16 · Join the named fleet, and announce it

On Copal: A Copal fleet is a set of machines on one LAN that trust one certificate authority, run from a console. Each machine needs a small, readable program for its side -- announcing itself, reporting its health, taking part in choosing the warden -- and this is it.

Use

copal-fleet alone says what this machine thinks it is: its fleet, role, tags, scene, and whether it is enrolled. The other verbs are mostly for the console and the services; facts and state are good for a quick look.

Examples

Options

status

fleet, node, role, score, tags, scene, authority, enrolment (the default)

state

one line of facts, for the console

facts

id, versions, uptime, memory, temperature, card use, certificate days...

id

the node's name

role

node or warden (or the pinned role)

score

this node's score in the warden election

elect

recompute the role

beacon

rewrite the mDNS announcement

watch

elect and rewrite the beacon every 4 minutes (the service)

browse

the fleet machines visible from here

install-cert

install a host certificate read from stdin (root)

bus-key

this node's bus identity, made if needed

bus-users

write the bus membership from stdin (warden, root)

bus-config

rewrite /etc/nats/nats.conf (warden, root)

bus-address

where the bus is

bus-state

what this node's part of the bus is doing

logs ID|all [DAYS]

the logs the warden has collected, even for a dead node

-h, --help

the usage

Notes

• The fleet console is a different program on the operator's machine: copal fleet (make install-fleet on a Mac or Linux host). It reaches this one through copal-fleet-exec.
• The warden is chosen by a score every node computes and publishes; the highest announcing node takes the role. role-pin in /etc/copal/fleet fixes a role by hand.
• The settings are one file per field in /etc/copal/fleet. Stage 16 installs the program and the copal-fleet service.
• The announcement says a machine is there, never that it is trusted: only its certificate decides that.

See also copal-fleet-exec, copal-fleet-agent, copal-remote, avahi-browse

copal-fleet-agent A fleet machine's standing connection to the fleet's message bus: presence, health and commands, all the time.

Copal · Copal's own · stage 16 · Join the named fleet, and announce it

On Copal: SSH answers when asked; the bus keeps the console's wall live without asking. The agent announces the machine, publishes its state as it changes, and runs commands that arrive on the bus -- through copal-fleet-exec, the same checked list SSH uses, so the bus can never do more than SSH can.

Use

You do not run it; OpenRC does, as the unprivileged copal-fleet account. Check on it with rc-service. --self-test runs its built-in checks without touching the network.

Examples

Options

--self-test

run the built-in checks and exit

Notes

• It publishes hello every 10 seconds, the node's state on change (at most every 5 seconds), new lines of /var/log/copal-fleet.log, and an acknowledgement for every command it ran.
• With no warden (and so no bus), it waits and tries again; that is normal during a handover, and SSH keeps working meanwhile.
• On the warden it also collects every node's log lines, so the logs of a machine that has died can still be read (copal-fleet logs).
• It publishes its own uptime, so the console can tell "the machine is up" from "the agent is alive".

See also copal-fleet, copal-fleet-exec, rc-service

copal-fleet-exec The only thing the fleet console's logins can run: a short, fixed list of verbs, each checked, each logged.

Copal · Copal's own · stage 16 · Join the named fleet, and announce it

On Copal: This is the fleet's security boundary. sshd sends every login by the copal-fleet account here, with no shell, no terminal and no forwarding, and what arrives is matched against a list of verbs rather than run as a command. A verb not on the list is refused and logged -- there is no pass-through.

Use

You do not run it; sshd does, as a forced command, with the console's request in SSH_ORIGINAL_COMMAND. The fleet agent hands bus commands to it the same way. Read it to know exactly what the console can do to a machine.

Examples

Options

state, status, facts, score, id, uptime

reports; nothing changes

beacon

rewrite the mDNS announcement

power off|reboot

shut down or restart

snapshot restore

restore the node's snapshot (if it has copal-snapshot)

scene apply NAME

record the scene name; applying it is Ansible's job

bus key|users|state

the node's bus identity, membership (warden), state

logs ID|all [DAYS]

the warden's collected logs

log tail [N]

the last lines of this node's fleet log

remote start|stop|status

share the screen, bounded (see copal-remote)

message TEXT

put a sentence on the screen (see copal-notify)

Notes

• A message is at most 200 characters of letters, digits, spaces and . , ! ? : and -: no quotes, brackets or slashes, so nothing in it can be read as markup or shell syntax.
• A scene name is lowercase letters, digits and dashes.
• Every request is logged with the caller's address to /var/log/copal-fleet.log; refusals are marked REFUSED.
• Adding a verb means editing this file, and nothing else can add one: the bus agent parses no verbs of its own.

See also copal-fleet, copal-fleet-agent, copal-remote, copal-notify, sshd

copal-fonts Install Copal's font sets -- coding, console, IBM PC, web documents -- and set the text console's font.

Copal · Copal's own · stage 12 · The application catalogue

On Copal: Fonts in groups rather than one by one: the coding faces (with Nerd Font symbols for prompts), the console fonts, the classic IBM PC faces, and the metric-compatible set that makes a .docx look right. Stage 12 installs coding, console and ibmpc by default.

Use

With no arguments it shows what is installed, group by group. install adds a group; console sets the font of the text console (the one before the desktop, and after Ctrl-Alt-F2).

Examples

Options

install GROUP...

coding, console, ibmpc, web, coding-extra, or all

list [GROUP]

a group's contents, and what is on disk

console [NAME]

list, or set, the text console's font

licences

where the fonts' licence files are

Notes

• web is not installed by default: it matters only when a document from elsewhere looks wrong, and it is large. Install it when that happens.
• Installing a group again only fetches what is missing.

See also starship, oh-my-posh

copal-gpu Say whether the desktop is drawn by the GPU or the CPU, layer by layer, and what to do about it.

Copal · Copal's own · stage 4 · X.Org, i3, a terminal and a browser

On Copal: A slow desktop is usually software rendering, and the reason can be at any of four layers: the kernel's device, the host's VirGL offer, the compositor's renderer, or Mesa's. This checks each and reports the first fault only, because one fault makes every layer above it look wrong too.

Use

Run it inside the desktop. It lists what it found at each layer and ends with a verdict and, when there is a fault, the fix.

Examples

Options

Notes

• The exit status is the verdict: 0 accelerated, 1 working but drawn on the CPU, 2 cannot tell yet (X has not run since boot).
• Under Hyprland the answer is the Renderer: line in Hyprland's log: llvmpipe means software. Under X it reads the Xorg log for the driver and glamor, then asks glxinfo -B (package mesa-demos).
• In a UTM virtual machine, 3D is the host's decision: "-virgl" in the kernel's messages means the display device offers none, and the fix is the VM's display setting (virtio-ramfb-gl), not anything inside.
• On a Raspberry Pi, no DRM device and the framebuffer path are expected.

See also glxinfo, dmesg, copal-debug

copal-gui The other menu, Linux Mint's Cinnamon style: favourites, categories, icons and search, for the mouse.

Copal · Copal's own · stage 4 · X.Org, i3, a terminal and a browser

On Copal: Super+A. The mouse's menu beside copal-menu's keyboard one: hover a category to switch to it, hover a program to read about it, click to run. It sits over the screen as a layer, on the theme's own menu colours.

Use

Press Super+A (again to close). Categories on the left switch on hover, after a short pause; programs on the right describe themselves at the foot as you hover them; a click runs one. Type to search. Right-click a program to add or remove it from the favourites column.

Examples

Options

--list

print section|name|desktop-id for every entry, and exit

Notes

• Scrolling by the edges: rest the pointer in the strip at the top or the bottom of the list and it scrolls at a steady pace; the rows in between stay still, so a click lands on what you aimed at. The wheel works as usual.
• The favourites are kept in ~/.config/copal/gui-favourites, one per line: edit it, or right-click in the menu.
• A click anywhere outside the menu closes it.

See also copal-menu, copal-apps

copal-guide Read Copal's plain-text guides, on the machine, with no network: tmux, nvim, languages, radio and more.

Copal · Copal's own · stage 4 · X.Org, i3, a terminal and a browser

On Copal: The tutorials that come with Copal -- how the editor is set up, which languages this board has, software radio, the small web -- kept in /usr/local/share/copal/guides and opened by name. Super+/ (or Super+F1) opens the desktop's key guide.

Use

Without a name it lists the guides and asks which; with a name it opens that guide in the pager.

Examples

Options

NAME

open that guide (the file's name without .txt)

Notes

• The guides are plain text files in /usr/local/share/copal/guides; less or grep reads them as well.
• The stage that installs a feature writes its guide, so the list grows with what the machine has.

See also man, tldr

copal-halt End the session, and the machine, in one step: shut down, restart or log out, asking first.

Copal · Copal's own · stage 4 · X.Org, i3, a terminal and a browser

On Copal: Super+Shift+P and Session in the menu both run it. It closes the desktop properly first, so programs are asked to quit, then powers down -- from a terminal, a console or SSH alike, without typing the root password.

Use

With no argument it asks, then shuts down. reboot restarts, logout leaves the desktop and keeps the machine running. -y skips the question.

Examples

Options

(none)

shut down, after asking

reboot

restart

logout

end the desktop session only

-y, --yes

do not ask

-h, --help

the usage

Notes

• It needs no password: a narrow doas rule, zz-copal-halt.conf, lets your account run only this. That rule is named to sort after the general wheel rule, because in doas the last match wins.
• Inside i3 it closes the session first, so unsaved work gets its prompt before the power goes.

See also doas, rc-service

copal-install Install packages from the menu's Install branch, in a terminal that stays open to say how it went.

Copal · Copal's own · stage 4 · X.Org, i3, a terminal and a browser

On Copal: What the menus run when you choose a program you do not have yet. It installs the packages, then -- where Copal Apps is present -- their man pages, optionals and group access, and refreshes the menu so the program is there the next time it opens.

Use

You rarely type it: the menus open a terminal running it. By hand, name the packages; a name ending @testing comes from Alpine's testing repository, and one ending @flathub from Flathub.

Examples

Options

PKG...

Alpine packages to install

NAME@testing

from edge/testing (the repository tag is added if needed)

NAME@flathub

a Flatpak from Flathub

Notes

• The window waits for Enter at the end, so a failure's message can be read: the usual causes are no network, or a package this board's architecture does not have.
• It needs root, and says so: run it with doas.
• On a RAM-resident system it reminds you to lbu commit; an installed Copal machine does not need that.

See also copal-store, copal-menu, apk

copal-launcher Open the program launcher -- whichever this machine has: Copal's menu, wofi, or dmenu.

Copal · Copal's own · stage 17 · Hyprland and the Antiquity theme

On Copal: What the theme's launcher key runs. Linux Antiquity names its own launcher, which is not packaged for Alpine; this hands the key to copal-menu, falling back to wofi or dmenu.

Use

Press the launcher key (Super+Space) or run it; it opens the first launcher it finds.

Examples

Options

Notes

• The order is copal-menu, then wofi --show drun, then dmenu_run; if none is installed it says so and exits.

See also copal-menu, copal-gui

copal-logflush Copy the logs kept in RAM down to the card, and back up at boot -- so they survive, with few writes.

Copal · Copal's own · stage 15 · What wears a card, logs, a read-only root

On Copal: An SD card wears with every small write. With /var/log in RAM, this chooses when to write: one complete copy each hour and at shutdown instead of a stream of appends. It is log2ram's design, in a few lines of shell.

Use

You do not run it by hand. It runs only if stage 15's "flush periodically" was chosen: hourly from cron, at shutdown, and at boot to restore.

Examples

Options

save

/var/log (RAM) -> /var/log.persist, then sync (the default)

restore

/var/log.persist -> /var/log (at boot)

Notes

• It does nothing unless /var/log is a tmpfs, so it cannot double the writes on a machine logging straight to the card.
• A power cut loses up to an hour of logs; a clean shutdown loses none.
• A log deleted from RAM is deleted from the copy too, by rsync's --delete where rsync is installed, and by a prune after cp -a where it is not.
• The hooks are /etc/periodic/hourly/copal-logflush and /etc/local.d/copal-logflush.start and .stop.

See also copal-logs, rsync

copal-logs Find the logs that matter on a Copal machine, read them, and clear out the old ones.

Copal · Copal's own · written on every run of the installer

On Copal: The evidence for a desktop that will not start is in a file most people never find. This lists the desktop sessions, the install transcript and the system logs with their sizes, opens the one you want in a pager, and cleans up only what is safe to lose.

Use

With no argument it shows what exists and what it costs. x opens the newest desktop session log, errors picks out its error lines, install opens the install transcript.

Examples

Options

status

what exists, and its size (the default)

x [N], session [N]

a desktop session log; N counts back, 1 the newest

list

every desktop session log, newest first

errors

the error and warning lines from the newest session

install

the install transcript (copal.log on the boot partition)

clean

delete session logs beyond what copal-startx keeps, and stale .bak files

clean --all

the same, and rotate the install transcript to .1

Notes

• The session logs are the X11 desktop's, written by copal-startx into ~/.local/state/copal: the latest two, or ten while copal-debug is on, which is also what clean keeps; a Hyprland session keeps its own log under $XDG_RUNTIME_DIR/hypr, which this does not read.
• clean removes /etc/inittab.bak, /boot/copal-init.sh.bak and /etc/apk/world.bak, but only where the original is beside them. Run it with doas for those.
• status says whether /var/log is in RAM (lost at reboot unless the flush is on) or on disk.

See also copal-startx, copal-debug, copal-logflush, less

copal-menu The keyboard menu: every program in one searchable list, and a second pane of categories, settings, Install and the session.

Copal · Copal's own · stage 4 · X.Org, i3, a terminal and a browser

On Copal: Super+Space (and Super+D, and the bar's button) open its left pane; Super+Z its right. Unlike a plain launcher it lists the terminal programs, the tools you would have to know the names of, and what you could install but have not.

Use

The left pane is every program, flat and sorted: type to filter, Enter to run. The right pane is the same programs by category, then Settings, Style, Install and the session (lock, log out, reboot, shut down). Left and Right cross between the panes; nothing is more than two levels deep.

Examples

Options

--system

open on the right pane

--at-pointer

open at the mouse pointer

--rebuild

rebuild the cached list for this desktop

--rebuild-all

rebuild it for both sessions (Hyprland and i3)

Notes

• The list is cached in ~/.cache/copal so the menu opens in a fraction of a second; it rebuilds itself when programs change, and copal-install rebuilds it after every install. A program missing from the menu: copal-menu --rebuild.
• It draws with wofi. Its scrolling is wofi's own: with the mouse, keep to the middle rows and use the wheel; the arrow keys always work.
• The Install branch lists the catalogue's programs not yet installed; choosing one runs copal-install in a terminal.

See also copal-gui, copal-install, copal-apps

copal-morse Send text as Morse code, drill yourself on it, or print the table.

Copal · Copal's own · stage 7 · Compilers, editors, Claude Code and the ~/code checkouts

On Copal: Alpine packages no Morse program at all, and Copal is a radio amateur's machine too. This one is written for timing: it builds the whole message as one sound file with sox, so the rhythm is exact even on a slow board where starting a program per beep would ruin it.

Use

Give it text and it plays and prints the code. -d is the drill: it sends five random letters, you type what you heard.

Examples

Options

-w WPM

speed in words per minute (default 13)

-f HZ

tone in hertz (default 600)

-q

print the code, play nothing

-p

print the table and exit

-d

drill: it sends, you type

-h, --help

the usage

Notes

• In the drill, Enter alone repeats the group and ? shows it; it keeps score of right and wrong.
• Speed is by the standard word PARIS: at W words per minute a dot lasts 1200/W milliseconds. Letters, digits and common punctuation are sent; anything else is skipped.
• It needs sox for sound (doas apk add sox); without it, it prints the code instead.

See also sox, play, direwolf

copal-notify Put one sentence on this machine's screen: as a notification, a Hyprland banner, or on the console.

Copal · Copal's own · stage 16 · Join the named fleet, and announce it

On Copal: The fleet's "message" verb lands here -- the museum's "please stand back". It uses whatever the machine has, in order of how much screen it takes: a Hyprland overlay, a notification, or the whole console on a machine with no desktop.

Use

Give it the text as one argument. Mostly it is called by the fleet, but it works as a quick message to the screen from a script or over SSH.

Examples

Options

TEXT

the sentence to show (required; quote it)

Notes

• Inside Hyprland it uses hyprctl notify for 8 seconds; otherwise notify-send as a critical notification; with neither it writes the text to /run/copal/banner and to tty1.
• It takes the text as a single argument and never re-splits or interprets it. The fleet limits a message to 200 characters of letters, digits and . , ! ? : - before it gets here.

See also copal-fleet-exec, notify-send, hyprctl

copal-readme-man Make a man page from a project's README.md, so man PROGRAM answers for programs built from source.

Copal · Copal's own · stage 7 · Compilers, editors, Claude Code and the ~/code checkouts

On Copal: The programs in ~/code have READMEs and no man pages. This turns the parts of a README that are about using the program into a proper man page -- leaving out the badges, the build instructions and the licence -- so the manual works for them like everything else.

Use

copal-build runs it for every checkout it builds. Run it yourself to make or preview a page: give the README and the program names, and it writes roff to standard output.

Examples

Options

README NAME[,NAME...]

the page, as roff, on stdout

--markdown README NAME

the filtered Markdown instead, to review

Notes

• It keeps the sections about using the program and drops the title, badges, images and HTML, and the sections a user of the installed program does not need: building, installing, downloading, licence, contributing, credits, status, roadmap, changelog and internals.
• The NAME line lists every program named; the description is the first sentence of the README's first paragraph of prose. The date is the README's last commit, so the same README makes the same page.
• A README's ## becomes a section, its ### a subsection. lowdown does the conversion (doas apk add lowdown).

See also copal-build, lowdown, man

copal-remote Share this machine's screen on the local network for a limited time: VNC on X11, RDP on Wayland.

Copal · Copal's own · stage 16 · Join the named fleet, and announce it

On Copal: For looking at a fleet machine's screen from the console. The machine decides how -- the server that matches its desktop -- and the limits are set on the machine, not by whoever asks: its LAN address only, a deadline, a switch to forbid it, and a log line at each end.

Use

start shares the screen until the deadline (30 minutes unless set otherwise), stop ends it now, status says what is running. Starting again while it runs restarts the clock.

Examples

Options

start

share the screen on the LAN address, until the deadline

stop

stop sharing

status

session, server, mode, minutes and address (the default)

Notes

• On X11 it runs x11vnc on port 5900; on Wayland, hypr-rdp on 3389 with the node's certificate. Neither is part of a normal install.
• VNC asks for the fleet's screen password: COPAL_FLEET_REMOTE_PASSWORD, set by make answers and kept on the node in /etc/copal/remote/passwd (root only). The console's seat answers with the same one. With no password set, stage 16 turns sharing off altogether, and start says why.
• Classic VNC encrypts the login but not the screen, so keep it to a network you trust.
• /etc/copal/remote/mode set to off forbids it -- the setting for a machine in a public place. /etc/copal/remote/minutes sets the deadline; 0 means none.
• Wired interfaces are tried before wireless. Starts and stops go to /var/log/copal-fleet.log.

See also copal-fleet-exec, x11vnc, hyprctl

copal-session Start this machine's desktop -- Hyprland or X11, whichever /etc/copal/session names.

Copal · Copal's own · stage 4 · X.Org, i3, a terminal and a browser

On Copal: One front door for the graphical session. The console login, the autologin and the documentation all say "run copal-session", and a single word in /etc/copal/session decides what that means, so they can never disagree.

Use

Log in on a console as your own user and run it. With the word wayland (and Hyprland installed) it starts Hyprland; otherwise it runs startx.

Examples

Options

Notes

• It refuses to run as root: the desktop belongs to the admin user.
• For Wayland it makes XDG_RUNTIME_DIR if nothing has (a private /tmp/xdg-runtime-UID, mode 700, refusing one someone else owns), then runs Hyprland through start-hyprland when present, inside dbus-run-session so the session's programs share one bus.
• On the X path, if X's setuid helper has been disarmed it stops and names the fix, doas copal-desktop x11, instead of letting startx fail with "Only console users are allowed to run the X server".

See also copal-desktop, copal-startx, copal-autologin

copal-shot Super+Shift+S: drag a rectangle, and that part of the screen is saved as a picture.

Copal · Copal's own · stage 17 · Hyprland and the Antiquity theme

On Copal: The Hyprland desktop's screenshot key. The theme binds hyprshot, which Alpine does not package; copal-shot does the same with grim (grab) and slurp (select), which it does.

Use

Press Super+Shift+S, then drag over the area you want; release and it is saved to ~/Pictures as screenshot-DATE-TIME.png (to /tmp if there is no Pictures folder). Escape cancels.

Examples

Options

Notes

• It saves without saying so: look in ~/Pictures.
• For the whole screen, a window, or a copy on the clipboard, use grim directly, as in the examples.
• On the i3 desktop (X11) screenshots are scrot; copal-shot is for Wayland.

See also grim, scrot, tesseract

copal-splash Draw the i3 desktop's key bindings onto the wallpaper, so the first screen teaches the keys.

Copal · Copal's own · stage 4 · X.Org, i3, a terminal and a browser

On Copal: On the X11 desktop there is no welcome screen, and a tiling window manager with no visible menu is a blank wall to a newcomer. The keys, printed where the wallpaper would be, are the way in.

Use

i3 runs it at startup. Run it yourself after editing ~/.config/i3/keys.txt to see the change without logging out.

Examples

Options

Notes

• It draws the bindings and group headings from keys.txt (the section from START SOMETHING to IF SOMETHING), at the screen's size from xrandr, with a line of the essential keys along the bottom.
• The image is ~/.cache/copal-splash.png and is remade only when keys.txt is newer, so logging in costs nothing.
• It needs ImageMagick to draw and feh to show; without them the desktop is a plain colour, set with xsetroot. It is for the i3 desktop only; Hyprland has its own wallpaper and Super+/ for the keys.

See also i3, copal-guide, feh

copal-ssh Read and change this machine's SSH login policy: passwords, root, and who may log in.

Copal · Copal's own · stage 6 · Install the SSH key from the card

On Copal: Copal writes its SSH policy as one marked block in sshd_config. This edits only that block, tests the result with sshd -t before reloading, and puts the old file back if sshd rejects it -- so a typo cannot lock you out of a machine you can only reach by SSH.

Use

copal-ssh shows the policy. The other forms need doas; each changes one setting and reloads sshd.

Examples

Options

status

password login, root login, allowed users, public keys

password on|off

allow or refuse password (and keyboard-interactive) login

root on|off

root by key only (prohibit-password), or refused

users NAME...

replace the AllowUsers list

Notes

• password off refuses to act if the admin user has no ~/.ssh/authorized_keys, because it would lock the machine off the network. Copy a key in first (ssh-copy-id from your computer).
• The block runs from # >>> copal ssh policy >>> to # <<< copal ssh policy <<<; delete it by hand and OpenSSH's own defaults apply. Every change leaves the previous file as sshd_config.copal.bak.
• Every form, even status, needs root: sshd_config is not readable otherwise.

See also sshd, ssh-keygen, ssh-copy-id

copal-startx Start the X11 desktop as it should be started: not as root, with the right groups, and with a log kept.

Copal · Copal's own · stage 4 · X.Org, i3, a terminal and a browser

On Copal: When X fails to start, the reason scrolls off the console it just took over. copal-startx is startx with that fixed: it refuses root, warns about missing groups, and writes every session's output to a file, printing the tail when the desktop exits with an error.

Use

Run it from a console login instead of startx; arguments are passed on to startx. On the Wayland desktop you want copal-session instead, which picks the right path for this machine.

Examples

Options

(none)

start X, passing any arguments on to startx

Notes

• It refuses to run as root, and says which account to log in as. Plain startx still works for the day you need a root desktop on purpose.
• It warns if you are not in the video, input and tty groups, with the doas adduser line that fixes it.
• The log is ~/.local/state/copal/xsession-DATE.log, with xsession-latest.log linked to the newest. Two are kept; with debug on (doas copal-debug on) ten are kept, and Xorg's own log is copied into each.
• The log header records the tty, groups and graphics devices -- the facts that decide whether X may start and that are gone afterwards.

See also copal-session, copal-logs, copal-debug, startx

copal-store Copal Apps from the command line: find programs by what they do, install and remove them, with everything they need.

Copal · Copal's own · stage 18 · The Copal Store, and OpenShot compiled

On Copal: The engine behind Copal Apps and the menu's Install: every program Copal offers is a playbook, and copal-store runs it -- from an Alpine package, a Flatpak, a build from GitHub source, or a clone into ~/code -- then adds its man page, its optionals (plugins, codecs, format loaders) and the groups it needs.

Use

list and info to look; install and remove to change things (they ask for doas). With no arguments it opens the store window, or terminal menus where there is no desktop.

Examples

Options

list [SECTION]

every program, or one shelf

info ID

one program: description, source, install method

install ID...

install (with man pages, optionals and access)

remove ID...

remove

recipes

the programs built from source

optionals [PKG...|--installed]

the plugins and helpers; install them

access [USER]

the groups programs need: plugdev, wireshark, dialout...

manpages PKG...

the man pages of these packages

summary

the build record

log ID

one build's full log

Notes

• A build from source records what it compiled in ("with") and what it could not find ("absent") in the summary: the answer to which formats and codecs a build has.
• Its logs are in /var/log/copal-store; the event stream Copal Apps reads is /var/log/copal/events.
• Installed on medium and full installs (stage 18).

See also copal-apps, copal-install, apk

copal-terminal-theme Write a colour theme into the terminal emulators' configs: foot, kitty, alacritty and the rest.

Copal · Copal's own · stage 4 · X.Org, i3, a terminal and a browser

On Copal: The terminal part of the desktop's look, on its own: copal-theme calls it, and it can be run by hand for a different terminal palette or opacity.

Use

Name a theme and it writes it into every terminal configuration in your home; with no name it follows the desktop's current theme. Open terminals pick it up when they next start.

Examples

Options

THEME

helios, eris, priapus, eros, hades (Linux Antiquity), night, sand

--list

the theme names --show THEME print the palette and stop

--alpha A

window opacity, 0.5 to 1 (default 0.9)

Notes

• $COPAL_TERMINAL_THEME overrides what "follow the desktop" means.
• Only terminals already configured in your home are rewritten; a terminal installed later gets the theme the next time this runs.

See also copal-theme, foot

copal-theme One switch for the whole desktop's look: bar, borders, wallpaper, GTK, terminal, menus and editor together.

Copal · Copal's own · stage 4 · X.Org, i3, a terminal and a browser

On Copal: Copal's desktop is themed in a dozen places -- Hyprland, the bar, wofi, GTK, the terminal, Neovim, mc. copal-theme changes all of them at once, so nothing is left in the old colours.

Use

With no argument it lists the themes, the current one starred. A name switches to it; --toggle swaps light and dark; --pick offers a menu (Super+Shift+T, or Style in the menu).

Examples

Options

NAME

switch to NAME

--toggle

the current theme's light or dark partner

--pick

choose from a menu (Super+Shift+T)

--show [NAME]

print a theme's tokens

-q, --quiet

say nothing but errors

Notes

• The colours are written to ~/.config/copal/current/colors.css, which the bar, wofi and the Super+A menu read: a running Neovim follows the change without restarting.
• Themes shipped: Antiquity (helios, light) and Tokyo Night (dark).

See also copal-terminal-theme, copal-wallpaper, copal-gui

copal-times How long each package took to install, which ones pulled in the most, and what could be reordered.

Copal · Copal's own · written on every run of the installer

On Copal: A Copal install is hours on a small board, and the time goes somewhere measurable. The installer records every package's time and dependencies; this reads that record to show what was slow and, more usefully, which package's position in the order decided what everything after it cost.

Use

With no argument: the fifteen slowest packages and the total. groups shows the time by stage section; order and shared are the views for deciding what to install first.

Examples

Options

(none), top

the slowest fifteen, and the summary

all

every package, slowest first

groups

time and count by section

order

the packages that pulled in the most, with their position

shared

dependencies wanted by more than one package

deps PKG

what one package brought with it

total

packages, already present, failed, and the install time

csv

the whole record as CSV

--motd

rewrite the login message's summary (needs doas)

--reset

clear the record (needs doas)

-h, --help

the usage

Notes

• PULLED is how many other packages came with one. A long time with "-" is a package that is genuinely expensive; a long time with "+13" is one that happened to be asked for first and paid for the dependencies.
• The record is /var/lib/copal/install-times.tsv, with dependency sets in install-deps.tsv; older six-column records still read.

See also apk, copal-install

copal-wallpaper Choose and paint the desktop's wallpaper, from the theme's collection or your own pictures.

Copal · Copal's own · stage 17 · Hyprland and the Antiquity theme

On Copal: Hyprland's own wallpaper tool, hyprpaper, is not packaged for Alpine; copal-wallpaper paints with swaybg, remembers the choice, and is what the session starts.

Use

--pick shows thumbnails to choose from; set FILE uses any picture. Without arguments it paints the chosen one and keeps running -- the session starts it that way.

Examples

Options

--pick

choose one, with thumbnails

set FILE

use FILE from now on

--list

the wallpapers, and where each came from

--fetch

download the theme author's full collection

Notes

• The bundled wallpapers are in ~/.config/hypr/wallpapers_bundled; --fetch adds the rest of the collection.
• The choice is remembered across logins; set is all it takes.

See also copal-theme

copal-widgets The clock, date and weather on the wallpaper: show them, hide them, and see where they come from.

Copal · Copal's own · stage 4 · X.Org, i3, a terminal and a browser

On Copal: The desktop layer's widgets. The theme's own widget shell, quickshell, is not packaged for Alpine, so waybar draws them; this command turns them on and off without touching the bar, and seeds the theme's own widget file for the day quickshell arrives.

Use

--off hides them, --on brings them back, both at once; --status says which are running and from where.

Examples

Options

--on

show the widgets

--off

hide them

--status

which are running, and from where

--seed

place the theme's widgets in its quickshell file (run at login)

Notes

• What is drawn and where is ~/.config/waybar/desktop.json; the type and colours, desktop.css beside it. Nothing regenerates those files once they exist, so edits stay.

See also copal-bar, copal-theme

oh-my-posh A shell prompt engine with a hundred ready-made themes.

Appearance · command-line tool · built from source by Copal Apps · stage 18 · The Copal Store, and OpenShot compiled · on the Copal Apps shelf

On Copal: The store's other prompt: built by Copal Apps from source, with its whole theme collection, for anyone who wants to pick a look rather than design one.

Usage:
  oh-my-posh [flags]
  oh-my-posh [command]

Use

Initialise it in your shell's start-up file with a theme; the next shell has that prompt. The themes are JSON files: try one, keep the one you like, or copy it and change it.

Examples

Options

init SHELL

print the line that turns it on; --config THEME

print primary

print the prompt, to preview

config

read or export the configuration

debug

show what each segment costs

font

install a Nerd Font for the icons

version

the version

Notes

• Most themes need a Nerd Font; without one the icons show as boxes. copal-fonts install coding brings them.
• A theme that runs git in every prompt can feel slow on a Pi in a big repository; oh-my-posh debug shows which segment it is.

See also starship

starship A fast, configurable shell prompt: the folder, git state, language versions, all at a glance.

Appearance · command-line tool · starship 1.24.2 · stage 18 · The Copal Store, and OpenShot compiled · on the Copal Apps shelf · home

needs dbus-libs

On Copal: The store's prompt for any shell: one line added to the shell's start-up file, and the prompt shows the branch, what changed, how long the last command took and whether it failed.

Usage: starship <COMMAND>
Commands:
  bug-report    Create a pre-populated GitHub issue with information about your configuration

Use

Add its init line to your shell's start-up file; the next shell has the prompt. Change it in ~/.config/starship.toml, or start from one of its presets.

Examples

Options

init SHELL

print the line that turns it on (bash, zsh, fish...)

preset NAME

print a preset; -o FILE to write it

explain

describe the prompt you are looking at

config

edit the configuration

print-config

the configuration in force

toggle MODULE

turn one part on or off

Notes

• Many presets use Nerd Font symbols: without such a font they show as boxes. copal-fonts install coding brings them.
• For the Linux console, a plain preset (plain-text-symbols) avoids symbols the console font lacks.

See also oh-my-posh, git

fluidsynth A software synthesiser: play MIDI files, or MIDI keyboards, through a SoundFont.

Audio · command-line tool · fluidsynth 2.5.4 · stage 12 · The application catalogue · man fluidsynth(1) · home

needs fluidsynth-libs, glib, pipewire-libs

On Copal: The catalogue's MIDI synthesiser, installed with a General MIDI SoundFont (TimGM6mb) so a .mid file makes sound straight away, and a USB keyboard becomes an instrument.

fluidsynth [options] [ SoundFonts ] [ midifiles ]

Use

Give it a SoundFont -- the instrument samples -- and MIDI files to play, or leave it running for a keyboard or a sequencer to play through. It starts an interactive prompt unless told not to.

Examples

Options

-a DRIVER

the audio driver: alsa or pulseaudio (both reach PipeWire)

-i, --no-shell

no prompt: play and exit

-F FILE

render to FILE instead of playing

-g GAIN

the volume, 0 to 10 (default 0.2)

-r RATE

the sample rate

-q, --quiet

no banner -n, --no-midi-in no MIDI input

Notes

• Without -i it waits at its own > prompt after the file ends; quit leaves.
• The default gain is quiet on purpose; -g 1 for a louder start.
• A pages-long run of "ALSA lib ... Unknown PCM" at start is ALSA probing devices that do not exist; it is noise, not failure.
• Better SoundFonts are a download away: any .sf2 file works the same.

See also openmpt123, xmp, alsamixer

openmpt123 Play tracker music -- MOD, XM, S3M, IT and dozens more -- in the terminal, accurately.

Audio · command-line tool · openmpt123 0.8.9 · stage 12 · The application catalogue · man openmpt123(1) · home

needs libflac, libopenmpt, portaudio, libpulse, libsndfile

On Copal: The catalogue's module player, built on OpenMPT's library: the most faithful playback of the music of the Amiga and PC demoscene.

openmpt123 [options] [--] file1 [file2] ...

Use

Give it module files; it plays them in order and shows the pattern position. It can also render a module to a WAV or FLAC file.

Examples

Options

--render

render each file to a WAV beside it

--info

print the module's details only

--shuffle

shuffle the files

--repeat N

repeat each song N times (-1 forever)

--gain DB

the volume, in dB

-q, --quiet

no display

--driver NAME

the audio output

--help-keyboard

every key it answers while playing

Notes

• Modules are tiny: a three-minute XM is often under 100 kB. The Mod Archive (modarchive.org) holds over a hundred thousand.
• If there is no sound, --driver help lists the outputs this build has.

See also xmp, fluidsynth

pactl PulseAudio's control command, answered here by PipeWire.

Audio · pulseaudio-utils 17.0 · stage 10 · Wireless, audio, capture and disks · man pactl(1) · home

needs libintl, libpulse, libsndfile, libxcb

On Copal: Copal runs pipewire-pulse, so programs written for PulseAudio work unchanged -- and pactl, which most answers online use, works too. For everyday volume and output, wpctl is the native tool.

pactl [options] COMMAND [ARGS ...]

pactl --help

pactl --version

Use

List the outputs (sinks) and inputs (sources) by name, change their volume, and move a playing stream from one device to another. The special names @DEFAULT_SINK@ and @DEFAULT_SOURCE@ save looking them up.

Examples

Options

info

the server and its defaults

list [short] TYPE

sinks, sources, sink-inputs, cards, modules

set-sink-volume NAME VOL

50%, +5%, -5%

set-sink-mute NAME 1|0|toggle

mute

set-default-sink NAME

the default output

move-sink-input N SINK

move a playing stream

-f, --format=json

JSON output

Notes

• pactl info saying "Server Name: PulseAudio (on PipeWire ...)" is right: it is PipeWire's pulse layer. There is no PulseAudio daemon, and pulseaudio -k answers are not for this system.
• "Connection refused": no PipeWire in this session -- over SSH, say. See wpctl.

See also wpctl

wpctl Control PipeWire's audio: volume, mute, and which device plays.

Audio · wireplumber 0.5.15 · stage 10 · Wireless, audio, capture and disks · home

needs glib, libintl, lua5.4-libs, pipewire-libs, wireplumber-libs

On Copal: Copal's sound is PipeWire with WirePlumber, started with each session by copal-audio-start. The desktop's volume keys are wpctl commands; so is changing the output from HDMI to headphones.

Use

wpctl status lists the devices -- sinks are outputs, sources are inputs -- each with an ID number, and marks the default with *. Every other command takes an ID, or @DEFAULT_AUDIO_SINK@ for the current output.

Examples

Options

status

the whole graph: devices, sinks, sources, streams

get-volume ID

the volume, 1.00 being 100%

set-volume ID VOL[%][+-]

set, or step up or down

set-mute ID 1|0|toggle

mute, unmute, toggle

set-default ID

the default output or input

inspect ID

all of a node's properties

set-volume -l N ID VOL

go no higher than N (1.0 = 100%)

Notes

• "Could not connect to PipeWire": no PipeWire is running for this user in this session -- typical over SSH or on a console. Run it from the desktop's terminal, or start it with copal-audio-start.
• IDs change between sessions. In a script, use @DEFAULT_AUDIO_SINK@ and @DEFAULT_AUDIO_SOURCE@, not numbers.
• The RTKit warnings it prints first ("RTKit error ... ServiceUnknown") are harmless: there is no RTKit on Copal, and audio runs without it.

See also pactl, bluetoothctl

xmp The Extended Module Player: tracker music in the terminal, with a channel-by-channel view.

Audio · command-line tool · xmp 4.2.0 · stage 12 · The application catalogue · man xmp(1) · home

needs alsa-lib, libpulse, libxmp

On Copal: The catalogue's other module player: small, and it can solo and mute channels as it plays -- the way to hear how a tracker song is built.

xmp [-a, --amplify factor] [-A, --amiga] [-b, --bits bits] [-C, --show-comments] [-c,
--stdout] [-D device-specific parameters] [-d, --driver driver] [-e, --player-mode mode] [-F,
--nofilter] [-f, --frequency rate] [--fix-sample-loop] [-h, --help] [-I, --instrument-path]
[-i, --interpolation type] [--load-only] [-L, --list-formats] [-l, --loop] [--loop-all] [-M,
--mute channel-list] [-m, --mono] [--mixer_voices num] [-N, --null] [--nocmd] [-o,
--output-file filename] [-P, --pan num] [-p, --default-pan num] [--probe-only] [-q, --quiet]
[-R, --random] [-S, --solo channel-list] [-s, --start pos] [-t, --time time] [-u, --unsigned]
[--vblank] [-V, --version] [-v, --verbose] [-Z, --all-sequences] [-z, --sequence num] modules

Use

Play module files; the display shows the patterns and channels moving. Number keys mute channels while it plays, so the parts can be heard one at a time.

Examples

Options

-l, --loop

loop the song

-o, --output-file F

write to F instead of playing

-S, --solo LIST

play only these channels

-a, --amplify N

amplification, 0 to 3

-d, --driver NAME

the output driver

-L, --list-formats

the formats it reads

Notes

• It comes from Alpine's testing repository (xmp@testing).
• For the most faithful playback of IT and newer formats, openmpt123 is the reference; xmp is lighter and shows more.

See also openmpt123, fluidsynth

browsh The modern web in a terminal: a real Firefox renders the page, browsh draws it in text.

Browsers · terminal program · built from source by Copal Apps · stage 18 · The Copal Store, and OpenShot compiled · on the Copal Apps shelf

On Copal: The store's browser for pages the text browsers cannot show -- JavaScript, video thumbnails, modern layouts -- over SSH or on a console, with Firefox ESR doing the rendering headless.

Use

Start it with an address; Firefox runs in the background and browsh draws the page with coloured characters. Ctrl-l goes to a new address; the mouse clicks links where the terminal passes clicks.

Examples

Options

--startup-url URL

the page to open

--monochrome

no colour

--http-server-mode

run as an HTTP service instead of a terminal UI

--time-limit SECS

quit after SECS seconds

--firefox.path PATH

which Firefox (Copal's launcher passes firefox-esr)

Notes

• It is Firefox underneath, so it costs Firefox's memory: a few hundred MB, and a slow start on a small Pi.
• Not on ARMv6 (the first Zero): its row is gated off there.

See also links, w3m, firefox-esr

ascitty A raytraced city of typeable characters, in real time in a terminal -- with a taxi game inside.

Code · terminal program · stage 18 · The Copal Store, and OpenShot compiled · on the Copal Apps shelf · man ascitty(1), from its README

On Copal: One of the checkouts in ~/code, built by copal-build: a showpiece for a colour terminal, and a test of one. The same city runs on a Commodore Plus/4.

Use

Start it and a cab drives itself round the city, taking fares. Touch a key and you are driving: wasd is the vehicle, the arrows are the view, and \ hands it back to the autopilot. The frame is the size of the window, so a bigger terminal is a bigger city.

Examples

Options

--play

drive from the start, no autopilot

--walk

on foot

--copter

in the air

--mode M

ascii or unicode (default unicode)

--color D

true, 16 or none (default: from $COLORTERM)

--size WxH

a fixed frame instead of the window's size

--fps N

frame rate cap (default 30)

--seed N

another city

--sky N

start at phase N of 12: 0 night, 3 sunrise, 5 noon, 8 sunset

--shot [N]

render N frames, print the last, exit

--bench

measure the renderer

Notes

• The terminal is the bottleneck, not the renderer: a big frame takes the renderer a millisecond and the terminal twenty. Bands of the picture a frame behind mean the terminal is falling behind -- a smaller window or --fps 15 fixes it.
• Hold the keys: the throttle winds on while it is down, as the steering does, so a tap does very little.
• --color follows $COLORTERM; set --color 16 if the colours look wrong over SSH.

See also copal-build, copal-terminal-theme

birdshot Bird and sky capture for the Raspberry Pi HQ Camera, from the command line.

Code · command-line tool · stage 18 · The Copal Store, and OpenShot compiled · on the Copal Apps shelf · man birdshot(1), from its README

On Copal: Copal's camera. copal-build builds the C++ pipeline from the birdshot checkout; birdshot-gui is its window (Super+Shift+B), and this is the same pipeline for a script or an SSH session.

Use

Capture with metered auto-exposure and quality gates that drop blurred or badly exposed frames, fast bursts, timelapses, or a watch on the sky that fires when a bird crosses it. Then stamp the EXIF and assemble a session's frames into a video.

Examples

Options

capture [-n N] [-v]

the full pipeline, with quality gates

rapid [-n N]

fastest single photos

timelapse [-i SEC] [-n N]

one frame every SEC seconds

birdflight [-n TAKES]

trigger on a bird

gui [--port N]

the live pipeline in a browser

exif DIR

stamp EXIF into a session, losslessly

assemble DIR [--fps N]

frames to a movie; --out FILE

sun / plan / site

where the sun is, a plan for the days ahead, your site

info / sessions / doctor / selftest

the housekeeping

--config PATH

another settings file

Notes

• It is for an IMX477 -- the Pi HQ Camera. Other cameras are not what its exposure ladder and gates are tuned for; birdshot doctor says what it found.
• Settings live in ~/.config/birdshot/settings.json; every command reads it, and --config points at another.
• The first run of the window offers a calibration wizard, about a minute. Its numbers are what the quality gates judge by: run it.

See also copal-camera, copal-build

copal-tm Copal's task manager: an instrument panel and a process browser in one terminal window.

Code · terminal program · stage 18 · The Copal Store, and OpenShot compiled · on the Copal Apps shelf · man copal-tm(1), from its README

On Copal: The task manager on Copal's full install, built by copal-build from its checkout: what the machine is doing, which process is doing it, and a considered way to stop one.

Use

The top half is the instrument panel -- CPU, memory, swap, temperature, network, pressure; the bottom half is the process tree. Select a process and press k to send it one signal, or x for the Halt plan: the gentle signals first, the hard one last, with the reasons shown.

Examples

Options

--view MODE

split, dashboard or browser

--refresh SECONDS

the tick, 0.25 to 10 (default 1.0)

--charset SET

auto, full, blocks or ascii

--color MODE

auto, truecolor or 16 --browser.sort KEY cpu, mem, pid, time, name or user

--theme NAME

copal or mono

--simulate

run against a simulated machine

--dump-config

print the effective configuration

Notes

• k shows each signal's disposition -- whether the process catches, ignores or dies of it -- before you send it; the Halt plan uses those.
• The configuration is ~/.config/copal/taskman.conf, key = value, and every key is also a flag of the same name.
• It degrades legibly: on a 16-colour console or an ASCII-only terminal it still draws, with --charset ascii.

See also htop, btop, copal-halt

orrery The console for a fleet of Copal machines: the wall, the seat, and the museum interface.

Code · terminal program · stage 18 · The Copal Store, and OpenShot compiled · on the Copal Apps shelf · man orrery(1), from its README

On Copal: Stage 16's fleet -- a room of Copal machines -- is watched and run from it: every machine at once on the wall, one of them full screen in the seat. Built by copal-build from the orrery checkout.

Use

Three faces. The wall is a web page of every machine in the fleet, served on a port. The seat is one machine, observed and controlled over VNC, full screen in this terminal. The native window (--gui) is the museum interface. Without --operator it only observes; with it, the verbs that act on machines are enabled.

Examples

Options

--listen HOST:PORT

where the wall is served (default 127.0.0.1:8080)

--operator TOKEN

enable the verbs that change machines

--fleet NAME

which fleet (passed to copal fleet)

--demo

serve from a fixture instead of a fleet

--gui

the native window instead of a web page

--seat NODE

one node over VNC; --fps N, --vnc-port N

--frame PATH

render one frame to a PPM and exit (works headless)

--dark

the night palette

--quiet

do not log requests

Notes

• The default listens on loopback only. The gallery screen needs --listen 0.0.0.0:8080, which puts the wall on the LAN: a LAN you trust.
• Read-mostly by default is deliberate. --operator is what turns a display into a control panel.
• The seat asks a node for 6 frames a second, because frame rate is the expensive axis; --fps raises it.

See also copal-fleet, ssh

radbeeper A GQ GMC Geiger counter on the desk: find it, watch it, log it, and pull its history.

Code · terminal program · stage 18 · The Copal Store, and OpenShot compiled · on the Copal Apps shelf · man radbeeper(1), from its README

On Copal: Stage 10 sets up the Geiger counter; radbeeper, built by copal-build from its checkout, is the command the counter's instrument panel (radbeeper-gui) is built on.

Use

Plug the counter in by USB, radbeeper probe to find it, radbeeper watch to see its rate over five time spans at once while it logs. It also downloads what the counter recorded on its own, and turns the timing of decays into random numbers.

Examples

Options

probe

find and identify the counter

watch

the live monitor

cpm

one reading

clock [--set]

compare, or set, the counter's clock

log info|pull

what history it holds / download it

backfill

fill gaps in the log from the counter's memory

random

random bits from decay timing; --check F to verify a log

-d, --device PATH

the serial port; repeat for a second counter

-b, --baud RATE

the baud (default: 115200, then 57600)

--duration SECONDS

stop after this long

--logs DIR

where logs are written and read

Notes

• Nothing found? probe says what went wrong, because each cause has its own fix. "Permission denied" means the account is not in dialout, which owns the serial port: doas adduser $USER dialout, then log in again.
• Set the clock first (clock --set): the history in the counter's flash carries the counter's own timestamps.
• The default tube factor is 151.5 CPM per µSv/h, the GMC-320's; --cpm-per-usvh for another tube.
• doas dmesg | tail after plugging it in shows the serial port it got.

See also copal-build, dmesg

sstr Record a stream into a .sstr file, with its order, pace and damage tolerance kept, and play it back.

Code · command-line tool · stage 18 · The Copal Store, and OpenShot compiled · on the Copal Apps shelf · man sstr(1), from its README

On Copal: The archive format ytq keeps its downloads in. Built by copal-build from the staticstream checkout; sstr export turns captures back into ordinary files whenever you want them.

Use

sstr record writes a stream -- a file, or stdin -- into a capture; sstr play lets it out again: to a file, to stdout at the pace it was recorded, or to VLC or mpv over the network. Every record carries Reed-Solomon parity (about 21 % more bytes), so a damaged capture is repaired as it is read. Nothing is encrypted and nothing is decoded.

Examples

Options

record OUT

capture stdin, or --input FILE, into OUT

play IN

write the stream back; -o FILE, --paced, --speed N

play IN --serve A

serve it over HTTP at HOST:PORT

verify IN

check every record and signature

export PATH...

captures or folders back to files; -r, -n, --into DIR

config

list, get, set or unset a setting

--key KEY

sign the checkpoints with this SSH key

--allowed-signers F

trust signatures by these keys, when reading

-

as IN or OUT: stdin or stdout

Notes

• Checkpoints are signed with your SSH key, which proves who recorded it; they are not encrypted. Anyone with the file can play it.
• export with --remove deletes each capture once its file is out and checked; without it, both stay.
• A capture can be played or served while it is still being recorded: --follow keeps going as it grows, so mpv or VLC can watch it live.

See also ytq, sstr-workspace

sstr-workspace One terminal window over the download queue and the archive: browse, play, verify, export.

Code · terminal program · stage 18 · The Copal Store, and OpenShot compiled · on the Copal Apps shelf · man sstr-workspace(1), from its README

On Copal: Super+Shift+A. The Workspace over ytq's queue and the folders of Static Stream captures it fills, from the staticstream checkout -- every action one key, and every action a command line you can read.

Use

A column browser. Move through folders and the queue, look at a capture in the Inspector, and send it a Service -- play, verify, export -- with one key. Each Service is written into the Transcript as a command line before it runs, so you see exactly what was done and can type it again.

Examples

Options

DIR

browse DIR instead of the queue

Space

the Shelf: a Service then goes to everything on it

d

one line per queue entry, or two

Notes

• The archive folder is ARCHIVE_DIR in ~/.config/copal/media.conf, then ~/.config/ytq/config -- where ytq reads it. The player (mpv) and the serve address come from the same files.
• A Service that prints takes the terminal until a key is pressed; the window comes back after it.

See also ytq, sstr

ytq A download queue that watches the clipboard, and keeps what it fetches as Static Stream.

Code · terminal program · stage 18 · The Copal Store, and OpenShot compiled · on the Copal Apps shelf · man ytq(1), from its README

On Copal: Copy a video's link, press Super+Shift+Y, and it is queued. Built by copal-build from the staticstream checkout in ~/code; the Rust ytq replaced the Python one Copal used to write.

Use

Queue links, then download them one at a time with yt-dlp, best video and audio merged. The queue is one file shared by every ytq at once, so ytq add works while ytq run is downloading. Each download also gets a .txt beside it: the full title, author, URL, dates, the description and the captions, so it can be cited later.

Examples

Options

clip

queue the clipboard's URL, or every YouTube link in it

add URL...

queue URLs

run

download the queue in this terminal

status / list

the current download / every entry

retry URL

put an entry back (r in the window)

forget URL

take one out; the downloaded file stays (d)

clear

forget finished and failed entries; files and log stay

cookies

retry the entries waiting on a sign-in (c)

--mp4

keep the video file, write no capture

--sstr

keep a Static Stream capture, remove the video once checked

--both

keep the two

--run / --no-run

start a runner this once / never

Notes

• Nothing downloads until something runs the queue: ytq run, the window, or autostart (~/.config/ytq/auto). Without that file, clip and add only queue.
• A login, age gate or "confirm you are not a bot" page opens Brave on the URL: sign in there, then ytq cookies. A second failure is final.
• What it keeps by default is a .sstr capture, not a video file. sstr export DIR turns a folder of them back into ordinary files.
• The log is ~/.local/share/ytq/ytq.log; the queue is ~/.local/share/ytq/queue.json.

See also sstr, sstr-workspace, copal-build

redshift Warm the screen's colour after sunset, following the time of day at your location.

Control · command-line tool · redshift 1.12 · stage 12 · The application catalogue · man redshift(1) · home

needs python3, libx11, libxxf86vm, libdrm, glib, libxcb

On Copal: The catalogue's night colour for the X11 desktop (i3). It has no Wayland method, so on Hyprland it cannot reach the screen; there, hyprsunset and gammastep -- installed with it as optionals -- do the same job.

redshift [-l LAT:LON | -l PROVIDER:OPTIONS] [-t DAY:NIGHT] [OPTIONS...]

Use

Give it your latitude and longitude; it shifts the colour temperature through the day. -O sets one temperature and leaves it; -x resets.

Examples

Options

-l LAT:LON

your location

-t DAY:NIGHT

colour temperatures (default 6500:4500)

-O TEMP

one-shot: set TEMP and exit

-o

one-shot: set the current temperature and exit

-x

reset the screen

-P

reset the gamma first (for -O)

-m METHOD

randr, vidmode or drm

Notes

• On Hyprland it has nothing to talk to: this build's methods are X11's (randr, vidmode) and bare DRM. Use hyprsunset -t 4000, Hyprland's own, or gammastep, redshift's Wayland-capable fork with the same options.
• Settings can live in ~/.config/redshift/redshift.conf instead of on the command line.

See also hyprctl

udiskie Mount USB sticks and cards automatically when they are plugged in, with a tray icon.

Control · command-line tool · udiskie 2.6.1 · stage 12 · The application catalogue · man udiskie(8) · home

needs py3-docopt, py3-keyutils, py3-gobject3, py3-yaml, python3, udisks2

On Copal: The catalogue's automounter: plug in a stick and it appears under /run/media, with a notification -- no mount commands. It talks to udisks2, which starts on demand.

udiskie [OPTIONS]

udiskie-mount [OPTIONS] (-a | DEVICE...)

udiskie-umount [OPTIONS] (-a | PATH...)

Use

Run it in the background of the desktop session; it mounts removable media as it arrives and offers to unmount from its tray icon. For a one-off, udisksctl mounts and unmounts by hand.

Examples

Options

-a, --automount

mount new devices as they appear

-n, --notify

show a notification for each

-t, --tray

show a tray icon

-s, --smart-tray

the tray icon only while there is something to show

-N, --no-notify

no notifications

-T, --no-tray

no tray icon

Notes

• To start it with the desktop, add exec-once = udiskie -a -n -s to ~/.config/hypr/local.conf.
• Media are mounted under /run/media/$USER/LABEL; unmount before pulling a stick out, or the last writes may not reach it.

See also lsblk, sshfs

dot Graphviz: lay out and draw graphs -- boxes and arrows -- from a text description.

Design · command-line tool · graphviz 12.2.1 · stage 12 · The application catalogue · man dot(1) · home

needs font-cantarell, libx11, cairo, graphviz-libs, libexpat, libgd, glib, pango

On Copal: The catalogue's graph drawer, and the layout engine PlantUML and Doxygen call. A dependency tree, a state machine or a network map is a few lines of text.

dot [options] [files]
neato [options] [files]
twopi [options] [files]
circo [options] [files]
fdp [options] [files]
sfdp [options] [files]
patchwork [options] [files]
osage [options] [files]

Use

Describe the graph in the DOT language -- nodes and -> edges -- and dot works out where everything goes and draws it. Other layouts of the same file: neato and fdp (springs), circo (circles), twopi (rings).

Examples

Options

-T FORMAT

svg, png, pdf, and others

-o FILE

the output file (default stdout)

-G NAME=VALUE

a graph attribute: rankdir=LR, bgcolor=transparent

-N NAME=VALUE

a default for every node: shape=box

-E NAME=VALUE

a default for every edge

-K LAYOUT

the layout engine: dot, neato, fdp, circo, twopi

Notes

• digraph draws arrows (->), graph plain lines (--); mixing them is a syntax error.
• Large graphs are slow with dot; sfdp handles thousands of nodes.

See also plantuml, doxygen

plantuml Draw UML and other diagrams from plain text: sequence, class, state, activity, Gantt.

Design · command-line tool · plantuml 1.2025.10 · stage 12 · The application catalogue · home

needs graphviz, gtk+2.0, java-common, java-jre

On Copal: The catalogue's diagrams-as-text tool: a diagram kept as a few lines in the repository, diffed and reviewed like code, and drawn when needed.

Usage:
  java -jar plantuml.jar [options] [file|dir]...
  java -jar plantuml.jar [options] --gui

Use

Write the diagram between @startuml and @enduml in a .puml file, and run plantuml on it: a picture of the same name appears beside it. It is a Java program, so the first run takes a few seconds.

Examples

Options

--svg / --png

the output format

--output-dir DIR

where the pictures go

-pipe

read stdin, write the picture to stdout

--check-syntax

check the diagrams, draw nothing

--gui

a window listing the diagrams in a folder

Notes

• -tsvg and -tpng, the older spellings most guides use, still work.
• Class and component diagrams are laid out by Graphviz, which is installed (dot); sequence diagrams need nothing else.
• On a Pi with little memory, Java's start-up is most of the time. Draw a whole folder in one run rather than a file per run.

See also dot, nvim

hyprctl Ask the running Hyprland about its windows, monitors and settings, and change them.

Desktop · hyprland 0.54.3 · stage 17 · Hyprland and the Antiquity theme · man hyprctl(1) · home

needs mesa-egl, mesa-gles, libxcursor, aquamarine, cairo, libdrm, mesa-gbm, glib

On Copal: Stage 17's desktop is Hyprland. hyprctl is how to find a monitor's name, a window's class for a rule, or why a line in the config was not accepted -- and to try a setting before writing it down.

hyprctl [(opt)flags] [command] [(opt)args]

Use

Query (monitors, clients, activewindow), or act (dispatch, keyword, reload). A keyword change lasts until the next reload; to keep it, put the same line in ~/.config/hypr/local.conf.

Examples

Options

monitors [all]

outputs; all includes the disabled ones

clients

windows

activewindow

the focused window

workspaces

workspaces and what is on them

binds

every key binding

configerrors

config lines that failed

reload

reload the configuration

dispatch NAME ARGS

run a dispatcher: workspace, exec, killactive...

keyword NAME VALUE

set a config value for now

-j

JSON output

--batch 'A; B'

several commands in one call

Notes

• ~/.config/hypr/hyprland.conf is rewritten each time stage 17 runs. Your changes go in local.conf, which it sources last, so they win; Hyprland reloads on save.
• Hyprland 0.54 reads only the .conf dialect. The hyprland.lua beside it is upstream's original, for 0.55 and later.
• A window rule needs the window's class: open it, then hyprctl clients and read class:.

See also copal-desk, copal-theme, copal-shot

gcc The GNU C and C++ compiler.

Development · gcc 15.2.0 · stage 7 · Compilers, editors, Claude Code and the ~/code checkouts · man gcc(1) · home

needs binutils, libgcc-static, libgomp, libatomic, gmp, isl25, mpc1, mpfr4

On Copal: Stage 7 installs build-base -- gcc, make and the musl headers -- because most things built on a Copal machine start here: the checkouts in ~/code, the store's source builds, your own programs.

gcc [-c|-S|-E] [-std=standard]
    [-g] [-pg] [-Olevel]
    [-Wwarn...] [-Wpedantic]
    [-Idir...] [-Ldir...]
    [-Dmacro[=defn]...] [-Umacro]
    [-foption...] [-mmachine-option...]
    [-o outfile] [@file] infile...

Only the most useful options are listed here; see below for the remainder.  g++ accepts
mostly the same options as gcc.

Use

Compile C (gcc) or C++ (g++) source into a program, or into object files for a larger build. Warnings on and debug information in is the right default while writing; optimisation for the version you keep.

Examples

Options

-o FILE

name the output

-c

compile only, make a .o

-g

debug information, for gdb

-O2

optimise; -O0 for none, -Os for size

-Wall -Wextra

the warnings worth having

-std=c17

the language standard: c89 c99 c11 c17 c23, c++17 c++20 c++23

-I DIR

another directory of headers

-L DIR -lNAME

link libNAME from DIR

-static

link everything in

-E

preprocess only

Notes

• The C library is musl, not glibc. Code that uses glibc extensions (execinfo.h's backtrace, some _GNU_SOURCE corners) will not find them. A binary built on Debian will not run here, nor the reverse.
• -fsanitize=address and -fsanitize=undefined fail to link: Alpine ships no sanitizer runtimes. Use valgrind for memory errors.
• -static is cheap and reliable on musl -- a static binary copies to another Copal machine of the same architecture and runs.
• Missing header? The library's -dev package has it: apk add openssl-dev for openssl/ssl.h.

See also clang, make, gdb, valgrind, cmake

git Version control: keep a project's history, branch it, and share it.

Development · git 2.54.0 · stage 7 · Compilers, editors, Claude Code and the ~/code checkouts · man git(1) · home

needs libcurl, libexpat, pcre2, zlib

On Copal: Stage 7 clones your repositories into ~/code with it, and sets its identity from the answers given on the Mac. copal-code pulls and rebuilds every checkout through it; Copal itself is a git checkout.

git [-v | --version] [-h | --help] [-C <path>] [-c <name>=<value>]
    [--exec-path[=<path>]] [--html-path] [--man-path] [--info-path]
    [-p | --paginate | -P | --no-pager] [--no-replace-objects] [--no-lazy-fetch]
    [--no-optional-locks] [--no-advice] [--bare] [--git-dir=<path>]
    [--work-tree=<path>] [--namespace=<name>] [--config-env=<name>=<envvar>]
    <command> [<args>]

Use

Record changes as commits, move between versions, and exchange them with a remote such as GitHub. The daily loop is short: status, add, commit, pull, push.

Examples

Options

status

the working tree against the last commit

add -p

stage hunk by hunk, asking for each

commit -m MSG

commit with a message; --amend to redo the last one

pull --rebase

fetch, then replay your commits on top

log --oneline

one line per commit; --graph draws the branches

diff / diff --staged

unstaged / staged changes

switch -c NAME

create a branch and switch to it

restore FILE

discard working-tree changes; --staged to unstage

stash / stash pop

set changes aside, and bring them back

remote -v

where fetch and push go

Notes

• Stage 7 clones over SSH when it can and over HTTPS when it cannot. HTTPS checkouts pull but cannot push without a token: make a key (ssh-keygen -t ed25519), add its .pub to GitHub, then git remote set-url origin git@github.com:you/thing.git.
• The identity comes from stage 1's answers: git config --global user.email shows it, and sets it.
• git restore and git reset --hard discard work with no undo. When unsure, git stash first: it keeps the changes where you can get them back.
• With delta installed (the catalogue's System section), git config --global core.pager delta makes diffs coloured and clearer.

See also ssh-keygen, ssh, make, copal-code, copal-build

make Rebuild what is out of date, by the rules in a Makefile.

Development · make 4.4.1 · stage 7 · Compilers, editors, Claude Code and the ~/code checkouts · man make(1) · home

On Copal: The build tool behind Neovim's F5 (:make) and stage 7's sample project in ~/dev/hello, and the front door of most checkouts -- Copal's own repository included (make lint, make commands).

make [OPTION]... [TARGET]...

Use

Run in a directory with a Makefile: make builds its first target, make NAME a named one. It compares file times, so only what changed is rebuilt.

Examples

Options

-j N

run N jobs in parallel

-n

dry run: show the commands

-C DIR

change to DIR first

-B

rebuild everything, dated or not

-k

keep going after an error

-s

silent: do not echo the commands

VAR=VALUE

set a variable, overriding the Makefile's

Notes

• Recipe lines start with a TAB, not spaces. "missing separator" means an editor put spaces there.
• -j with more jobs than RAM can hold: on a 512 MB board, make -j1 and zram are safer than a build killed halfway.
• In Neovim, F5 saves and runs :make; the errors land in the quickfix list, and ]q and [q walk them.

See also gcc, cmake, ninja, nvim

ninja Run a build that cmake or meson generated, fast and in parallel.

Development · samurai 1.2 · stage 7 · Compilers, editors, Claude Code and the ~/code checkouts · man ninja(1) · home

On Copal: The builder behind cmake -G Ninja and every meson project. On Alpine the command is samurai, a small compatible reimplementation (/usr/bin/samu); what it lacks, few builds use.

samu [-C dir] [-d debugflag] [-f buildfile] [-j maxjobs] [-k maxfail] [-w warnflag=action]
     [-nv] [target...]
samu [-C dir] [-f buildfile] -t clean [-gr] [target...]
samu [-C dir] [-f buildfile] -t compdb [-x] [rule...]
samu [-C dir] [-f buildfile] -t commands [target...]
samu [-C dir] [-f buildfile] -t query [target...]
samu [-C dir] [-f buildfile] -t targets [depth [maxdepth]]
samu [-C dir] [-f buildfile] -t targets rule [rulename]
samu [-C dir] [-f buildfile] -t targets all
samu -t list

Use

Run it in (or point it at) a build directory that has a build.ninja. You rarely write that file yourself: cmake or meson writes it, and ninja builds from it, running as many jobs as there are cores.

Examples

Options

-C DIR

change to DIR first

-j N

N jobs at once (default: cores + 2)

-k N

keep going until N failures

-n

dry run

-v

print each full command

-t TOOL

a subtool: clean, targets, commands, compdb, query

Notes

• It is samurai: -t graph and a few other ninja subtools are not there ("unknown tool"). Builds themselves behave the same.
• The default job count assumes enough memory for each. On a 512 MB Pi, a C++ build at -j3 swaps hard; pass -j1 or -j2.
• Do not edit build.ninja: the next cmake or meson run rewrites it.

See also cmake, make, meson

nvim Neovim: a modal text editor, set up by Copal as a small IDE.

Development · neovim 0.12.2 · stage 7 · Compilers, editors, Claude Code and the ~/code checkouts · man nvim(1) · home

needs lua5.1-lpeg, tree-sitter-c, tree-sitter-lua, tree-sitter-markdown, tree-sitter-vim, tree-sitter-vimdoc, tree-sitter-query, libintl

On Copal: Stage 7's editor. Copal's configuration gives it building (F5), the error list, a debugger (F4), language servers and LazyVim-shaped keys -- with no plugin manager and nothing to download.

nvim [options] [file ...]
nvim [options] -
nvim [options] -t tag
nvim [options] -q [errorfile]

Use

Open a file, edit in insert mode, move and change text in normal mode. On a Copal machine it also builds and debugs: F5 runs make, the errors land in a list, and the language server answers "where is this defined" and "who calls this". Space is the leader key: press it and wait for the menu of what follows.

Examples

Options

+N

open at line N

-d A B

diff mode

-R

read-only

--clean

start with no configuration at all (to test a problem)

:w

:q :wq (in nvim) write, quit, both; :q! quits without saving

i

Esc (in nvim) into insert mode, back to normal mode

u

Ctrl-R (in nvim) undo, redo

Notes

• The configuration is layered, and one part is yours: ~/.config/nvim/local.lua is never written by Copal and runs last. init.vim, theme.lua, keys.lua and lsp.lua are rewritten when stage 7 runs again.
• Language servers need the project's build flags for C and C++: a compile_commands.json, from bear -- make or cmake.
• The colours follow the desktop's theme, even in a running editor.
• :Tutor inside nvim is the half-hour lesson in the modal part.

See also make, gdb, git, tmux, clang

pip Install Python packages from PyPI -- inside a virtual environment.

Development · py3-pip 26.1.2 · stage 7 · Compilers, editors, Claude Code and the ~/code checkouts · man pip(1) · home

needs python3

On Copal: Stage 7 installs it for the packages Alpine does not carry. On Alpine it refuses to touch the system's Python, and that refusal is the most-asked question about it.

pip <command> [options]

Use

Make a virtual environment for the project, enter it, and pip installs there -- not into the system. For a command-line tool you want everywhere, pipx does the same for one program at a time.

Examples

Options

install PKG

install; -U to upgrade; ==VER for a version

install -r FILE

install every line of FILE

uninstall PKG

remove

list

what is installed; --outdated

show PKG

version, location, dependencies

freeze

installed packages as a requirements file

Notes

• "error: externally-managed-environment" outside a venv is Alpine protecting apk's Python. --break-system-packages overrides it and means what it says: a later apk upgrade can break both.
• A package with C inside may have no musl wheel and compile instead, which needs build-base python3-dev and, on a Pi, patience.
• pip install --user is refused too. pipx is the tool for per-user programs; it puts them in ~/.local/bin, which Copal puts on PATH.

See also python3, apk

bear Record a build's compiler calls into compile_commands.json, for clangd and other tools.

Devtools · command-line tool · bear 4.1.5 · stage 7 · Compilers, editors, Claude Code and the ~/code checkouts · man bear(1) · home

On Copal: The catalogue's bridge between a Makefile and the editor: clangd needs each file's flags, and a plain make build does not write them down. Bear watches the build and does.

bear [OPTIONS] [--] [BUILD_COMMAND...]

bear intercept [OPTIONS] [--] BUILD_COMMAND...

bear semantic [OPTIONS]

Use

Put bear -- in front of the build command. Afterwards compile_commands.json sits in the current folder, and clangd -- in Neovim, Helix or Geany -- understands the project.

Examples

Options

--

everything after is the build command

--output FILE

where to write (default compile_commands.json)

--append

add to the file instead of replacing it

Notes

• Only files that are compiled during the run are recorded: after a make that had nothing to do, the file is empty. Clean first.
• CMake and Meson write the same file themselves; Bear is for builds that do not.

See also clangd, make, cmake

ccache A compiler cache: a rebuild of unchanged code takes seconds instead of minutes.

Devtools · command-line tool · ccache 4.13.6 · stage 7 · Compilers, editors, Claude Code and the ~/code checkouts · man ccache(1) · home

needs hiredis, libxxhash, zstd-libs

On Copal: The catalogue's rebuild accelerator -- worth most on a Pi, where compiling is slow and the same sources are often built again after a make clean or a branch switch.

ccache [ccache options]
ccache [KEY=VALUE ...] compiler [compiler options]
compiler [compiler options]

The first form takes options described in COMMAND LINE OPTIONS below. The second form invokes
the compiler, optionally using configuration options as KEY=VALUE arguments. In the third
form, ccache is masquerading as the compiler as described in RUN MODES.

Use

Put it in front of the compiler. It remembers each compilation's result by its inputs; the same file with the same flags later comes from the cache. It is not switched on by default.

Examples

Options

-s, --show-stats

statistics: hits, misses, size

-z, --zero-stats

reset the statistics

-C, --clear

empty the cache

-M, --max-size SIZE

set the cache limit, e.g. 5G

-p, --show-config

the settings in force

Notes

• The cache is ~/.cache/ccache, 5 GB at most by default; on a small card, ccache -M 1G.
• /usr/lib/ccache/bin holds links named gcc, cc, g++ and the rest, which is what makes the PATH method cover everything.

See also gcc, clang, make, cmake

cgdb gdb with a source window above it, in the terminal: see the code as you step.

Devtools · terminal program · cgdb 0.8.0 · stage 7 · Compilers, editors, Claude Code and the ~/code checkouts · home

needs gdb, libncursesw, readline

On Copal: The catalogue's lightweight debugging front end: gdb's commands, with the current line shown in the source -- the simplest way to see where a program is, over SSH or on a console.

Use

Start it as you would gdb. The top half shows the source with the current line marked; the bottom half is gdb itself. Escape moves to the source window, i back to gdb.

Examples

Options

-d DEBUGGER

the gdb to run

--

the rest goes to gdb

Notes

• Build with -g: without debug information there is no source to show.
• Its settings go in ~/.config/cgdb/cgdbrc (for example set syntax=on, or a colour scheme).

See also gdb, lldb, pwndbg

cmake Generate a project's build files -- for ninja or make -- from its CMakeLists.txt.

Devtools · command-line tool · cmake 4.2.3 · stage 7 · Compilers, editors, Claude Code and the ~/code checkouts · man cmake(1) · home

needs libarchive, libcrypto3, libexpat, rhash-libs, libssl3, libuv, zlib

On Copal: Stage 7 installs it because a large share of C and C++ projects build only through it; several of the store's source builds do.

Generate a Project Buildsystem
 cmake [<options>] -B <path-to-build> [-S <path-to-source>]
 cmake [<options>] <path-to-source | path-to-existing-build>

Build a Project
 cmake --build <dir> [<options>] [-- <build-tool-options>]

Install a Project
 cmake --install <dir> [<options>]

Open a Project
 cmake --open <dir>

Run a Script
...

Use

Two steps, always in a separate build directory: configure (read CMakeLists.txt, find the compiler and libraries, write the build files), then build. Configure once; after that, only the build step.

Examples

Options

-B DIR

the build directory (made if missing)

-S DIR

the source directory (default: here)

-G NAME

the generator: Ninja, or "Unix Makefiles"

-D VAR=VALUE

set a cache variable: CMAKE_BUILD_TYPE, CMAKE_INSTALL_PREFIX...

--build DIR

build a configured tree

--install DIR

install it

--fresh

forget the cached configuration

-j N

with --build: parallel jobs

Notes

• The cache remembers. A changed compiler or a library installed after the first configure is not noticed until --fresh or rm -rf build.
• "Could NOT find Foo": install the library's -dev package (apk search -e foo-dev), then configure again with --fresh.
• CMAKE_BUILD_TYPE is empty by default: no optimisation and no debug information. Say Debug or Release.

See also ninja, make, gcc, clang

cppcheck Static analysis for C and C++: find bugs the compiler does not warn about.

Devtools · command-line tool · cppcheck 2.21.0 · stage 7 · Compilers, editors, Claude Code and the ~/code checkouts · man cppcheck(1) · home

needs pcre, tinyxml2

On Copal: The catalogue's C checker: out-of-bounds indexes, leaks, null pointers and uninitialised variables, found by reading the code, without running it.

cppcheck [--check-config] [--check-library] [-D<id>] [-U<id>] [--disable=<id>]
         [--enable=<id>] [--error-exitcode=<n>] [--errorlist] [--exitcode-suppress=<spec>]
         [--exitcode-suppressions=<file>] [--file-list=<file>] [--filesdir] [--force]
         [--fsigned-char] [--funsigned-char] [--help] [-I<dir>] [--includes-file=<file>]
         [--config-exclude=<dir>] [--config-excludes-file=<file>] [--include=<file>]
         [-i<dir>] [--inconclusive] [--inline-suppr] [-j<jobs>] [-l<load>]
         [--language=<language>] [--library=<cfg>] [--max-configs=<limit>]
         [--max-ctu-depth=<limit>] [--platform=<type>] [--quiet] [--relative-paths=<paths>]
         [--report-progress] [--report-type=<type>] [--rule=<rule>] [--rule-file=<file>]
         [--showtime=<mode>] [--std=<id>] [--suppress=<spec>] [--suppressions-list=<file>]
         [--suppress-xml=<.xml file>] [--template='<text>'] [--verbose] [--version] [--xml]
         [--xml-version=<version>]] [file or path] ...

Use

Point it at files or a folder. By default it reports only errors it is sure of; --enable widens it to warnings, style and performance.

Examples

Options

--enable=LIST

warning, style, performance, portability, all

--std=STD

the language standard: c11, c17, c++17...

--project=FILE

read files and flags from compile_commands.json

-I DIR

an include directory

--suppress=ID

silence one kind of message

-j N

use N threads

--xml

XML output, for the HTML report

Notes

• --enable=all also reports missingInclude for system headers; --suppress=missingIncludeSystem quiets it.
• cppcheck-gui and cppcheck-htmlreport come with its optionals.

See also gcc, clang, valgrind

ctags Universal Ctags: index a project's definitions, so an editor can jump to them.

Devtools · command-line tool · ctags 6.2.1 · stage 7 · Compilers, editors, Claude Code and the ~/code checkouts · man ctags(1) · home

needs jansson, yaml

On Copal: Stage 7 installs it: the tags file lets vim and Neovim jump to a function's definition in any language, even where no language server exists.

ctags [<options>] [<source_file(s)>]
etags [<options>] [<source_file(s)>]

Use

Run it at the top of a project; it writes a tags file. In vim or Neovim, Ctrl-] on a name jumps to where it is defined, Ctrl-T jumps back.

Examples

Options

-R

recurse into folders

--exclude=PATTERN

leave matching paths out

-f FILE

write to FILE instead of ./tags

--languages=LIST

index only these languages

--list-languages

list the languages

-x

print a cross-reference table instead of a file

Notes

• Re-run it after large changes: the tags file does not update itself.
• Add tags to .gitignore; it is generated, and large.

See also nvim, vim, clangd

doxygen Generate reference documentation -- HTML, with call graphs -- from comments in source code.

Devtools · command-line tool · doxygen 1.17.0 · stage 7 · Compilers, editors, Claude Code and the ~/code checkouts · man doxygen(1) · home

On Copal: The catalogue's API documenter for C, C++ and more: comments above functions become a browsable site, with diagrams drawn by Graphviz.

Use

Make a configuration file once with -g, set the project's name and input folder in it, then run doxygen: the site appears in html/.

Examples

Options

-g [FILE]

write a template configuration (default Doxyfile)

-u [FILE]

update an old configuration to this version

-s

with -g or -u: leave out the explanatory comments

Notes

• Out of the box it documents only commented items; EXTRACT_ALL = YES in the Doxyfile lists everything.
• HAVE_DOT = YES turns on call and include graphs, drawn with Graphviz, which is installed.
• Comments it reads start with /** or ///.

See also dot, mdbook

gdb The GNU debugger: stop a program, step through it, look at its state.

Devtools · terminal program · gdb 16.3 · stage 7 · Compilers, editors, Claude Code and the ~/code checkouts · man gdb(1) · home

needs musl-dbg, libdebuginfod, libexpat, gmp, xz-libs, mpfr4, libncursesw, python3

On Copal: Stage 7 installs it for C, C++, Rust and Go, and Neovim's F4 (Termdebug) is gdb in a split window. When a program crashes, gdb says where and why.

gdb [OPTIONS] [prog|prog procID|prog core]

Use

Start the program under gdb, set a breakpoint, run, and when it stops, look: the call stack, the variables, the next line. Build with -g first, or there is nothing to see but addresses.

Examples

Options

--args PROG ARGS

pass arguments to the program

-p, --pid PID

attach to a running process

--core FILE

examine a core dump

--tui

the text interface: source, prompt, registers

-q

no banner

-ex CMD

run a gdb command at start; repeatable

Notes

• Attaching to a process needs doas: ptrace is limited to a process's own children here (kernel.yama.ptrace_scope is 1).
• Core dumps are off (ulimit -c is 0). ulimit -c unlimited in the shell first, and a crash leaves core beside the program.
• In Neovim: F9 sets a breakpoint on the current line, F4 opens Termdebug, F8 / F10 / F11 continue, step over, step into.
• For Rust, rust-gdb prints Rust types properly; Go is better served by dlv.

See also gcc, valgrind, nvim, cgdb, lldb

just A command runner: a project's recipes -- build, test, deploy -- in a justfile.

Devtools · command-line tool · just 1.48.1 · stage 7 · Compilers, editors, Claude Code and the ~/code checkouts · man just(1) · home

On Copal: The catalogue's make for tasks rather than files: named recipes, arguments, and no tabs-versus-spaces trap.

just [--alias-style] [--allow-missing] [--ceiling] [--check] [--chooser] [--clear-shell-args]
[--color] [--command-color] [--cygpath] [--dotenv-filename] [-E|--dotenv-path] [-n|--dry-run]
[--dump-format] [--explain] [-g|--global-justfile] [--group] [--highlight] [-f|--justfile]
[--list-heading] [--list-prefix] [--list-submodules] [--no-aliases] [--no-deps] [--no-dotenv]
[--no-highlight] [--one] [-q|--quiet] [--set] [--shell] [--shell-arg] [--shell-command]
[--changelog] [--choose] [-c|--command] [--completions] [--dump] [-e|--edit] [--evaluate]
[--fmt] [--groups] [--init] [--json] [-l|--list] [--man] [-s|--show] [--summary] [--usage]
[--variables] [--tempdir] [--timestamp] [--timestamp-format] [-u|--unsorted] [--unstable]
[-v|--verbose]... [-d|--working-directory] [--yes] [-h|--help] [-V|--version] [ARGUMENTS]

Use

Write recipes in a justfile; just NAME runs one, just runs the first. Each recipe is a list of shell lines.

Examples

Options

-l, --list

list the recipes

-n, --dry-run

print the commands, run nothing

-f, --justfile F

use another justfile

--choose

pick a recipe from a list

-v

print each command as it runs

Notes

• A justfile recipe: a name and a colon, then the lines indented under it -- spaces or tabs, either works.
• Unlike make, just does not compare file times: a recipe always runs.

See also make

ltrace Watch the library calls a program makes: what it asks of libc and other libraries.

Devtools · command-line tool · ltrace 0.7.3 · stage 7 · Compilers, editors, Claude Code and the ~/code checkouts · man ltrace(1) · home

needs libelf

On Copal: strace's companion one level up: where strace shows the kernel calls, ltrace shows malloc, strcmp, getenv and the rest -- which settings a program reads and what it compares.

ltrace [-e filter|-L] [-l|--library=library_pattern] [-x filter] [-S] [-b|--no-signals] [-i]
[-w|--where=nr] [-r|-t|-tt|-ttt] [-T] [-F filename] [-A maxelts] [-s strsize] [-C|--demangle]
[-a|--align column] [-n|--indent nr] [-o|--output filename] [-D|--debug mask] [-u username]
[-f] [-p pid] [[--] command [arg ...]]

ltrace -c [-e filter|-L] [-l|--library=library_pattern] [-x filter] [-S] [-o|--output
filename] [-f] [-p pid] [[--] command [arg ...]]

ltrace -V|--version

ltrace -h|--help

Use

Run a program under it; each call into a shared library prints with its arguments and return value. -c counts them instead.

Examples

Options

-c

count calls instead of printing them

-e FILTER

only these calls

-f

follow child processes

-o FILE

write to FILE

-p PID

attach to a running process

-S

system calls too

Notes

• It sees calls into shared libraries only: a statically linked program shows nothing.
• Attaching with -p needs root, like strace.

See also strace, gdb

lua-language-server The Lua language server: completion, types, and errors as you type, in any editor.

Devtools · command-line tool · lua-language-server 3.16.1 · stage 7 · Compilers, editors, Claude Code and the ~/code checkouts · home

On Copal: Stage 7's server for Lua, which Neovim starts for .lua files -- the language Copal's own Neovim configuration is written in.

Use

The editor runs it; there is nothing to start by hand. From the shell, --check runs its diagnostics over a folder and reports what it finds.

Examples

Options

--check=DIR

run the diagnostics over DIR

--check_format=FMT

pretty (to stdout) or json (to a file)

Notes

• In Neovim it warns that vim is an undefined global until told the code runs inside Neovim: a .luarc.json with {"diagnostics.globals": ["vim"]}.
• A project's settings go in .luarc.json at its root.

See also lua5.4, nvim

meson A build system: configure a project into a build folder, then build it with ninja.

Devtools · command-line tool · meson 1.11.1 · stage 7 · Compilers, editors, Claude Code and the ~/code checkouts · man meson(1) · home

needs samurai, python3

On Copal: Stage 7's Meson, for the many C, C++ and GNOME projects that build with it -- several of Copal Apps' source builds among them.

Use

Two steps, as with CMake: meson setup configures into a build folder, meson compile (or ninja -C build) builds. Options are set at setup and changed later with meson configure.

Examples

Options

setup DIR

configure into DIR

compile -C DIR

build

test -C DIR

run the tests

install -C DIR

install (doas for /usr/local)

configure DIR

show or change options (-Dname=value)

setup --buildtype=T

debug, debugoptimized, release

setup --reconfigure

set up again in an existing folder

Notes

• meson setup prints which optional dependencies it found and which it did not: that list says which features the build will have.
• It writes compile_commands.json in the build folder for clangd.

See also ninja, cmake, make

pylsp The Python language server: completion, go-to-definition and lint for Python, in any editor.

Devtools · command-line tool · py3-lsp-server 1.14.0 · stage 7 · Compilers, editors, Claude Code and the ~/code checkouts · home

needs py3-docstring-to-markdown, py3-jedi, py3-lsp-jsonrpc, py3-pluggy, py3-setuptools, py3-ujson, py3-whatthepatch, py3-yapf

On Copal: Stage 7's server for Python, which Neovim and Helix start for .py files: definitions, references and hover documentation.

usage: pylsp [-h] [--tcp] [--ws] [--host HOST] [--port PORT]
             [--check-parent-process] [--log-config LOG_CONFIG |
             --log-file LOG_FILE] [-v] [-V]

Use

The editor runs it over stdin and stdout; there is nothing to start by hand. It finds modules as the Python it runs under does, so a project's virtual environment should be active when the editor starts.

Examples

Options

--tcp

serve over TCP instead of stdio

--host / --port

where, with --tcp

--log-file FILE

write its log to FILE

-v

more detail in the log

Notes

• Its checks come from plugins: pyflakes (errors) and pycodestyle (style), which Copal installs with it as optionals from 24 Sep 2026.
• Settings are passed by the editor, not a file of its own.

See also python3, nvim, hx

shellcheck Find bugs in shell scripts: quoting, portability, and the traps sh is full of.

Devtools · command-line tool · shellcheck 0.11.0 · stage 7 · Compilers, editors, Claude Code and the ~/code checkouts · man shellcheck(1) · home

needs libffi, gmp

On Copal: The catalogue's shell linter, and the one Copal's own scripts are written against: most of Copal is POSIX sh, and shellcheck knows which sh a script says it is.

shellcheck [OPTIONS...]  FILES...

Use

Run it on a script; each finding has a code (SC2086 and so on), a line, and an explanation. The script's first line decides the dialect it checks: #!/bin/sh is held to POSIX, #!/bin/bash allows bash.

Examples

Options

-s SHELL

check as sh, bash, dash or ksh

-x

follow sourced files

-e CODES

exclude these codes

-S LEVEL

minimum severity: error, warning, info, style

-f FORMAT

output format: tty, gcc, json, diff

Notes

• A finding can be silenced for one line with a comment above it: # shellcheck disable=SC2086, with the reason beside it.
• Every code has a page explaining it: search "shellcheck SC2086".

See also shfmt, busybox

shfmt Format shell scripts consistently -- and parse them, which catches syntax errors.

Devtools · command-line tool · shfmt 3.13.1 · stage 7 · Compilers, editors, Claude Code and the ~/code checkouts · man shfmt(1) · home

On Copal: The catalogue's shell formatter, shellcheck's partner: one style for every script in a project, applied by a command, not by hand.

shfmt [flags] [path...]

Use

With no options it prints the script reformatted. -d shows the changes as a diff, -w writes them back. Indentation and style are options.

Examples

Options

-d

print a diff instead of the result

-w

write the result back to the file

-l

list files whose formatting differs

-i N

indent with N spaces (0 means tabs, the default)

-p

POSIX sh only (same as -ln posix)

-ln LANG

the dialect: bash, posix, mksh, bats

-ci

indent switch cases

Notes

• A syntax error stops it with the line and column: shfmt -d doubles as a quick check that a script parses.
• It reads an .editorconfig, so a project's indentation can live there instead of in options.

See also shellcheck

strace Watch the system calls a program makes: which files it opens, what fails, and why.

Devtools · command-line tool · strace 6.19 · stage 7 · Compilers, editors, Claude Code and the ~/code checkouts · man strace(1) · home

needs libdw

On Copal: The catalogue's answer to "it just says error": strace shows the file a program could not find, the permission it was refused, the address it could not reach.

strace [-ACdffhikkqqrtttTvVwxxyyYzZ] [-a column] [-b execve] [-e expr]... [-I n] [-o file]
       [-O overhead] [-p pid]... [-P path]... [-s strsize] [-S sortby] [-U columns]
       [-X format] [--seccomp-bpf] [--stack-trace-frame-limit=limit] [--syscall-limit=limit]
       [--tips[=format]] { -p pid | [-DDD] [-E var[=val]]... [-u username] command [args] }

strace -c [-dfwzZ] [-b execve] [-e expr]... [-I n] [-O overhead] [-p pid]... [-P path]...
       [-S sortby] [-U columns] [--seccomp-bpf] [--syscall-limit=limit] [--tips[=format]] {
       -p pid | [-DDD] [-E var[=val]]... [-u username] command [args] }

strace --tips[=format]

Use

Run a program under it, or attach to one running. Each system call prints as a line: the call, its arguments, and its result -- a failure shows its error name, such as ENOENT (no such file).

Examples

Options

-f

follow child processes too

-e trace=SET

only these calls: openat, network, file, process...

-o FILE

write the trace to FILE

-c

count calls and time instead of printing them

-p PID

attach to a running process

-s N

show strings up to N characters (default 32)

-t / -T

timestamps / time spent in each call

Notes

• Attaching to a process needs root (ptrace_scope is 1); tracing a program you start yourself does not.
• strace-tui, one of its optionals, browses a saved trace file interactively.

See also ltrace, gdb, valgrind

valgrind Run a program under a checker that catches memory errors and leaks.

Devtools · command-line tool · valgrind 3.25.1 · stage 7 · Compilers, editors, Claude Code and the ~/code checkouts · man valgrind(1) · home

On Copal: On Alpine it is the memory checker: the compilers' AddressSanitizer runtime is not packaged. Stage 7 installs it where it exists -- everywhere but 32-bit ARMv6 (armhf).

valgrind [valgrind-options] [your-program] [your-program-options]

Use

Put valgrind in front of the command. The program runs perhaps twenty times slower, and every invalid read or write, use of freed memory and leak is reported with the line it came from -- if it was built with -g.

Examples

Options

--leak-check=full

report each leak in detail

--show-leak-kinds=all

include "still reachable" blocks

--track-origins=yes

trace uninitialised values to their source (slower)

--error-exitcode=N

exit N if errors were found

--tool=NAME

memcheck (default), massif, callgrind, cachegrind, helgrind

-q

only the errors

--log-file=FILE

report to FILE instead of the terminal

Notes

• Read the first error first. Later ones are often its consequences.
• "definitely lost" is a real leak; "still reachable" is memory held at exit, usually harmless.
• Build with -g -O0 (or -O1) for readable reports; optimised code reports lines that do not match the source.

See also gdb, gcc, clang

7z 7-Zip: pack and unpack .7z, zip, tar and more, and extract rar, iso and dozens of others.

Discs · command-line tool · 7zip 26.01 · stage 10 · Wireless, audio, capture and disks · home

On Copal: The catalogue's universal archiver: the best compression of the common formats, strong encryption, and it opens nearly any archive someone sends you -- rar included.

Usage: 7zz <command> [<switches>...] <archive_name> [<file_names>...] [@listfile]
<Commands>
  a : Add files to archive

Use

A command letter, the archive, then files. x extracts with folders, a adds, l lists. It detects the format of what it opens.

Examples

Options

a

add to an archive (creating it)

x

extract with full paths

e

extract everything into one folder

l

list

t

test integrity

-o DIR

extract into DIR (written -oDIR, no space)

-p

set or ask for a password

-mx=N

compression level, 0 to 9 -m{...} other method settings: -mhe=on encrypts the file names too (.7z)

Notes

• The command here is 7z; guides that say 7za or 7zr mean the same program.
• -o takes its folder with no space: -oout, not -o out.
• It reads rar archives but cannot create them.

See also zip, bsdtar, unarj

abcde A Better CD Encoder: rip a CD, look up its track names, encode and tag, in one command.

Discs · command-line tool · abcde 2.9.3 · stage 12 · The application catalogue · man abcde(1) · home

needs bash, cd-discid, eyed3, perl-webservice-musicbrainz

On Copal: The catalogue's CD-to-music-library tool: cdparanoia to rip, a database lookup for the names, an encoder for FLAC, Ogg or MP3.

abcde [options] [tracks]

Use

Insert the CD and run it. It looks up the disc, asks you to confirm the names, rips every track and encodes them into folders by artist and album.

Examples

Options

-o FORMATS

output formats: flac, ogg, mp3, opus...

-N

non-interactive: accept the lookup's answer

-d DEV

the CD drive

-c FILE

another configuration file

-x

eject the CD when done

Notes

• Settings go in ~/.abcde.conf: OUTPUTTYPE, OUTPUTDIR, the naming pattern.
• Each format needs its encoder. Its default, Ogg, needs oggenc (vorbis-tools), which abcde does not pull in: the catalogue row brings it and flac from 24 Sep 2026. MP3 needs lame.
• Not on 32-bit ARMv7: its row is gated off there.

See also cdparanoia, cmus

bsdtar libarchive's tar: reads almost any archive -- tar, zip, 7z, rar, iso, cpio, deb, rpm, xar.

Discs · command-line tool · libarchive-tools 3.8.7 · stage 12 · The application catalogue · man bsdtar(1) · home

needs acl-libs, libbz2, libcrypto3, libexpat, lz4-libs, xz-libs, zlib, zstd-libs

On Copal: The catalogue's universal unpacker. One command extracts whatever format someone sent, detecting it and its compression by itself.

tar [bundled-flags ⟨args⟩] [⟨file⟩ | ⟨pattern⟩ ...]
tar {-c} [options] [files | directories]
tar {-r | -u} -f archive-file [options] [files | directories]
tar {-t | -x} [options] [patterns]

Use

The tar options, on any format: -t lists, -x extracts, -c creates. Compression is detected when reading; when creating, -a picks it from the file name.

Examples

Options

-t

list the contents

-x

extract

-c

create

-f FILE

the archive (- for stdin or stdout)

-C DIR

change into DIR first

-a

with -c: compression from the suffix (.gz .xz .zst .zip ...)

-v

name each file

-z / -j / -J

gzip / bzip2 / xz, when creating without -a

Notes

• tar on Copal is GNU tar; bsdtar is the one that also opens zip, 7z, ISO and rar.
• It reads rar, but writes only the formats it lists in its manual: tar, zip, 7z, iso, cpio and others.

See also 7z, zip, xorriso, rpm, dpkg

cdparanoia Rip audio CDs to WAV files, correcting for scratches and drive errors.

Discs · command-line tool · cdparanoia 10.2 · stage 12 · The application catalogue · man cdparanoia(1) · home

needs cdparanoia-libs

On Copal: The catalogue's CD ripper: it reads each sector until it is sure, which is what makes a rip from a worn disc sound like the disc.

cdparanoia [options] span [outfile]

Use

With a CD in the drive, rip every track, or chosen ones, to WAV files in the current folder. The progress line shows how hard it had to work.

Examples

Options

-B

batch: every track, each to its own file

-Q

query the disc and print its table of contents

-d DEV

the drive to use

-X

abort on a skip rather than filling it in

-z

never skip: retry an unreadable sector forever

Notes

• For MP3, FLAC or Ogg with names and tags, abcde runs cdparanoia and an encoder together.
• The drive needs the cdrom group.

See also abcde, cdrdao

cdrdao Write CDs in disc-at-once mode: audio CDs, gapless, from a TOC or CUE file.

Discs · command-line tool · cdrdao 1.2.6 · stage 12 · The application catalogue · man cdrdao(1) · home

On Copal: The catalogue's audio CD writer: disc-at-once keeps the gaps between tracks exactly as described, which track-at-once cannot.

cdrdao
{show-toc|toc-info|toc-size|read-toc|read-cd|read-cddb|show-data|read-test|disk-info|discid|msinfo|drive-info|unlock|scanbus|simulate|write|copy|blank}
[--device device] [--source-device device] [--driver driver-id] [--source-driver driver-id]
[--simulate] [--speed writing-speed] [--blank-mode mode] [--datafile file] [--read-raw]
[--read-subchan [--no-mode2-mixed] mode] [--tao-source] [--tao-source-adjust link-blocks]
[--fast-toc] [--buffers buffer-count] [--multi] [--overburn] [--eject] [--swap] [--session]
[--force] [--reload] [--keepimage] [--on-the-fly] [--paranoia-mode mode] [--with-cddb]
[--cddb-servers server-list] [--cddb-timeout timeout] [--cddb-directory directory] [--tmpdir
directory] [--keep] [--save] [-n] [-v verbose-level] toc-file

Use

Describe the disc in a table of contents (a .toc or .cue file) that lists the WAV files, then write it. It can also copy a whole CD.

Examples

Options

write TOC

burn the disc described in TOC

read-cd TOC

read a CD into an image and a TOC

show-toc TOC

print what a TOC describes

scanbus

list drives

--device DEV

the drive (/dev/sr0)

--speed N

the writing speed

--eject

eject when done

Notes

• A TOC file is plain text: one TRACK AUDIO block per track, each with FILE "track01.wav" 0.
• Access to the drive is the cdrom group's.

See also cdparanoia, abcde, xorriso

cdw A terminal front end for burning CDs and DVDs: data discs, ISO images, erasing.

Discs · terminal program · cdw 0.8.1 · stage 12 · The application catalogue · man cdw(1) · home

needs cdrkit, libburn, libcdio, libformw, libintl, libmenuw, libncursesw, libpanelw

On Copal: The catalogue's disc burner for a machine with no desktop, driving the command-line burning tools through menus.

cdw [--help] [--version] [--enable-dvd-rp-dl] [--escdelay=X]

Use

Start it with a burner attached; pick files or an ISO image from the menus, and write them. It calls the underlying tools (xorriso and others) and shows what they report.

Examples

Options

Notes

• Writing needs access to the drive, /dev/sr0, which the group cdrom owns: doas adduser $USER cdrom, then log in again.
• Its settings, including which drive and which tools, are in its configuration window and ~/.cdw/cdw.conf.

See also xorriso, cdrdao, cdparanoia

dpkg Look inside Debian and Ubuntu packages: list, inspect and unpack .deb files.

Discs · command-line tool · dpkg 1.23.7 · stage 12 · The application catalogue · man dpkg(1) · home

needs tar, xz, libbz2, libmd, zlib

On Copal: The catalogue's way to open a .deb on Alpine, to see what it holds or take files out of it. Not for installing: Alpine's packages are apk's.

dpkg [option...] command

Use

dpkg-deb does the looking: -c lists the files, -I shows the package's information, -x extracts the files into a folder.

Examples

Options

-c, --contents

list the contents (as dpkg-deb -c)

-I, --info

show the package information

-x DIR

extract the files into DIR (with dpkg-deb)

-e DIR

extract the control files (with dpkg-deb)

Notes

• dpkg -i would install into a Debian database that nothing here reads: do not. The program inside is built for glibc and will not run on musl as it is.
• bsdtar -xf package.deb shows the layers: control.tar.* and data.tar.*, the second holding the files.

See also rpm, bsdtar, apk

mksquashfs Pack a folder into a SquashFS image -- compressed, read-only, mountable -- and unsquashfs to unpack one.

Discs · command-line tool · squashfs-tools 4.7.5 · stage 12 · The application catalogue · man mksquashfs(1) · home

needs lz4-libs, xz-libs, lzo, zlib, zstd-libs

On Copal: The catalogue's SquashFS tools: the format of live systems and of Alpine's own boot images, and a way to keep a large folder compressed yet browsable.

mksquashfs source1 source2 ...  FILESYSTEM [OPTIONS] [-e list of exclude dirs/files]

Use

mksquashfs FOLDER IMAGE writes a compressed image of the folder. Mount it read-only to use the files in place, or unsquashfs to get them back.

Examples

Options

-comp ALG

compression: gzip, xz, lz4, zstd, lzo

-b SIZE

block size (larger compresses better)

-e NAMES

exclude these files

-noappend

overwrite the image rather than add to it

-processors N

threads to use

Notes

• Without -noappend, a second run adds to an existing image rather than replacing it.
• The image is read-only by design; to change it, unpack, edit, and pack again.

See also bsdtar, xorriso

rpm Look inside Red Hat, Fedora and SUSE packages: list, inspect and unpack .rpm files.

Discs · command-line tool · rpm 4.19.1.1 · stage 12 · The application catalogue · man rpm(8) · home

needs rpm-scripts, acl-libs, libarchive, libbz2, libcap2, libcrypto3, libdw, libelf

On Copal: The catalogue's way to open a .rpm on Alpine -- to read what a package holds, or take one file out of it. Not for installing: Alpine's packages are apk's.

QUERYING AND VERIFYING PACKAGES:
    rpm {-q|--query} [select-options] [query-options]

    rpm --querytags

    rpm {-V|--verify} [select-options] [verify-options]

INSTALLING, UPGRADING, AND REMOVING PACKAGES:
    rpm {-i|--install} [install-options] PACKAGE_FILE ...

    rpm {-U|--upgrade} [install-options] PACKAGE_FILE ...

    rpm {-F|--freshen} [install-options] PACKAGE_FILE ...

...

Use

Query a package file with -qp and a second letter for what to show. To unpack it, turn it into a cpio stream with rpm2cpio.

Examples

Options

-q, --query

query mode

-p, --package

query a package file (not an installed package)

-l, --list

list its files

-i

with -q: its information

--scripts

with -q: its install scripts

Notes

• rpm -i would try to install into an rpm database Alpine does not use: do not. A program packaged only as .rpm needs rebuilding for Alpine, or a Flatpak.
• A .rpm is built for glibc; its binaries will not run on musl as they are.

See also dpkg, bsdtar, apk

unarj List, test and extract .arj archives -- the DOS-era format.

Discs · command-line tool · unarj 2.65 · stage 12 · The application catalogue · home

On Copal: The catalogue's key to old archives: software and files from the 1990s, BBS downloads and old disk images often arrive as .arj.

Use

A command letter, then the archive. It only reads: it cannot make .arj files.

Examples

Options

l ARCHIVE

list

t ARCHIVE

test

x ARCHIVE

extract with paths

e ARCHIVE

extract without paths

Notes

• It is the free demonstration version: it reads ordinary archives but not multi-volume or password-protected ones. 7z x old.arj handles more.
• Names from DOS come in capitals and 8.3 form, as they were stored.

See also 7z, bsdtar, zip

xorriso Make ISO 9660 images and burn them: data discs, bootable images, and updates to both.

Discs · command-line tool · xorriso 1.5.8 · stage 12 · The application catalogue · man xorriso(1) · home

needs libisoburn

On Copal: The catalogue's ISO tool, and the one that makes bootable images: its -as mkisofs mode takes the options of the classic mkisofs.

xorriso [settings|actions]

Use

Build an image from a folder, burn an image to a disc, or list and extract what an image holds. -as mkisofs and -as cdrecord accept the older tools' options, which is what most recipes online use.

Examples

Options

-as mkisofs

behave like mkisofs (-o OUT, -J, -R, -V LABEL)

-as cdrecord

behave like cdrecord (dev=, -v, blank=)

-indev FILE

read an existing image or disc

-outdev FILE

write to an image or disc

-ls PATH

list a folder inside the image

-extract A B

copy A from the image to B (with -osirrox on)

-devices

list optical drives

Notes

• -J -R add Joliet and Rock Ridge: long names for Windows and Unix. Without them names are cut to 8.3 capitals.
• Burning needs the cdrom group, which owns /dev/sr0.

See also cdw, cdrdao, bsdtar

zip Make .zip archives -- and, with unzip, list and extract them.

Discs · command-line tool · zip 3.0 · stage 12 · The application catalogue · man zip(1) · home

needs unzip

On Copal: The catalogue's zip pair: the archive format every other system opens without asking, for sending folders to Windows and Mac users.

zip [-aABcdDeEfFghjklLmoqrRSTuvVwXyz!@$] [--longoption ...] [-b path] [-n suffixes] [-t date]
[-tt date] [zipfile [file ...]] [-xi list]

zipcloak (see separate man page)

zipnote (see separate man page)

zipsplit (see separate man page)

Note:  Command line processing in zip has been changed to support long options and handle all
options and arguments more consistently.  Some old command lines that depend on command line
inconsistencies may no longer work.

Use

zip ARCHIVE FILES adds files to an archive, creating it if needed; -r takes whole folders. unzip extracts, unzip -l lists.

Examples

Options

-r

include folders, recursively

-e

encrypt, asking for a password

-9

best compression (-1 fastest)

-u

update: add only changed files

-x PATTERN

leave matching files out

-q

quiet

Notes

• zip's own password encryption is weak. For real secrecy use 7z a -p -mhe=on, which is AES-256 and hides the file names too.
• zip -r stores paths as given: zip -r a.zip /home/you/x stores the full path, so change into the folder first for short ones.

See also unzip, 7z, bsdtar

lsblk List the disks and partitions, as a tree, with sizes and mount points.

Disks · lsblk 2.42.3 · stage 5 · Compressed swap in RAM (zram) · man lsblk(8) · home

needs libblkid, libmount, libncursesw, libsmartcols

On Copal: The answer to "which device is the card" before anything that writes to one -- sfdisk, dd, mkfs. Stage 5 installs util-linux, which brings it; BusyBox has no lsblk.

lsblk [options] [device...]

Use

Show every block device: whole disks, their partitions beneath them, and where each is mounted. Run it before and after plugging something in and the new line is the new device.

Examples

Options

-f, --fs

filesystem type, label, UUID, available space, use

-o, --output LIST

choose the columns; -H lists them all

-p, --paths

full device paths

-d, --nodeps

whole disks only

-l, --list

a flat list instead of the tree

-J, --json

JSON output

-b, --bytes

sizes in bytes

Notes

• The names say the bus: mmcblk0 is an SD card (partitions mmcblk0p1), sda a USB or SATA disk (sda1), nvme0n1 an NVMe drive (nvme0n1p1), vda a virtual machine's disk. A Pi booting from USB has its root on sda, not mmcblk0.
• -f without root shows blank FSTYPE and UUID columns: reading them means reading the device. Use doas lsblk -f.
• zram0 with [SWAP] is Copal's compressed swap in RAM (stage 5), not a disk.

See also sfdisk, resize2fs, zramctl, dmesg

resize2fs Grow or shrink an ext4 filesystem to fit its partition.

Disks · e2fsprogs-extra 1.47.4 · stage 2 · Format p2 and move the apk cache · man resize2fs(8) · home

needs e2fsprogs, libblkid, libcom_err, e2fsprogs-libs, libuuid

On Copal: The second half of stage 8: after sfdisk makes the root partition fill the disk, resize2fs makes the filesystem fill the partition -- while it is mounted as /.

resize2fs [ -fFpPMbs ] [ -d debug-flags ] [ -S RAID-stride ] [ -z undo_file ] device [ size ]

Use

Given only a device, grow its ext2/3/4 filesystem to the size of the partition. Growing works while mounted; shrinking needs the filesystem unmounted and checked first.

Examples

Options

SIZE

the new size: 20G, 500M; none means the partition's size

-P

print the minimum size and change nothing

-M

shrink to that minimum

-p

show progress

-f

force: skip the safety checks

Notes

• Order matters. To grow: partition first (sfdisk), then resize2fs. To shrink: resize2fs first, then the partition -- the other way round cuts the end off the filesystem.
• "Please run 'e2fsck -f' first" before a shrink is not optional: it needs a clean check since the last mount. That means from another system, or another card, for the root.
• ext4 only. The FAT boot partition (p1) is not resized by this.

See also sfdisk, lsblk

sfdisk Read, save, restore and change a disk's partition table, from a script.

Disks · sfdisk 2.42.3 · stage 8 · Grow p2 into the free space · man sfdisk(8) · home

needs libfdisk, libncursesw, libsmartcols

On Copal: Stage 8 grows the root partition into the rest of the disk with it, while that partition is mounted -- which parted refuses to do. The same one line claims the space after a VM's disk is enlarged.

sfdisk [options] device [-N partition-number]

sfdisk [options] command

Use

Print a partition table, dump it to a file you can restore, or rewrite it from lines of input. It never prompts, which is what makes it the tool for a script -- and the one to run with -n first.

Examples

Options

-l, --list

list the partitions

-F, --list-free

list the free areas

-d, --dump

the table as sfdisk input, to save

-N, --partno N

change partition N only

-n, --no-act

do everything but write

--no-reread

do not refuse because the disk is in use

-X, --label TYPE

create a new table: dos or gpt

--delete DEV [N]

delete partitions

-q, --quiet

fewer messages

Notes

• ', +' means: keep the start, make it as large as possible. Changing the table does not change the filesystem inside: grow that with resize2fs afterwards.
• On a disk in use -- the one you booted from -- sfdisk refuses unless given --no-reread, and the kernel keeps the old sizes until told: partx -u DISK, as stage 8 does, or a reboot. That refusal is about the kernel's copy of the table, not a danger to the data.
• Keep a dump before any change. A table restored from sfdisk -d output gives back every partition, data included, as long as nothing has been formatted in the meantime.

See also lsblk, resize2fs

zramctl Show and set up zram devices: compressed swap in RAM.

Disks · util-linux-misc 2.42.3 · stage 5 · Compressed swap in RAM (zram) · man zramctl(8) · home

needs setarch, libblkid, libfdisk, libmount, libncursesw, libsmartcols, utmps-libs, libuuid

On Copal: Stage 5 gives every Copal machine a zram swap half the size of RAM, compressed with lz4 -- on a 512 MB board the largest single win, and it spares the card the writes of disk swap.

Get info:
    zramctl [options]

Reset zram:
    zramctl -r zramdev...

Print name of first unused zram device:
    zramctl -f

Set up a zram device:
    zramctl [-f | zramdev] [-s size] [-t number] [-a algorithm]

Use

With no arguments, show each zram device: its size, how much is stored in it and how small that compressed to. Copal sets zram up at boot from /etc/local.d/zram.start; zramctl is for looking, or for changing it.

Examples

Options

-s, --size SIZE

the device size: 512M, 1G

-a, --algorithm ALG

lzo, lz4, lz4hc, deflate, 842 or zstd

-r, --reset DEVICE

empty and release a device

-f, --find

the first free device

-o, --output LIST

choose the columns

-b, --bytes

sizes in bytes

Notes

• DISKSIZE is the most it will take, not memory spent: RAM is used only for what is stored, compressed. DATA against COMPR is the ratio -- usually 2 to 3 times.
• A change made with zramctl is gone at the next boot. To change the size for good, edit the disksize line in /etc/local.d/zram.start.
• zram is swap, not more memory: a machine that swaps constantly is slow either way. Its gain is that a burst -- a big build, a browser -- no longer ends in the out-of-memory killer.

See also lsblk, dmesg

pdftotext Pull the text out of a PDF -- and, with the other poppler tools, split, join and inspect PDFs.

Documents · command-line tool · poppler-utils 25.12.0 · stage 12 · The application catalogue · man pdftotext(1) · home

needs cairo, freetype, libintl, lcms2, poppler

On Copal: The catalogue's PDF toolkit (poppler-utils): search a PDF with grep, read one over SSH, or feed it to a script. Its siblings pdfinfo, pdfunite, pdfseparate and pdftoppm come in the same package.

pdftotext [options] PDF-file [text-file]

Use

pdftotext FILE.pdf writes FILE.txt; with - as the output it prints to the terminal. -layout keeps columns and tables where they were, instead of reflowing the text.

Examples

Options

-layout

keep the physical layout: columns, tables

-f N

-l N the first and last page

-raw

the text in the order it is stored

-enc UTF-8

the output encoding

-nopgbrk

no form feed between pages

-

as the output file: stdout

Notes

• A scanned PDF is pictures of pages and has no text to extract: the output is empty. Run the pages through tesseract (from pdftoppm's images) to get text.
• Multi-column papers come out interleaved without -layout, and hyphenated at line ends either way.

See also qpdf, tesseract

qpdf Rewrite PDFs without changing their content: split, merge, rotate, decrypt, repair.

Documents · command-line tool · qpdf 12.3.2 · stage 12 · The application catalogue · man qpdf(1) · home

needs qpdf-libs

On Copal: The catalogue's PDF surgeon. It works on the PDF's structure, not its pictures, so nothing is re-rendered or lost -- and it repairs files other programs refuse to open.

qpdf [ options ] infilename [ outfilename ]

Use

Read one PDF and write another, with pages chosen, rotated or merged on the way. --empty --pages builds a new file from pages of others; --check reports what is wrong with a damaged one.

Examples

Options

--empty

start from an empty PDF (with --pages)

--pages F R ... --

pages R of file F, in order; . is the input file

--split-pages

write each page (or group) as its own file

--rotate=[+-]DEG:R

rotate pages R

--decrypt

remove encryption (with --password)

--linearize

optimise for fast web viewing

--check

check the structure and report

--show-npages

the page count

Notes

• Page ranges: 1-5, 3,7,9, z is the last page, r1 counts from the end, 1-z:odd every odd page.
• --decrypt needs the password when there is one to open it; for a file that opens freely but forbids printing, no password is asked.
• It never re-compresses images, so output is the same quality -- and roughly the same size -- as the input.

See also pdftotext

sc-im A spreadsheet in the terminal, with vim's keys: formulas, CSV, and Excel import.

Documents · terminal program · sc-im 0.8.5 · stage 12 · The application catalogue · man sc-im(1) · home

needs libncursesw, libxml2, libzip

On Copal: The catalogue's spreadsheet for a machine with no desktop, or for a quick sum over SSH. It opens CSV and XLSX, and writes both back.

sc-im [OPTION]... [FILE]

Use

Move between cells with vim's keys, type = to enter a number or a formula, < or > for text. :w saves in its own format; CSV and tab-separated files open and export directly.

Examples

Options

--nocurses

no screen: print the sheet and read commands from stdin

--quit_afterload

leave after loading (with --nocurses: a print)

--sheet=SHEET

which sheet of an XLSX to open

--xlsx_readformulas

import formulas from XLSX, not only their values

--output=FILE

where --nocurses writes

Notes

• Formulas use sc's functions with an @: @sum, @avg, @max, @if. Excel's SUM() spelling is not understood.
• It exports as well as imports: :e xlsx FILE for a spreadsheet program, :e mkd FILE for a Markdown table, :e txt for plain text.
• :help is the full manual, inside the program.

See also vim, python3

hx Helix: a modal editor with selections first, and a language server and syntax trees built in.

Editors · terminal program · helix 25.07.1 · stage 12 · The application catalogue · home

On Copal: The catalogue's modern modal editor: what nvim needs a config for, Helix does out of the box -- completion, go-to-definition, and a menu for every key. Its command is hx.

Use

Modal like vim, but the selection comes first and the action second: w selects a word, then d deletes it. Press Space for a menu of pickers and commands; every menu says what each key does.

Examples

Options

--tutor

the tutorial

--health [LANG]

check the language servers and grammars

-c, --config FILE

another config file

--vsplit / --hsplit

open the files in splits

-w, --working-dir D

start in directory D

+N

open the first file at line N

Notes

• Language servers are programs of their own: hx --health shows which are found. Stage 7's clangd, rust-analyzer, gopls and pylsp are.
• Config is ~/.config/helix/config.toml; themes are one line: theme = "onedark".
• Vim habits misfire: dw is wd here, and there is no :s -- select, then s to select within, then c to change.

See also nvim, vim, micro

micro A terminal text editor with the keys of a desktop editor: Ctrl-S, Ctrl-C, Ctrl-V, the mouse.

Editors · terminal program · micro 2.0.15 · stage 12 · The application catalogue · man micro(1) · home

On Copal: The catalogue's editor for anyone who does not want modes. Copy and paste reach the desktop clipboard, and the mouse selects text.

micro [OPTION]... [FILE]... [+LINE[:COL]] [+/REGEX]
micro [OPTION]... [FILE[:LINE[:COL]]]...  (only if the `parsecursor` option is enabled)

Use

Open a file and type. Ctrl-S saves, Ctrl-Q quits, Ctrl-Z undoes, and Ctrl-E opens a command prompt for anything else. Syntax colours, multiple cursors and splits come built in.

Examples

Options

+N

open at line N

-clean

ignore the configuration

-config-dir DIR

use another configuration directory

-plugin install P

install a plugin; remove to take it out

-options

list every setting and its default

Notes

• Settings are in ~/.config/micro/settings.json, keys in bindings.json; Ctrl-E then set tabsize 4 changes and saves one.
• Copy and paste reach the desktop's clipboard through wl-copy and wl-paste (its clipboard setting is external).
• Ctrl-E help opens the manual inside the editor.

See also nano, nvim, hx

nano The simplest terminal editor: type, and the keys are listed at the bottom.

Editors · terminal program · nano 9.2 · stage 12 · The application catalogue · man nano(1) · home

needs libncursesw

On Copal: The catalogue's editor for anyone new to the terminal, and the one to reach for to change a config file quickly -- nothing to learn before the first edit.

nano [options] [[+line[,column]] file]...

nano [options] [[+[crCR]{/|?}string] file]...

Use

Open a file and type. The two lines at the foot list the commands: ^ means Ctrl, M- means Alt. Ctrl-O saves ("write Out"), Ctrl-X leaves.

Examples

Options

-l, --linenumbers

show line numbers

-m, --mouse

use the mouse

-i, --autoindent

keep the indentation of the line above

-E, --tabstospaces

type spaces for Tab

-T N, --tabsize=N

tab width

-B, --backup

keep a backup (file~)

-v, --view

read-only

-/, --modernbindings

Ctrl-S, Ctrl-Q, Ctrl-C, Ctrl-V as elsewhere

Notes

• Settings go in ~/.config/nano/nanorc, one set per line: set linenumbers, set modernbindings.
• doas nano FILE edits as root. Keep root's edits to system files -- your own files edited as root end up owned by root.

See also micro, vim, nvim

vis A small vi-like editor with multiple selections and sam's structural regular expressions.

Editors · terminal program · vis 0.9 · stage 12 · The application catalogue · man vis(1) · home

needs !outils-vis, lua5.3-lpeg, acl-libs, lua5.3-libs, libncursesw, libtermkey

On Copal: The catalogue's lean modal editor: vi's keys in a fraction of vim's size, plus multiple cursors and sam-style editing for changing many places at once.

vis [-v] [+command] [--] [files ...]

Use

Edit as in vi. What it adds: several selections at once, all edited together, and :x/pattern/ command to select every match in the selection and act on each.

Examples

Options

-v

the version

--

everything after is a file name

Notes

• Configuration is Lua: ~/.config/vis/visrc.lua.
• It is vi, not vim: no :s///. :x/old/ c/new/ over the selection (:, for the whole file) does the same job.

See also vim, nvim, hx

qemu-system-x86_64 Emulate a whole 64-bit PC: boot another operating system inside a window on the Pi.

Emulation · command-line tool · qemu-system-x86_64 11.0.3 · stage 18 · The Copal Store, and OpenShot compiled · on the Copal Apps shelf · home

needs qemu, qemu-edk2-i386-vars, libaio, libbpf, capstone, libdw, libfdt, glib

On Copal: The store's PC emulator, on the 64-bit boards: run an x86 Linux, a BSD or DOS inside Copal. On an ARM board it emulates the CPU in software, so it works everywhere and fast nowhere.

usage: qemu-system-x86_64 [options] [disk_image]
'disk_image' is a raw hard disk image for IDE hard disk 0

Use

Make a disk image with qemu-img, then boot an installer ISO with it attached. -m sets the memory, -smp the CPUs; the display opens in a window.

Examples

Options

-m SIZE

memory: 1G, 2048M

-smp N

CPUs

-hda FILE

the first disk

-cdrom FILE

an ISO in the CD drive

-boot d

boot from the CD (c for the disk)

-nographic

no window: the console on this terminal

-accel NAME

tcg (software) is what an ARM board has

-bios FILE

firmware: /usr/share/qemu/edk2-x86_64-code.fd for UEFI

Notes

• On an ARM Pi there is no KVM for x86: every instruction is translated, so a guest runs at a small fraction of native speed. Small, text-mode systems are the good fit.
• qemu-img comes with it as an optional from 24 Sep 2026; before that, doas apk add qemu-img.
• 64-bit boards only: its row is gated to aarch64 and x86_64.

See also waydroid, mednafen

waydroid Run Android apps in a container on the desktop, each in its own window or a full Android screen.

Emulation · command-line tool · waydroid 1.6.2 · stage 18 · The Copal Store, and OpenShot compiled · on the Copal Apps shelf · home

needs dnsmasq, gbinder-python, iptables, kmod, lxc, py3-dbus, py3-gobject3, py3-pyclip

On Copal: The store's Android layer: LineageOS in a container, sharing the Linux kernel, drawn through Wayland -- so it needs the Hyprland desktop, not i3.

usage: waydroid [-h] [-V] [-l LOG] [--details-to-stdout] [-v] [-q]
                {status,log,init,upgrade,session,container,app,prop,show-full-ui,first-launch,shell,logcat,adb,bugreport} ...
options:

Use

Initialise it once (it downloads the Android images, about a gigabyte), start the container service, then start a session from the desktop and open the full UI or single apps.

Examples

Options

init

set up the images (root)

container

start, stop, restart the container (root)

session start

start the Android session (as you, in the desktop)

show-full-ui

the whole Android screen

app install APK

install an app; app list the installed ones

prop

read and set Android properties

Notes

• It needs the kernel's binder, which Copal's kernel has built in, and a Wayland session: from i3 or over SSH it cannot draw.
• To start it at boot: doas rc-update add waydroid-container.
• Not on ARMv6: its row is gated off there.

See also scrcpy, qemu-system-x86_64

admesh Check an STL mesh, and repair it: close holes, fix normals, remove stray facets.

Engineering · command-line tool · admesh 0.98.5 · stage 12 · The application catalogue · man admesh(1) · home

On Copal: The catalogue's STL doctor: a model that a slicer rejects or prints wrong usually has a hole or a flipped face, and admesh reports and fixes both.

admesh [OPTION]... file

Use

Run it on an STL to see its statistics and problems. With options it repairs, scales, rotates or merges, and writes the result with --write-binary-stl or --write-ascii-stl.

Examples

Options

-b, --write-binary-stl=F

write the result as binary STL

-a, --write-ascii-stl=F

write it as ASCII STL

-f, --fill-holes

fill holes in the mesh

-d, --normal-directions

fix facets facing the wrong way

-u, --remove-unconnected

remove facets with no neighbours

-e, --exact

join edges that match exactly

--scale=FACTOR

scale the model

--x-rotate=DEG

rotate about X (also --y-rotate, --z-rotate)

--merge=FILE

add another STL into this one

Notes

• With no repair options it runs all of them; name one or more to run only those.
• It reads both ASCII and binary STL; binary output is several times smaller.

See also solvespace-cli

ngspice SPICE circuit simulation: transient, AC and DC analysis of a netlist.

Engineering · command-line tool · ngspice 46 · stage 12 · The application catalogue · man ngspice(1) · home

needs python3, libx11, libxaw, libxt, libgomp, libncursesw, readline

On Copal: The catalogue's circuit simulator, the standard open one: check a filter, an amplifier or a power supply before building it.

ngspice [options] [file ...]

Use

Describe the circuit as a netlist -- components, the nodes they join, their values -- and the analyses to run. Interactively it plots results as ASCII; in batch mode it writes them for another program to plot.

Examples

Options

-b, --batch

run and exit

-r, --rawfile FILE

write the results to FILE

-o, --output FILE

write the output to FILE

-i, --interactive

stay interactive even with a file on stdin

-n, --no-spiceinit

ignore .spiceinit files

Notes

• A netlist's first line is its title and is never read as a component -- a first component there silently disappears.
• gnuplot out v(out) at the prompt draws the plot with gnuplot, which the catalogue's Science section installs.

See also gnuplot, python3

solvespace-cli SolveSpace from the command line: export and render .slvs models without the window.

Engineering · command-line tool · solvespace 3.2 · stage 12 · The application catalogue · home

needs mesa-gl, atkmm2.28, cairo, fontconfig, freetype, gtk+3.0, gtkmm3, glib

On Copal: The catalogue's scripted CAD: the SolveSpace window designs a part, and this turns it into STL, a drawing or a picture in a Makefile.

Use

Name a command and the .slvs files to apply it to. --output is a pattern: % becomes each input file's name.

Examples

Options

export-mesh

a triangle mesh (STL, OBJ...)

export-view

a 2D view (SVG, DXF, PDF...), --view VIEW

export-surfaces

exact surfaces (STEP)

thumbnail

a rendered picture, --size WxH

regenerate

reload, regenerate and save

-o, --output PAT

the output name: % is the input's name

-v, --view DIR

top, bottom, left, right, front, back, isometric

-t, --chord-tol N

how finely curves become straight segments

Notes

• The output format follows the extension of --output: .stl or .obj for a mesh, .svg, .dxf or .pdf for a view.
• --chord-tol is in millimetres for exports: smaller is smoother and larger.

See also admesh, solvespace

fdupes Find duplicate files -- identical contents, whatever their names -- and optionally delete them.

Files · command-line tool · fdupes 2.4.0 · stage 18 · The Copal Store, and OpenShot compiled · on the Copal Apps shelf · man fdupes(1) · home

needs libncursesw, libpcre2-32, sqlite-libs

On Copal: The store's duplicate finder: photos copied twice, downloads saved again, backups of backups. It compares sizes, then checksums, then bytes, so a match is exact.

fdupes [ options ] DIRECTORY ...

Use

Point it at folders; it prints each set of identical files together. Look at the list before deleting anything; -d then asks, set by set, which copy to keep.

Examples

Options

-r, --recurse

go into subfolders

-S, --size

show sizes

-m, --summarize

only the totals

-n, --noempty

ignore empty files

-d, --delete

ask which file of each set to keep, delete the rest

-N, --noprompt

with -d: keep the first of each set without asking

-f, --omitfirst

list all but the first file of each set

Notes

• -dN deletes without asking, keeping whichever file happened to be listed first: check the list without -d first.
• Deleting is permanent; there is no bin. For a gentler clean-up, rdfind -makehardlinks true keeps every name and frees the space.

See also jdupes, rdfind

jdupes A faster fdupes: find duplicate files, and delete, hard-link or deduplicate them.

Files · command-line tool · jdupes 1.31.1 · stage 18 · The Copal Store, and OpenShot compiled · on the Copal Apps shelf · man jdupes(1) · home

needs libjodycode, libxxhash

On Copal: The store's fast duplicate finder: the same results as fdupes, much quicker on large folders, and able to replace copies with hard links instead of deleting.

jdupes [ options ] DIRECTORIES ...

Use

The same way as fdupes: point it at folders, read the sets, then decide. Beyond deleting, -L replaces duplicates with hard links, so every name stays and the space is freed.

Examples

Options

-r, --recurse

go into subfolders

-S, --size

show sizes

-m, --summarize

only the totals

-d, --delete

ask which to keep, delete the rest

-N, --no-prompt

with -d: keep the first without asking

-L, --link-hard

replace duplicates with hard links

-B, --dedupe

copy-on-write deduplication (Btrfs, XFS)

-Q, --quick

skip the final byte-by-byte check (faster, less sure)

Notes

• Hard links only work within one filesystem, and after linking, editing one name edits them all -- fine for photos, wrong for files you mean to change separately.
• -Q trades certainty for speed; leave it off before deleting.
• It comes from Alpine's testing repository (jdupes@testing).

See also fdupes, rdfind

mc Midnight Commander: a two-panel file manager for the terminal, with a viewer and an editor.

Files · terminal program · mc 4.8.33 · stage 4 · X.Org, i3, a terminal and a browser · man mc(1) · home

needs e2fsprogs-libs, glib, gpm-libs, libintl, slang, libssh2

On Copal: The catalogue's terminal file manager, and the first one Copal's menus open for files when there is no desktop. Its skin follows Copal's theme.

mc [-abcCdfhPstuUVx] [-l log] [dir1 [dir2]] [-e [file] ...] [-v file]

Use

Two panels, a folder in each. Select files on one side and copy or move them to the other with a function key; the keys are listed along the bottom. The command line under the panels still works as a shell.

Examples

Options

-b

monochrome

-d

no mouse

-u

no subshell (a faster start)

-e FILE

edit FILE, as mcedit

-v FILE

view FILE, as mcview

Notes

• A function key the terminal keeps for itself has an Esc equivalent: Esc then 0 is F10, Esc then 5 is F5.
• Ctrl-O hides the panels to show the shell underneath, and brings them back.
• Settings are in ~/.config/mc/ini; Copal writes only its skin= line.

See also nnn, ranger, rsync

nnn A tiny, fast terminal file manager, driven from the keyboard.

Files · terminal program · nnn 5.2 · stage 12 · The application catalogue · man nnn(1) · home

needs libncursesw, readline

On Copal: The catalogue's lightest file manager: it starts at once even on a Pi Zero, and stays out of the way.

nnn [-aAcCdDeEfgHJKnQrRSuUVxz0h] [-b key] [-F val] [-l val] [-p file] [-P key] [-s name]
    [-t secs] [-T key] [PATH]

Use

Move through folders with the arrows or h j k l, and open a file with Enter. Space selects; the selection can then be copied or moved into the folder you are in.

Examples

Options

-d

detail mode

-H

show hidden files

-e

open text files in $EDITOR, in the terminal

-o

open files only on Enter

Notes

• It opens files with xdg-open; without a desktop, -e keeps text files in $EDITOR.
• Quitting does not change the shell's folder: that takes the small quitcd shell function from nnn's documentation.

See also mc, ranger

ranger A terminal file manager in columns, with previews and vi keys.

Files · terminal program · ranger 1.9.4 · stage 12 · The application catalogue · man ranger(1) · home

needs python3

On Copal: The catalogue's file manager with the most on screen: the parent folder, the current one and a preview side by side.

ranger [--version] [--help] [--debug] [--clean] [--cachedir=directory] [--confdir=directory]
[--datadir=directory] [--copy-config=which] [--choosefile=target] [--choosefiles=target]
[--choosedir=target] [--selectfile=filepath] [--show-only-dirs] [--list-unused-keys]
[--list-tagged-files=tag] [--profile] [--cmd=command] [path ...]

Use

Three columns: the parent folder, the current one, and a preview of what is selected. h and l move out and in; Enter opens. Commands start with :, as in vim.

Examples

Options

--copy-config=WHICH

copy the default config into ~/.config/ranger

--choosefile=FILE

pick a file, and write its path to FILE

--cmd=CMD

run a ranger command at start

Notes

• Text previews work out of the box; previews of images and PDFs need helper programs.
• S opens a shell in the current folder; exit returns to ranger.

See also mc, nnn

rdfind Find redundant files across folders, ranked by which copy is the original, and act on them.

Files · command-line tool · rdfind 1.8.0 · stage 18 · The Copal Store, and OpenShot compiled · on the Copal Apps shelf · man rdfind(1) · home

needs nettle, libxxhash

On Copal: The store's duplicate finder for "which copy do I keep?": it ranks files by the order the folders were given, so the first folder's copies win -- right for clearing a backup against the originals.

rdfind [ options ] directory1 | file1 [ directory2 | file2 ] ...

Use

Name the folders, the one to keep first. By default it only writes a report, results.txt; options replace the later copies with links, or delete them. Try with -dryrun true before changing anything.

Examples

Options

-dryrun true

say what would change, change nothing

-deleteduplicates true

delete all but the highest-ranked copy

-makehardlinks true

replace duplicates with hard links

-makesymlinks true

replace them with symbolic links

-makeresultsfile false

no results.txt

-ignoreempty true

skip empty files (the default)

Notes

• The order of the folders is the ranking: the first folder's copy is the one kept. Put the originals first.
• Options take true or false after them, unlike most commands.

See also fdupes, jdupes

adventure Colossal Cave Adventure: the first text adventure, from 1977.

Games · terminal program · bsd-games 3.3 · stage 4 · X.Org, i3, a terminal and a browser · man adventure(6) · home

needs libncursesw

On Copal: Part of the catalogue's BSD games (bsd-games): the ancestor of Zork and of every text adventure since, typed a command at a time.

Use

Read the description, type a command of one or two words -- go north, get lamp, open grate -- and read what happens. Map the cave on paper as you go; that is how it was meant to be played.

Examples

Options

Notes

• The first thing to do is take the lamp. The cave is dark.
• It understands the first five letters of a word: inven is inventory.
• help and info are commands too: the game explains itself.

See also frotz, nethack

angband Angband: a hundred-level descent to Morgoth, in the lineage of Moria.

Games · terminal program · angband 4.2.5 · stage 12 · The application catalogue · home

needs sdl2, sdl2_image, sdl2_mixer, sdl2_ttf, libncursesw

On Copal: The catalogue's long-form roguelike: a character built over many hours, a town to return to, and the dungeon from Tolkien's Moria onward.

Use

Create a character, buy supplies in the town, and descend. Levels are made afresh every time you take the stairs, so going back up and down is normal. ? is the help, Enter a menu of every command.

Examples

Options

-n

a new character (overwrites the default savefile, without -u)

-u NAME

use the savefile NAME

-l

list the savefiles

-c

choose a savefile from a menu

-w

bring a dead character back (marks the save)

Notes

• Your saves and settings are in ~/.angband, not in /usr/share.
• -n without -u replaces the default character. Name a new one: angband -n -uSomeone.
• It comes from Alpine's testing repository (angband@testing).

See also zangband, nethack, brogue

asciiquarium An aquarium in the terminal: fish, sharks, a castle and bubbles, animated.

Games · terminal program · asciiquarium 1.1 · stage 12 · The application catalogue · home

needs perl, perl-term-animation

On Copal: One of the catalogue's toys: something alive in a spare terminal or a tmux pane, and a quick test of a terminal's colours and speed.

Use

Run it, watch, press q to leave. It fills the terminal at whatever size it is, and redraws when the window changes.

Examples

Options

Notes

• It is a Perl program: the first frame takes a moment on a Pi.
• It ignores --help and simply starts.

See also cmatrix, cbonsai

atc Air Traffic Control: route planes through your airspace without a collision.

Games · terminal program · bsd-games 3.3 · stage 4 · X.Org, i3, a terminal and a browser · man atc(6) · home

needs libncursesw

On Copal: Part of the catalogue's BSD games, and the best of them -- unplayable until you have read man atc, and excellent afterwards.

atc [-u?lstp] [-gf game name] [-r random seed]

Use

Planes enter at the edges; guide each to its exit or airport at the right altitude, and keep them apart. Every command starts with the plane's letter, then the action and its value, and Enter sends it; ? lists what may come next at any point.

Examples

Options

-l

list the scenarios

-s

print the score table

SCENARIO

play that airspace: Default, Atlantis, Killer, OHare

Notes

• ba5 sends plane b to 5000 feet; btd turns it to heading east. Directions are the eight keys around s: w north, e north-east, d east, round to q north-west.
• Planes enter at 7000 feet and must leave through their exit at 9000, or land at their airport by going to 0 directly over it.

See also robots, snake

brogue Brogue: a roguelike made to be learned -- twenty-six levels, no classes, beautiful in a terminal.

Games · terminal program · brogue 1.15.1 · stage 12 · The application catalogue · home

needs sdl2, sdl2_image

On Copal: The catalogue's most approachable roguelike: fewer keys than NetHack, a mouse that works, and a dungeon that shows you what it is doing.

Use

Descend twenty-six levels to the Amulet of Yendor and back out. You build your character from what you find, not from a class. The mouse moves you and describes what you point at; ? lists the keys.

Examples

Options