# nami and namiOS > nami is a declarative package manager for any Linux distribution: apps, dotfiles, shell and > project tools come from short YAML files, from nixpkgs' 140,000+ packages and binary cache, > with no Nix to install. namiOS is a declarative Linux distribution built on nami: a whole > computer, its people and its desktop, from one file. Every change can be undone. Site: https://namios.dev. (nami was called tray, and namiOS trayOS; `tray` and `*.tray` files still work until nami 1.0.) ## The files Three files with the same keys; the file decides whose setup it is. Plain YAML. - `~/user.nami`: one person's apps, dotfiles, environment, shell and desktop settings (`namios:` on namiOS). `nami apply` makes the profile match it. - `/etc/nami/computer.nami`: the computer's apps for everyone, services, `/etc` files; on namiOS also users, hardware, boot. Admins change it. - `project.nami`: a project's tools, `tasks:` and `services:`, for everyone who clones it. nami uses the nearest one at or above the current folder, as git finds `.git`. - `nami.lock`: pinned versions, next to the file. Commit it. ```yaml packages: - ripgrep - nodejs: 22 # a version - git: ~/.gitconfig: { user: { name: Ada, email: ada@example.org } } env: EDITOR: nvim tasks: # project.nami test: npm test ``` Every key, with examples: `nami options` (`--json`), or JSON Schemas for editors at https://namios.dev/schema/user.json (also computer, project, package, service). ## Key commands - `nami install ` / `nami remove `: change your apps and the file together (`--for-everyone`: the computer's). - `nami apply [file]`: make the computer or profile match the file (`--dry-run --json` says what would change). - `nami search --json`, `nami info --json`: find packages (`attr` is the name to use). - `nami list --json`, `nami status --json`, `nami history --json`, `nami diff --json`: what's installed, who you are to nami, each change, what changed. - `nami undo [change]`: go back. - `nami check --json`: problems in a nami file, by line, without applying it. - `nami config set|add|remove|get [value] [--file f]`: edit a file in place, comments kept. - `nami new --from `: a project (node, python, rust, go, c, empty; writes `project.nami` and an `AGENTS.md`), a service, or a namiOS computer (`--from namios`). - `nami shell`, `nami run `, `nami run -- `, `nami env`: use a project's tools. - `nami up -d`, `nami down`, `nami logs`: a project's services. - `nami doctor --json`, `nami upgrade --dry-run --json`, `nami backup status --json`, `nami sync status --json`. - `nami desktop ...` (namiOS): Control Center from the command line: `status`, `volume 40`, `mute`, `output`, `brightness 70`, `wifi on|off|list|connect`, `bluetooth on|off|list`, `dnd on --for 1h`, `look dark`, `night on`, `wallpaper `, `settings `, `screenshot `, `windows`, `focus `, `close `, `notify `, `lock`. All take `--json`; `nami desktop status --json` is the whole state. ## For scripts and agents - `--json` on any command that prints something to read. Commands that only change things print `{"ok": true}` when done. - A failed command with `--json` prints `{"error": {"code": "...", "message": "...", "hint": "..."}}` on stdout. Codes: `invalid_args`, `not_found`, `invalid_file`, `needs_admin`, `needs_input`, `network`, `conflict`, `denied`, `not_running`, `unsupported`, `failed`. - Exit codes: 0 ok, 1 failed, 2 command line, 75 network (try again later), 77 needs an admin. - `NAMI_NONINTERACTIVE=1`: nothing waits on a question or a password box; what would ask fails with `needs_input` and names the flag to pass (`--yes`, `--password-stdin`). - Prefer editing the nami file (or `nami config ...`) and `nami apply` over installing with other tools: the file is the truth. ## Docs - [Install nami](https://namios.dev/docs/nami/install) - [user.nami](https://namios.dev/docs/nami/user-nami) - [Projects](https://namios.dev/docs/nami/projects) - [Changes and undo](https://namios.dev/docs/nami/changes) - [Scripts and agents](https://namios.dev/docs/nami/scripts-and-agents): JSON, error codes, `nami desktop` - [computer.nami](https://namios.dev/docs/namios/computer-nami) - [The namiOS desktop](https://namios.dev/docs/namios/desktop) - [Commands](https://namios.dev/docs/reference/commands): every command's `--help` - [Options](https://namios.dev/docs/reference/options): every key in the files - [Examples](https://namios.dev/docs/reference/examples): starters, services, packages