Skip to main content

Quickstart

Five minutes to a working glixos repo. Assumes you've already installed glix (see Installation) and that you're on a machine where nix flake commands work.

1. Initialise the repo​

glix init \
  --host laptop \
  --user alice \
  --system x86_64-linux

This creates $XDG_CONFIG_HOME/glixos (or ~/.config/glixos), populates it with flake.nix, hosts/laptop/{default.nix,glix.toml}, runs git init, and makes the first commit:

initialized glixos user-packages repo at /home/alice/.config/glixos
  host:   laptop
  user:   alice
  system: x86_64-linux
  core:   github:donnismoore/glixos

Flags:

FlagDefaultMeaning
--host$(hostname)hosts/<name>/ directory to create
--user$USERPrimary user for home-scope packages
--systemx86_64-linuxNix system tuple for this host
--dir$XDG_CONFIG_HOME/glixosRepo root
--coregithub:donnismoore/glixosFlake URL for the glixos repo

2. Add a package​

cd ~/.config/glixos
glix add github:donnismoore/glixos?dir=examples/pkg-hello

What just happened:

  1. The ref was used verbatim (it's a URI).
  2. The package was added to hosts/laptop/glix.toml and to the glix-managed inputs region of flake.nix.
  3. nix flake lock ran to pin the new input.
  4. A git commit was created.
added pkg-hello -> github:donnismoore/glixos?dir=examples/pkg-hello (scope=system) to host laptop
staged. run `glix rebuild` to apply.

By default, packages are staged — they live in the manifest but the system is not rebuilt yet.

Want to apply immediately? Add --apply:

glix add --apply github:donnismoore/glixos?dir=examples/pkg-hello

3. Inspect​

glix list
NAME      SCOPE   STATE    USER  FLAKE
pkg-hello system  enabled        github:donnismoore/glixos?dir=examples/pkg-hello
glix show pkg-hello
name    pkg-hello
flake   github:donnismoore/glixos?dir=examples/pkg-hello
scope   system
state   enabled
host    laptop
glix info
root    /home/alice/.config/glixos
git     clean
head    glix add laptop: pkg-hello (...)
hosts:
  laptop       system=x86_64-linux primary_user=alice packages=1/1 enabled
flake.lock:
  glixos-core          github:donnismoore/glixos
  home-manager         github:nix-community/home-manager @ ...
  nixpkgs              github:NixOS/nixpkgs @ ...
  pkg-hello            github:donnismoore/glixos

4. Rebuild​

sudo glix rebuild switch

This is just a wrapper around nixos-rebuild --flake .#laptop switch. The switch action is the default and can be omitted.

Other actions are forwarded as-is: boot, test, build, dry-build, dry-activate.

5. Recover from a bad rebuild​

If a rebuild fails or activates something you didn't want:

sudo nixos-rebuild --rollback switch    # boot back into the previous generation
glix rollback                           # revert the manifest to match

If nix flake lock itself fails during glix add or glix update, glix already rolled back the manifest before returning the error — no manual intervention needed.

Where next​