1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
|
# hjem-cli
[smfh]: https://github.com/feel-co/smfh
This is the standalone command-line companion to Hjem, a Nix module system for
managing files in your `$HOME`. It is a small Rust workspace that evaluates Hjem
manifests and applies them atomically via [smfh], and it serves two audiences at
once:
- **Plumbing** for the NixOS, nix-darwin and finix modules, whose activation
services call into the CLI to validate manifests, link files, and poke Systemd
user units when their contents change.
- **Porcelain** for machines that are not NixOS at all: `hjem standalone`
evaluates a `hjem.nix` (or a flake output) and applies it to the current user,
with NixOS-style generations, rollback, and expiry.
The installed binary is a multicall executable: symlinking it as
`hjem-standalone` or `hjem-internal` selects the corresponding subcommand family
from `argv[0]` (`package.nix` sets this up for you).
## Command surface
[top-level README]: https://github.com/feel-co/hjem/blob/main/README.md
```bash
# Standalone commands for using `hjem` on non-NixOS systems
$ hjem standalone <init|switch|build|generations|rollback|
expire-generations|remove-generations>
# Internal activation logic
$ hjem internal <validate-manifest|activate|reload-actions|
update-state|cleanup-state>
# Manifest commands based on smfh's library componenet
$ hjem manifest <validate|diff>
# Activation
$ hjem activate --manifest <path> --state <path>
```
> [!TIP]
> Diagnostics default to `warn`. Use `-v` for activation progress, `-vv` for
> managed paths and linker details, and `-vvv` (or more) for trace diagnostics.
> `--verbosity=error|warn|info|debug|trace` selects a level explicitly.
`standalone switch` and `standalone build` accept exactly one manifest source:
`--manifest` (pre-generated JSON), `--config` (a `hjem.nix` evaluated with
`nix eval`), or `--flake` (defaulting to `hjemConfigurations."$USER"`). State
lives in `$XDG_STATE_HOME/hjem/standalone`, or `~/.local/state/hjem/standalone`
when unset; `--state-dir` overrides it.
The `internal` commands are the module-facing plumbing and are generally not run
by hand, however, `manifest validate` and `manifest diff` might come handy when
authoring manifests directly. An alternative file linker can be plugged in with
`--external-linker` / `--linker-arg` on the activation commands.
See the [top-level README] for full usage examples and the manifest format.
## Development
`hjem-cli` is built with Rust (obviously) targeting Rust 1.95.0 (for the time
being) and a formatter from nightly edition of Rust to get access to more
formatter rules, and Taplo for TOML formatting. We do not vendor a
`rust-toolchain.toml`; please use the Nix devshell provided by the flake to
acquire a pure and reproducible development environment.
### Building
With Nix, from the repository root:
```sh
# Building with Nix
$ nix build .#hjem # or: nix-build -A packages.hjem
```
With Cargo, from this directory:
```sh
# Building with Cargo
$ cargo build --release # binary at target/release/hjem
$ cargo nextest run
```
## License
[LICENSE]: https://github.com/feel-co/hjem/blob/main/LICENSE
`hjem-cli` is licensed under Mozilla Public License (MPL) version 2.0, same as
Hjem. See [LICENSE].
|
