Skip to content
SYKhayyatPublic

About

Declare a machine in files — packages, services, settings, firewall rules, dotfiles — and sync it to match, driving the tools already installed

Topics

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

1,253 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Shall

Declarative configuration for a machine: you write down what it should have, and sync makes the machine match. The name is what a line in that file means: this machine shall have ripgrep.

New here and not a Rust programmer? You do not need Rust to use Shall. Install a release with the shell or PowerShell command below, then start with shall init, shall check, and shall sync. Rust, Cargo, and the source checkout are only needed if you want to develop Shall itself. For contributors, read Your first hour after the user workflow; you can make documentation, grammar examples, tests, and bug reports without knowing Rust, and the contributor guide explains the one command that validates a change.

Packages are the largest kind and not the only one. Repositories, services, schedules, symlinks, OS and desktop settings, scripts, generated declarations, dotfile trees and firewall rules are all declared in the same files, by the same grammar, and converged by the same sync.

Shall does not replace apt, pacman, brew, cargo or npm — nor systemd, ufw or gsettings. It drives them. One file says what the machine should have; shall sync adds what is missing, removes what is no longer listed, and leaves everything else alone.

$ cat ~/.config/shall/modules/tools.txt
apt:ripgrep
cargo:bat
npm:typescript@version=>=5.0.0

$ cat ~/.config/shall/profiles/Main
use tools

$ shall sync
Planned changes:
  install 3   remove 0   (total 3 change(s))

Delete the cargo:bat line and sync again, and bat is uninstalled. That is the whole idea: the file is the truth, and every command is a shortcut for editing it and syncing.

Note the second file. A module is a list; it does nothing until an active profile uses it. That indirection is what lets one repo describe several machines — see Profiles.


Contents

Getting going — Install · Start · The files · Configuration

Writing declarations — The grammar · Options · Which file gets installed · Storage you can declare · Host conditions · Profiles · Your own conditions

Beyond packages — Running a script · The firewall · A folder of dotfiles · Secrets

Running it — Commands · History and rollback · Locking · When sync says "nothing to do" · Exit codes

Trusting it — The removal guard · Safety · What has been driven

Extending it — Teaching Shall a package manager it has never heard of

Working on Shall itself? Your first hour, in order is the reading path — six documents, and which one to open first.

Inherited it, and something is red? docs/TAKING-OVER.md is the one to open — how to read the board, what each kind of failure means, and which ones are not yours to fix.


Install

curl -fsSL https://raw.githubusercontent.com/SYKhayyat/Shall/HEAD/scripts/install.sh | sh
irm https://raw.githubusercontent.com/SYKhayyat/Shall/HEAD/scripts/install.ps1 | iex

Either script downloads the published binary for your platform, runs shall check, and offers to adopt the packages already on the machine. Nothing else is needed — no toolchain, no compiler. Seven builds are published: Linux on x86_64 and arm64, against glibc and musl both; macOS on Intel and Apple silicon; and x86_64 Windows. Anywhere else the script falls back to building from source, which needs Rust and takes rather longer than thirty seconds. The scripts run --version on what they downloaded before trusting it, and build from source if it will not start.

SHALL_REF=v0.8.0 installs an exact release instead of the newest. From a checkout:

cargo build --release
cp target/release/shall ~/.local/bin/

Start

shall init              # scaffold ~/.config/shall, with one profile (Main) already active
shall apply apt:jq      # writes a line you own, then applies exactly it
shall check             # what needs you: drift, unmanaged, health — read-only
shall sync              # make the machine match the files

shall apply is not a separate mechanism — it writes the declaration into a module the active profile already reaches, then applies that one declaration and nothing else: apt:jq, dir:~/scratch, link:~/.vimrc @target=…. Anything it can do, editing the file does too. It is also the removal: shall apply apt:jq --delete takes the line out and undoes the thing. The whole-machine converge is sync, and apply says how many declarations are still pending.

Writing a module by hand takes one extra step, because a module is inert until something uses it:

