# NixBox
A NixOS TUI package manager. Search a nixpkgs channel, pick a package, and NixBox writes it into your home-manager or NixOS config and runs the rebuild — without ever leaving the terminal.
## What it does
- Live search against `nix search --json` over a configurable flake input (default `nixpkgs`).
- Maintains two managed files in your config directory — `nixbox-home-packages.nix` and `nixbox-system-packages.nix` — and owns them end-to-end. Your hand-written config is never touched outside of a single `imports` line.
- On install/uninstall it updates the managed file, makes sure it's imported by your `home.nix` / `configuration.nix`, then runs the appropriate rebuild and streams the output into the TUI.
- Works whether your home-manager is exposed as a standalone `homeConfigurations.<user>` flake output, or wired in as a NixOS module — NixBox auto-detects which one you have and picks the right rebuild command.
- Scans your existing config for externally-declared packages and lets you "migrate" them into the managed file with `m` (or `M` for all of them).
- Settings (channel, target, theme, paths) persist in `~/.config/nixbox/settings.json`.
## How it wires itself in
The first time you install or migrate a package, NixBox does three things automatically:
1. Writes the managed file (`nixbox-home-packages.nix` for home-manager, `nixbox-system-packages.nix` for NixOS).
2. Inserts `./nixbox-home-packages.nix` (or `…-system-…`) into the `imports = [ … ]` list of your `home.nix` / `configuration.nix`. Existing imports-list style is preserved, and the insertion is idempotent.
3. Stages the managed file with `git add -N` if your config dir is a git work tree, so flakes (which ignore untracked files) can actually evaluate it.
If you want to override where NixBox looks for the "main" config file, set `home_manager_main_file` or `nixos_main_file` in `~/.config/nixbox/settings.json`.
Inside the managed file, NixBox owns everything between `# nixbox:packages:start` and `# nixbox:packages:end`. Don't edit those by hand.
## Install
```sh
cargo install nixbox
```
Or build from source:
```sh
devenv shell
cargo build --release
```
## Run
```sh
nixbox # if cargo-installed
devenv shell -- just run # from a checkout
```
## Development
The reproducible development environment is managed by [devenv](https://devenv.sh/):
```sh
devenv shell # Rust toolchain, Nix tooling, and just
just ci # format, lint, and test the workspace
devenv test # evaluate the environment and run just ci
devenv update # update pinned inputs
```
With direnv installed, run `direnv allow` once to activate the environment automatically.
## Layout
Cargo workspace:
- `crates/nixbox` — binary entrypoint
- `crates/nixbox-tui` — ratatui app, search / installed / build views
- `crates/nixbox-nix` — `nix search` wrapper, managed-file writer, import inserter, rebuild runner
- `crates/nixbox-config` — persisted user settings (channel, target, theme, input mode, path overrides)
## Keys
| `/` / `i` / `a` | enter insert mode in a search bar |
| `v` | enter visual mode in a search bar |
| `h` `l` / `b` `w` | move by character / word |
| `0` / `$` | move to start / end |
| `x` / `D` | delete character / to end |
| `d` / `x` / `c` | delete or change a visual selection |
| `↑` `↓` / `k` `j` | move package selection |
| Enter | install selected package |
| `d` / Delete | uninstall selected (Installed tab) |
| `m` / `M` | migrate selected / all external packages |
| `c` | cancel active build (Building tab) |
| Tab | next tab (Search → Installed → Build) |
| Shift-Tab | previous tab |
| Ctrl-S | open settings |
| Esc / Ctrl-C | return to normal mode / quit |