Universal package management and SubOS environments
Options: -h, --help — Show help for the selected command; --version — Show version; -y, --yes — Skip confirmation prompts; --agent — Use stable plain-text output; -v, --verbose — Enable verbose output; -q, --quiet — Suppress non-essential output; --ui-mode <MODE> — Frontend for this run (cli/tui/auto)
Install packages
Options: -g, --global — Use global scope; -u, --use — Activate installed version; --reconfig — Run the configuration step again, even where it already ran; --subos <NAME> — Install into this subos instead of the current one; --system — Install into the system layer (/xlings): every user of this machine gets it
Remove a package
Options: -g, --global — Use global scope; --force — Remove even if packages depend on it, the recipe is gone, or its uninstall hook fails; --all — Remove every installed version, not just the active one; --all-subos — Remove from every subos that has it installed; --subos <NAME> — Act on this subos only, instead of the current one
Update package index or package
Search for packages
List installed packages
Options: -a, --all — Show every subos
Show package information
Options: --all-versions — Show every available version
Show why a dependency resolved to the version it did
Switch tool version
Options: -a, --all — Show every subos; --strict — Require a coherent release
Show or modify configuration
Options: --lang <LANG> — Set language; --mirror <MIRROR> — Set mirror; --ui-mode <MODE> — Set UI mode (cli/tui/auto); --theme <THEME> — Set colour theme (name, path, or list); --interactive <BOOL> — Inline prompts in tui mode; --add-xpkg <FILE> — Add package recipe; --list-xpkg — List local recipes and how they relate to the synced index; --remove-xpkg <NAME> — Remove one local recipe; --clear-xpkg <all|stale> — Remove local recipes (all, or stale = identical/behind the synced index); --index-repo <NS:URL> — Add index repository; --rm-index-repo <NAME> — Remove index repository
Manage SubOS environments
Create a SubOS
Options: --sandbox [PRESET] — Declare its isolation once: dev (default), private or locked; --storage <MODE> — shared, tmpfs or image; --image-size <SIZE> — Image size; --from <SOURCE> — Fork source; --runtime <SPEC> — Runtime binding, e.g. glibc@2.44; --rootfs — Make it a root: entered, exported or booted as /; --proxy <URL> — Its network goes only through this SOCKS5h proxy, from the first entry; --domain <HOME> — Build a rootfs at this logical home prefix in an owned namespace; --carrier <NAME> — Where it runs: local, wsl2 (Windows) or vz (macOS); default chosen by what it is; --abi <ABI> — native (this machine's programs) or linux
Enter a SubOS
Options: --global — Persist the active SubOS; --shell [KIND] — Emit shell activation code; --sandbox [BACKEND] — Enable sandbox (bwrap, proot or landlock on Linux); --sandbox=dev|private|locked picks a preset; --net <MODE> — This call only: host, nat, none or proxy (may only tighten); --proxy <URL> — SOCKS5h endpoint for net=proxy; --observe <LEVEL> — This call only: off, basic, standard or full; --fetch <ACTION> — This call only: auto, ask or deny (may only tighten); --allow <GRANT> — This call only: grant from the policy's grants_allowed; --no-degrade — Refuse to enter when anything asked for is missing; --mount <HOST[:INSIDE][:ro|rw]> — This call only: map a host path into the SubOS; repeatable; --cmd <COMMAND> — Run one command; --keep — Keep the session after the shell exits; --no-keep — End the session with the shell; --ttl <SECONDS> — Session idle timeout; --gpu — Expose GPU devices (bwrap only)
List SubOS environments
Remove a SubOS
Show SubOS details
Stop a SubOS's running session
Run a command in a SubOS from outside it
Options: --sandbox [BACKEND] — Run in the SubOS's sandbox (bwrap, proot or landlock on Linux); --sandbox=dev|private|locked picks a preset; --net <MODE> — This call only: host, nat, none or proxy (may only tighten); --proxy <URL> — SOCKS5h endpoint for net=proxy; --observe <LEVEL> — This call only: off, basic, standard or full; --fetch <ACTION> — This call only: auto, ask or deny (may only tighten); --allow <GRANT> — This call only: grant from the policy's grants_allowed; --no-degrade — Refuse to run when anything asked for is missing; --publish <HOST:SANDBOX> — With net=nat: publish a TCP port; repeatable; --mount <HOST[:INSIDE][:ro|rw]> — This call only: map a host path into the SubOS; repeatable; --cwd <DIR> — Working directory inside; --env <K=V> — Set a variable; repeatable; --timeout <DURATION> — End the command after DURATION (90, 30s, 10m, 2h); exits 124; --json — Print the result as JSON on stderr when the command ends; --temp — Use a throwaway SubOS, removed afterwards (its audit is kept); --from <SOURCE> — With --temp: fork it from this SubOS or package
Start a SubOS session that runs without a terminal
Options: --sandbox [BACKEND] — Sandbox backend (bwrap, proot or landlock); --sandbox=dev|private|locked picks a preset; --net <MODE> — host, nat, none or proxy (may only tighten); --proxy <URL> — SOCKS5h endpoint for net=proxy; --observe <LEVEL> — This call only: off, basic, standard or full; --allow <GRANT> — Grant from the policy's grants_allowed; --no-degrade — Refuse to start when anything asked for is missing; --publish <HOST:SANDBOX> — With net=nat: publish a TCP port; repeatable; --mount <HOST[:INSIDE][:ro|rw]> — This call only: map a host path into the SubOS; repeatable; --ttl <DURATION> — End after DURATION idle (90, 30s, 10m, 2h); default: until stop
Copy files into or out of a SubOS
Show or change what a SubOS may do (its policy)
Options: --sandbox <PRESET> — Start from a preset (dev, private, locked) or a policy package (ns:name[@version]); --policy-upgrade — Move to the newest version of the selected policy package; --net <MODE> — host, nat, none or proxy; --proxy <URL> — SOCKS5h endpoint for net=proxy; --tz <ZONE> — A neutral identity's time zone: utc, proxy (the proxy's exit) or a name such as Asia/Tokyo; --fetch <ACTION> — Installing a missing package from inside: auto, ask or deny; --index-update <ACTION> — Updating the index from inside: auto, ask or deny; --observe <LEVEL> — off, basic, standard or full; --allow <GRANT> — Grant display, audio, camera, gpu, ssh-agent, dbus or host-loopback; --disallow <GRANT> — Withdraw a grant; --grants-allowed <LIST> — Grants a single call may add; --env-pass <NAME> — Let this host variable in; NAME* for a prefix; --mount <HOST[:INSIDE][:ro|rw]> — Map a host path into the SubOS, every time it is entered; --unmount <PATH> — Stop mapping it; --no-degrade — Refuse to enter when anything asked for is missing; --degrade — Enter and report what is missing; --reset — Remove the policy file; --json — Machine-readable output
Show what a SubOS asks for and what this host gives it
Options: --json — Machine-readable output
Check each SubOS: policy, entry on this host, policy package, sessions
Options: --json — Machine-readable output; --fix — Re-install a selected policy package whose payload is missing
List what a SubOS's sandbox asked for and is waiting on
Options: --json — One JSON object per request
Run a request a SubOS's sandbox is waiting on
Refuse a request a SubOS's sandbox is waiting on
Summarise what happened in a SubOS: sessions, programs, permissions, files
Options: --session <ID> — Only this session; --json — Machine-readable output
List running SubOS sessions
Options: --json — One JSON object per session
Show a SubOS's audit events
Options: --kind <KIND> — Only this kind (ops, lifecycle, perm, exec, net, fs); repeatable; --session <ID> — Only this session; -n, --lines <N> — Show the last N events (default 50); -f, --follow — Keep printing new events; --json — One JSON object per event
Move a root SubOS back to an earlier generation
Options: --to <N> — This generation (default: the one before); --list — List the generations
Choose the SubOS a machine boots, from the next boot on
Options: --once — Only the next boot (a trial); --fallback — Boot it when the default fails; --mark-good — This boot worked: keep booting it; --now — Switch user space to it now, where the init can (no reboot)
Export a root SubOS as a directory, a tarball or a disk image
Options: --rootfs <DIR> — A root directory (chroot, bwrap, nspawn); --tar <FILE> — A root tarball (docker import, podman import, wsl --import); --disk <FILE> — An ext4 disk image to boot; --drive <FILE> — A drive image that boots a machine (GPT, UEFI and BIOS, an ext4 root); --qcow2 <FILE> — The drive image as qcow2 (qemu, clouds); --iso <FILE> — A live ISO: boots from a CD or a drive and runs from memory; --kernel <VMLINUZ> — The kernel a live ISO boots (default: the root's own); --size <SIZE> — Disk size (default 4G); --with-data — Include /root, /home, /var, /srv, /opt
Compare the packages of two SubOS
Pack a SubOS's declaration as a subos-type xpkg
Options: --as <NS:NAME@VERSION> — The package it becomes; --out <DIR> — Where the tarball goes
Rebind a SubOS to another runtime
Manage xlings itself
Install xlings
Uninstall xlings
Options: -y, --yes — Skip confirmation; --keep-data — Keep data; --dry-run — Preview
Initialize directories
Update xlings
Options: --user — Install into this home even when xlings is a system package's
Show configuration
Clean cache
Options: --dry-run — Preview
Migrate old layout
Verify installation
Options: --deep — Audit package payloads and runtime functionality; --scope <PACKAGE[@VERSION]> — Limit deep payload/runtime audit to one local package coordinate; --subos <NAME> — Check/repair one specific subos instead of the active one; --fix — Repair (implies --deep; walks every subos that owns a finding); --dry-run — Preview repairs without changing detection depth; --show-ok — Show all findings, including non-defects; --all — Deprecated alias for --show-ok; --reset-metadata — Discard unreadable metadata; --isolation — Check what this host can isolate SubOS sandboxes with; with --fix, install a root-owned bwrap and its AppArmor profile; --json — Machine-readable output (with --isolation)
Run an xlings script
Use the NDJSON interface
Options: --args <JSON> — Capability arguments; --args-file <PATH> — Read capability arguments from a file; --list — List capabilities; --version — Show protocol version
Inspect and select package index snapshots
List published index snapshots
Options: --json — Machine-readable output
Pin an index source to a snapshot
Agent integration
List or show built-in skills
Manage profile configuration
List recorded generations
Record the active generation
Restore a recorded generation