echo 'cargo:ripgrep' > ~/.config/shall/modules/tools.txt
echo 'use tools'    >> ~/.config/shall/profiles/Main
shall check                # every question at once; `shall check drift` for one
shall --dry-run sync       # preview
shall sync

shall check is the fastest way to confirm a file is actually being read: it reports how many lines resolved. If you edited a module and check still says 0 present, no active profile is using it.

Your first hour in order

  1. Read Start and run shall init in a test or disposable profile.
  2. Read docs/start-here.md for the safety model and the difference between checking and changing a machine.
  3. Try shall check and shall --dry-run sync before allowing changes.
  4. Read CONTRIBUTING.md only if you are changing the project; you do not need Rust to report a bug or improve documentation.
  5. If you do want to build it, install Rust through rustup or use the Nix development shell, then run the contributor gate exactly as documented.

The files

They live under $SHALL_CONFIG_DIR (default ~/.config/shall). shall init creates the ones every machine needs; the rest appear when you first use the feature they belong to, and are marked below. This directory is meant to be a git repo — shall git init turns on version control, after which every sync commits, and shall rollback <commit> puts the machine back.

shall path prints where they are, so you never have to remember. To keep them somewhere else — a dotfiles repo, a shared drive — shall path --set ~/dotfiles/shall records it once and every later run finds it. For a single run, --config-dir wins over everything; the full order is --config-dir, then $SHALL_CONFIG_DIR, then the stored path, then the default, and shall path --explain tells you which one answered.

modules/       your lists of packages       lowercase names, *.txt
profiles/      named sets you turn on and off       Capitalized names
active         which profiles are on right now
priority       which package managers this machine uses, in order
groups         named backend chains, so `tools:rg` means `apt,cargo:rg` (optional)
vars           your own names for conditions, so `when` can ask about them
schedules      when Shall runs itself (written by `shall schedule`)
locks/         what everything resolved to, one file per backend
adapters/      what you have taught Shall — see below (optional)
preferences.toml   refusals and behaviour (written by `shall config init`)

Working versions of all of these are in examples/ — a module of packages, a module of the things that are not packages, a profile, and a fully commented preferences.toml. They are not illustrations: the test suite parses every one of them with the same grammar and the same Config type the program uses, so an example that stopped being true would fail the build rather than mislead you.

Shall's own bookkeeping — what it currently owns, snapshot metadata — lives in $SHALL_DATA_DIR, never in the config repo and never in git.

Facts about the machine are detected, not configured: core count, whether btrfs/ZFS/Timeshift exists, which managers are installed. The one exception is max_parallel, which you may set by hand to cap concurrency below the core count.

The grammar

A file is lines. A line is blank, a comment, a statement, or a block. An unrecognised line is an error naming the file, the line, and what was expected — never a silently ignored typo.

# a comment
apt:curl                  # explicit backend
ripgrep                   # bare name: resolved via `priority`, then locked
apt:re:^python3-.*        # regex against that backend's names
absent:snap:firefox       # must NOT be installed
nixos:ripgrep             # NixOS only: into the system configuration, not a profile
repo:apt:ppa:foo/bar      # a repository
shim:node                 # a PATH stand-in
service:nginx             # a service
link:./dotfiles/vimrc     # a managed file
dir:~/projects            # a directory, created idempotently
invariant:seforim @path=~/Documents/seforim,backed-by=restic:b2:seforim,max-age=7d
                          # a promise: `check durability` asks the backup tool
use editors               # pull in another module

Acting for another account

A line can name the account it acts for, as @user=, or a block can scope a group of them. The block covers exactly six statements — link:, dir:, shim:, setting:, service:, schedule: — and anything else inside it is an error on that line; a @user= on a line inside the block wins over the block's.

use user:alice {
  link:./dotfiles/gitconfig@target=~/.gitconfig   # the file comes from the repo,
  dir:~/.local/share/alice                        # the destination is alice's home
  shim:rg@source=cargo:ripgrep                    # shims land in her ~/.local/bin
  setting:org.gnome.desktop.interface/theme@value=dark
  schedule:nightly@cron=0 2 * * *,run=sync        # her user units, not the machine's
}

link:./dotfiles/vimrc@target=~/.vimrc,user=alice  # or one line at a time

~ in a destination is that account's home, and a @template=true source renders {{ USER }} and {{ HOME }} as that account. A link: source is still read from your repo — only the destination moves. @owner= sets the owner on its own; where a line names only @user=, that account owns what the line placed, including any parent directory Shall has to create on the way.

Two things are refused rather than approximated, both naming what is missing: a platform with no per-user domain for that kind (service: on OpenRC, SysV or sc; a schedule: for a named account on Windows, where schtasks needs that account's password), and a permission bit the platform has no word for (dir: @mode on Windows — ownership works there). These are refusals at run time, not parse errors, so one shared Linux manifest still parses on macOS and Windows; it simply reports what it could not do.

dir: is idempotent and converges: run it twice and the second run reports nothing, change @mode= and the next run applies it. Undeclaring a directory Shall created removes it (only if it is empty — one you have started using is left alone and reported); a directory that was already there is never removed, and locks/extras.toml records which of the two it was.

Commands

Every command shown here is checked by the test suite against the commands the binary actually ships, so a line that no longer works fails the build rather than misleading you.

Everyday

sync Install, remove and update until the machine matches your files
check Read-only: drift, unmanaged software, backend health — what needs you
apply / apply --delete Write the line and apply exactly it; --delete takes it out and undoes it
list / search / info What is installed, what exists, what a package is
update / upgrade Refresh metadata; upgrade managed packages
hold / unhold Stop a package from being upgraded
rebuild Remove and reinstall what is declared, to repair what sync cannot see
execute Run a plan file plan froze, applying exactly the captured changes

Understanding the machine

why Why a package is installed: where it is declared and what depends on it
check config Parse everything the active profiles reach; report errors, change nothing
check unmanaged What shall adopt would take: installed, you chose it, nothing declares it
check absent Every absent: rule in force, and which module it comes from
check conflicts The same tool pinned to different versions by different backends
check durability Is there still a copy of what your invariant: lines promise, and is it younger than they allow
check health Per-backend readiness. It only reports — shall heal is what repairs
path Print your config repo directory, so cd $(shall path) works. --explain says what decided it; --set DIR stores it
edit Open the repo, or one file in it, in $VISUAL/$EDITOR

Cleaning up

adopt Write the packages you installed by hand — and the config files you already link out of a git repository — into a module
add Vendor someone else's modules into your repo from github:owner/repo, a git/file URL, or a path. Their code arrives unapproved until shall lock
unmanage Stop managing a package without uninstalling it
remove-orphans Remove what each manager considers orphaned — shows the list and asks first
clean-cache Delete downloaded archives and caches; removes no installed package
purge-undeclared Delete every installed package nothing declares — a wider set than unmanaged, because it includes the dependency closure. Shows the whole list first

Plan, lock, reproduce

plan / apply Freeze what sync would do to a file, review it, then apply exactly that
eval Print the resolved config as versioned JSON — every when decided, every bare name given a backend. Takes no locks
try Rehearse this config on a clean machine in a container. Answers what plan cannot: would it work somewhere that is not here?
lock / unlock Freeze what a sync would otherwise decide again — nine kinds, from version pins to exec: approvals. Scope it to a kind, a sub-category (versions:apt), or one name. Recorded versions are replayed by every sync, not only sync --locked — see below
export Emit native manifests (Brewfile, requirements.txt, package.json, Aptfile); or a standalone script (--format bash) from the declarations (--from-declaration) or from what is installed (--from-scan); @export=no opts a line out and --best-effort writes a marked lossy copy
bundle An offline/air-gapped bundle of config, lockfile and resolved package list
sbom / check security CycloneDX bill of materials; scan managed packages against OSV.dev

Running things

shell An ephemeral shell with specific packages loaded, cleaned up on exit
run One command in a throwaway environment
watch Reconcile continuously (GitOps for one machine); unattended, applies without prompting
schedule Native scheduled tasks (systemd, launchd, Task Scheduler)
fleet Compare machines over SSH against your manifests and report drift

export never silently overwrites: if package.json already exists, the export is written beside it as package.shall.json and says so. --force overwrites deliberately.

What has been driven, and what has only been argv-checked

Shall ships 64 backends. That counts the managers it drives by building a command line; nixos: is a further one that works differently, by writing the system configuration instead. Either way the number is what Shall knows how to drive, not a claim that every one has been driven — so here is the difference, taken from the harnesses' own tables rather than from anybody's memory.

Most of them get a real install → list → binary-on-PATH → remove round trip, on every nightly, against the actual manager: apt, dnf, pacman, apk, zypper, xbps and brew on their own container image or runner, and cargo, npm, pnpm, yarn, bun, pip, pipx, uv, gem, go, composer, opam, cabal, conda, mix, nix, spack, luarocks, nimble, helm, krew, pixi, dotnet, pub, mise, scoop, winget, choco, github and web on the images that carry them. btrfs, LVM and ZFS run against real loopback block devices on a privileged image.

How many that is, measured rather than claimed. Every sweep records how many backends completed the full round trip, and scripts/lifecycle-floor.txt ratchets it: a run that does worse than its host class has done before fails. The recorded floors:

host class backends round-tripped
tools image (the broad ecosystem sweep) 28
native Windows runner 13
arch image 12
ubuntu image 10
fedora, void images 9
native macOS runner 8
alpine, opensuse, slackware images 7
guix image 4
storage image (btrfs/LVM/ZFS on loopback) 8

No single host runs them all, because no single host has them all — the Windows managers do not exist on Linux and the reverse. These numbers may rise and never fall, and the table above is checked against that file by the test suite, so it cannot drift the way the sentence it replaced did.

And each sweep also records what each of its sections actually ran, because a section that stops running cannot fail: every check it did not make is a check that did not fail, so the run ends green with a hole in it. This happened — crash/groupkill lost 10 of its 10 checks on one image, and finding those ten took a diff of two CI logs. So every container run prints shall-it-section: <section> <n> per section, and scripts/section-floor.txt ratchets those counts per host class: a section that credits fewer checks than its class has credited before fails, and one that credits more prints the line to add. One section is scored on its union with another. Plan-smoke's scope is whatever the sections above could not drive for real, so its own count falls by one every time a backend is promoted to a real lifecycle — the tally prints it as <n> (+<k> covered above = <n+k>), and the floor compares the sum, which only the registry moves. A shortfall the harness announced is excused, but only by a dated line that names both the count it covers and the soft this run printed — a section that stopped in silence prints no soft and is excused by nothing. These are the container matrix's numbers; the Windows and macOS sweeps print no per-section tally yet, so the floor is in force on neither.

These are argv-tested only — Shall builds the command line and a test asserts it is the right one, and no machine in this project's CI has ever run it:

backend why nothing has driven it
nixos no CI leg runs NixOS. The package round trip has been driven by hand on NixOS 26.05; the services-and-ports module has been evaluated and built into a real system closure there; and CI parses every generated module and merges it into a real NixOS module system. What no gate reaches is activation — that machine cannot activate at all, with or without Shall
flatpak needs a session bus; the container matrix has none
snap snapd is a systemd daemon, and no image here runs systemd
macports never attempted: CI does run on macos-latest, and no step installs MacPorts on it. Work nobody has done, not hardware nobody has
mas needs a signed-in Mac App Store account on real Apple hardware
pkg, pkg_add, pkgin FreeBSD, OpenBSD and pkgsrc — no BSD host exists in this CI
eopkg Solus publishes no container image
emerge smoke-only: gentoo/stage3 ships a binary-package host but no portage tree, so the closing move is a build-time emerge-webrsync nobody has paid for
stack its toolchain can be baked in; the per-package source build cannot, so it is minutes per run for ever
moss AerynOS's native manager. A real image (serpentos/base) exists and ships moss 0.1.0, but moss remove is unimplemented and moss install 404s against the live CDN, so no round trip can complete — argv-tested only

One code path is also unexecuted rather than untested: the dpkg -i / rpm -U local-file handoff. An argv test proves a command line was constructed correctly. It does not prove the manager accepts it.

A backend can be driven and still be unproven, because a harness lifecycle is evidence that the commands are right and the listing bytes a backend row is built from are evidence that its parsing is. spack, krew, asdf and slackpkg are canaried by the matrix and their rows still say UNVERIFIED:, so shall check health marks them unproven with the reason it applies — no harness has run it for the table above, its listing bytes were never captured for these four. Both are one axis: a backend is proven only when a harness has driven it and somebody has pasted what the tool actually printed. The fix is to run the manager; the count of rows still waiting is a ratchet that may only fall.

Storage removal used to be named here and no longer is, because it runs. The storage leg destroys a real object through Shall on every run and asserts it is gone — a btrfs subvolume, an LVM logical volume, and as of 2026-08-18 a ZFS dataset, each on a loopback device.

Teaching Shall a package manager it has never heard of

If a manager's CLI has plain install/remove/list verbs, Shall can learn it from data — no Rust, no release. Write adapters/backends.toml in your repo:

[[backend]]
name   = "firewall"        # the prefix a line is written with
binary = "ufw"             # the program actually run; defaults to `name`
install_args = ["allow"]
remove_args  = ["delete", "allow"]
list_args    = ["status", "numbered"]
[backend.parser]           # how to read `list` output
format = "columns"
name_col = 0

firewall:22/tcp then works everywhere a built-in prefix works. Because name and binary are separate, the prefix does not have to be a package manager's name — it can be any noun that has a CLI behind it. And binary may be an absolute path (/opt/vendor/tool, ~/bin/x), not just a $PATH name — a missing one is a named diagnosis in check health, not a refusal.

A custom backend is a full peer of a built-in — the same optional keys the shipped backends use are available to yours, and an absent key means this backend cannot answer that, never the answer is none.

The nine things you can teach it

Everything above is one of these. A row in one of nine files in your repo teaches Shall something it does not ship, and a thing you teach it is a full peer of a thing it ships — the built-in package managers go through the same table your [[backend]] row goes through.

file row teaches
adapters/backends.toml [[backend]] how to drive a package manager
adapters/settings.toml [[setting_store]] how to read and write a settings store
adapters/init.toml [[init]] how to drive an init system
adapters/firewall.toml [[firewall]] how to drive a firewall
adapters/snapshot.toml [[snapshot]] how to take and restore a filesystem snapshot
adapters/secret.toml [[secret]] how to decrypt a secret
adapters/prereq.toml [[prereq]] the setup a manager needs before it can install
adapters/bootstrap.toml [[bootstrap]] how to obtain a manager this machine lacks
adapters/backup.toml [[backup]] how a backup tool says when it last copied a path

shall adapters says what this machine has on each, and the column that matters is the last one: no rows is the one worth having a command for. A file can be present, approved and perfectly valid TOML and still be doing nothing — write [[backends]] where the reader wants [[backend]] and you have described a table nobody opens, with no parse error, no warning, and a mymgr: line that fails much later with a message about an unknown backend. shall adapters <surface> narrows to one, and --json is the same answer for a script.

Every one of these files runs on your machine, so every one goes through the approval ledger: the first sync after you write or change one refuses it by name and tells you to run shall lock. That is the same rule hooks and exec: scripts follow, and it is why a repo you cloned cannot teach your machine anything you have not read.

export --from-declaration --format bash writes bootstrap.sh: a shebang-and-commands script whose commands are the ones sync would actually run (the same argv builder, read not run). A line the format cannot carry — a link: @decrypt, an exec: script, or for now any resource line — is refused with the file and line named, and nothing is written. @export=no on a line keeps it out of the artifact while sync still applies it; --best-effort writes the script anyway, marks each hole with a # comment, and still exits 2. --from-scan renders the same artifact from what shall adopt discovers on the machine — the machine, never the files — and an empty scan writes nothing.

About

Declare a machine in files — packages, services, settings, firewall rules, dotfiles — and sync it to match, driving the tools already installed

Topics

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages