Most of the time you change a file and run nami apply; the window does the same with clicks. The rest are here. Admins' commands that change the computer run as root through nami's daemon, without sudo.
Get started
Install apps
They go into your user.nami, for you alone: apps from nami's catalog by name, from Flathub as flathub:<app id>, a recipe folder (./path), or a download (.deb, .rpm, AppImage).
What sets up the computer (a service, files in /etc, drivers: docker, steam, tailscale) is installed for everyone on it, in computer.nami, by an administrator.
Usage: nami install [OPTIONS] [PACKAGES]...
Arguments:
[PACKAGES]...
Apps: names from the catalog, flathub:<app id>, ./recipe folders or downloads (.deb, .rpm, AppImage)
Options:
--for-everyone
For everyone on this computer, in computer.nami (administrators)
[alias: --everyone]
--json
Print JSON: {"ok": true} once it's done; an error as {"error": {"code", "message", "hint"}}
--color <WHEN>
When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set)
[default: auto]
-h, --help
Print help (see a summary with '-h')
Examples:
# Install two apps for yourself
$ nami install firefox gimp
# For everyone on this computer (administrators)
$ nami install --for-everyone docker
# An app from Flathub, or a download
$ nami install flathub:org.gimp.GIMP ./app.deb
Remove apps
Each comes off from wherever it's installed: your user.nami, or the computer's computer.nami (administrators).
Usage: nami remove [OPTIONS] [PACKAGES]...
Arguments:
[PACKAGES]...
The apps, by the names they were installed with
Options:
--for-everyone
From the computer's apps (computer.nami), not yours (administrators)
[alias: --everyone]
--json
Print JSON: {"ok": true} once it's done; an error as {"error": {"code", "message", "hint"}}
--color <WHEN>
When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set)
[default: auto]
-h, --help
Print help (see a summary with '-h')
Examples:
# Remove an app
$ nami remove gimp
Find apps and packages
Apps come first; --all includes tools and libraries too. With no search term, the most used apps.
Usage: nami search [OPTIONS] [TERM]
Arguments:
[TERM]
What to look for; left out, the most used apps
[default: ""]
Options:
--all
Tools and libraries too, not only apps
--category <CATEGORY>
Only one kind of app: office, graphics, audio-video, games, internet, coding, learning, tools
--json
Print JSON
--flathub
Flathub's apps too, after the catalog's (`flathub:<app id>`; those the catalog has are left out)
--color <WHEN>
When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set)
[default: auto]
-h, --help
Print help (see a summary with '-h')
Examples:
# Find apps for photos
$ nami search photo
# Tools and libraries too
$ nami search --all ripgrep
# The most used games
$ nami search --category games
Show details about packages
What it is, whether you have it, and how many versions there are; --all shows all of its description and its screenshots; --screenshots downloads them. `nami versions` lists the versions.
Usage: nami info [OPTIONS] [PACKAGES]...
Arguments:
[PACKAGES]...
Names, or a version of one: firefox@150
Options:
--json
Print JSON
--all
All of the description, and the screenshots
--versions
Every version there is of each, as `nami versions` lists them
--screenshots
Download the apps' screenshots (kept in ~/.cache/nami/screenshots): their files instead of URLs
--color <WHEN>
When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set)
[default: auto]
-h, --help
Print help (see a summary with '-h')
Examples:
# What firefox is, and whether you have it
$ nami info firefox
# All of its description, and its screenshots
$ nami info firefox --all
List the versions of a package
Every version the catalog has had, by major version (or minor, like python3's 3.12 and 3.13), newest first, with when each was current. Pick one with `nami install firefox@159`, or `firefox: 159` in a nami file's packages.
Usage: nami versions [OPTIONS] <PACKAGES>...
Arguments:
<PACKAGES>...
Package names: firefox
Options:
--all
Every release, not only the newest of each version
--json
Print JSON: {"<name>": [{"version", "date", "nixpkgs"}]}, newest first
--color <WHEN>
When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set)
[default: auto]
-h, --help
Print help (see a summary with '-h')
Examples:
# Every version of firefox, newest first
$ nami versions firefox
# Every release, not only each version's newest
$ nami versions python3 --all
# Is there a firefox 150?
$ nami search firefox@150
# Install it
$ nami install firefox@150
List what's installed
Usage: nami list [OPTIONS]
Options:
--json Print JSON
--color <WHEN> When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set) [default: auto]
-h, --help Print help
Update your apps to their newest versions
Move installed packages to the versions in the current index (and your Flathub apps to Flathub's newest)
Usage: nami upgrade [OPTIONS]
Options:
--dry-run
Only show what would be updated
--json
Print JSON
--flathub
Only your apps from Flathub (what the daily timer runs)
--mine
Only your own apps, not the computer's (Updates runs it after os-update)
--color <WHEN>
When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set)
[default: auto]
-h, --help
Print help (see a summary with '-h')
Examples:
# See what would be updated
$ nami upgrade --dry-run
# Update everything
$ nami upgrade
Get the newest app catalog
Download a package index (URL or file, .json or .json.xz); with --refresh, fetch it again from where root last got it (any user)
Usage: nami update [OPTIONS]
Options:
--from <FROM>
--refresh
--trust <TRUST>
Trust this catalog signing key (name:base64, from `nami keygen`)
--unsigned
Accept a catalog without a signature (one you built yourself)
--icons <ICONS>
Where the app icons (icons.tar) are: a URL or file. Default: next to --from
--drvs <DRVS>
Where build definitions live (dir or URL), for `extends:` recipes
--json
Print JSON: {"ok": true} once it's done; an error as {"error": {"code", "message", "hint"}}
--color <WHEN>
When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set)
[default: auto]
-h, --help
Print help (see a summary with '-h')
Your setup
Make this computer match its nami file
Make the computer (or your profile) match a nami file: computer.nami for admins, your ~/user.nami for others, or the one named
Default: /etc/nami/computer.nami for admins, ~/user.nami for others; never a file in the current folder by itself. Any other file by its path (`nami apply ./user.nami` in a dotfiles repo); a project's project.nami is for `nami shell` and `nami run`. Keeps the versions in nami.lock; only new packages are resolved.
Or a config repo (github:owner/repo[@branch], or any git URL[@branch]): set this computer up from it in one step. It's cloned into ~/.config/nami (what was there is moved aside) and its nami file applied; the computer.nami in this computer's folder (named after it), if any, becomes the computer's file (admins). Run it again to pull and apply what changed.
Usage: nami apply [OPTIONS] [FILE]
Arguments:
[FILE]
A nami file, or a config repo to set up from
Options:
--locked
Install exactly what nami.lock says, or fail
--upgrade
Re-resolve everything from the current catalog and update nami.lock
--dry-run
Show what would change (packages, services, /etc files) without switching anything; what's needed is still downloaded
--password-stdin
Passwords for people new on the computer (or a new one for someone), from stdin: a login:password line each, as chpasswd reads them
--json
Print JSON: with --dry-run, what would change; else {"ok": true} once it's done
--color <WHEN>
When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set)
[default: auto]
-h, --help
Print help (see a summary with '-h')
Examples:
# Apply your nami file
$ nami apply
# See what would change first
$ nami apply --dry-run
# Set this computer up from your config repo
$ nami apply github:ada/nami-config
Find problems in a nami file
Find problems in a nami file without applying it (`-` reads stdin); a config repo's folder: all of it (each computer's two files)
Usage: nami check [OPTIONS] [FILE]
Arguments:
[FILE]
The nami file, or a config repo's folder (default: the project you're in, else the computer's)
Options:
--base <BASE>
Where relative paths are relative to (default: the file's directory)
--json
Print the problems as JSON
--color <WHEN>
When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set)
[default: auto]
-h, --help
Print help (see a summary with '-h')
Examples:
# Check a file before applying it
$ nami check ./user.nami
Change a nami file, keeping its comments
Change a nami file in place, keeping its comments (e.g. `nami config set env.EDITOR nvim`, `nami config add packages tree`)
Usage: nami config [OPTIONS] <COMMAND>
Commands:
set Set a value (YAML: 10, true, "text", [a, b])
unset Remove a key
add Add to a list
remove Remove from a list
json Apply an edit given as JSON ({"set": {"path": [...], "value": ...}} and so on; `{"!secret": "..."}` is a secret, to `nami secret seal`); `-` reads it from stdin. For tools
write Replace the whole file with what's on stdin, as it is (for tools: an editor's save)
unlock Ask for an admin's password now, for the computer's file: the changes of the next few minutes don't ask again (for tools)
get Print what the file says at a path (all of it without one): its own lines, not what it lists
path Print which nami file nami uses: computer.nami for admins, else your ~/user.nami
help Print this message or the help of the given subcommand(s)
Options:
--file <FILE>
The file (default: computer.nami for admins, your ~/user.nami for others; a person's keys always yours); `-`: stdin (an edit prints the changed file)
--color <WHEN>
When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set)
[default: auto]
-h, --help
Print help (see a summary with '-h')
Examples:
# Set a value
$ nami config set env.EDITOR nvim
# Add to a list
$ nami config add packages tree
Set a value (YAML: 10, true, "text", [a, b])
Usage: nami config set [OPTIONS] <PATH> <VALUE>
Arguments:
<PATH>
<VALUE>
Options:
--file <FILE> The file (default: computer.nami for admins, your ~/user.nami for others; a person's keys always yours); `-`: stdin (an edit prints the changed file)
--color <WHEN> When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set) [default: auto]
-h, --help Print help
Remove a key
Usage: nami config unset [OPTIONS] <PATH>
Arguments:
<PATH>
Options:
--file <FILE> The file (default: computer.nami for admins, your ~/user.nami for others; a person's keys always yours); `-`: stdin (an edit prints the changed file)
--color <WHEN> When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set) [default: auto]
-h, --help Print help
Add to a list
Usage: nami config add [OPTIONS] <PATH> <VALUE>
Arguments:
<PATH>
<VALUE>
Options:
--file <FILE> The file (default: computer.nami for admins, your ~/user.nami for others; a person's keys always yours); `-`: stdin (an edit prints the changed file)
--color <WHEN> When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set) [default: auto]
-h, --help Print help
Remove from a list
Usage: nami config remove [OPTIONS] <PATH> <VALUE>
Arguments:
<PATH>
<VALUE>
Options:
--file <FILE> The file (default: computer.nami for admins, your ~/user.nami for others; a person's keys always yours); `-`: stdin (an edit prints the changed file)
--color <WHEN> When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set) [default: auto]
-h, --help Print help
Apply an edit given as JSON ({"set": {"path": [...], "value": ...}} and so on; {"!secret": "..."} is a secret, to nami secret seal); - reads it from stdin. For tools
Usage: nami config json [OPTIONS] <OP>
Arguments:
<OP>
Options:
--file <FILE> The file (default: computer.nami for admins, your ~/user.nami for others; a person's keys always yours); `-`: stdin (an edit prints the changed file)
--color <WHEN> When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set) [default: auto]
-h, --help Print help
Replace the whole file with what's on stdin, as it is (for tools: an editor's save)
Usage: nami config write [OPTIONS]
Options:
--file <FILE> The file (default: computer.nami for admins, your ~/user.nami for others; a person's keys always yours); `-`: stdin (an edit prints the changed file)
--color <WHEN> When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set) [default: auto]
-h, --help Print help
Ask for an admin's password now, for the computer's file: the changes of the next few minutes don't ask again (for tools)
Usage: nami config unlock [OPTIONS] [ABOUT]
Arguments:
[ABOUT] What's changing, in a few plain words, for the box that asks
Options:
--file <FILE> The file (default: computer.nami for admins, your ~/user.nami for others; a person's keys always yours); `-`: stdin (an edit prints the changed file)
--color <WHEN> When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set) [default: auto]
-h, --help Print help
Print what the file says at a path (all of it without one): its own lines, not what it lists
Usage: nami config get [OPTIONS] [PATH]
Arguments:
[PATH]
Options:
--json As JSON (nothing there: null), for tools
--text The whole file as it's written, comments and all (no path)
--file <FILE> The file (default: computer.nami for admins, your ~/user.nami for others; a person's keys always yours); `-`: stdin (an edit prints the changed file)
--color <WHEN> When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set) [default: auto]
-h, --help Print help
Print which nami file nami uses: computer.nami for admins, else your ~/user.nami
Usage: nami config path [OPTIONS]
Options:
--personal Your own (home settings) instead
--file <FILE> The file (default: computer.nami for admins, your ~/user.nami for others; a person's keys always yours); `-`: stdin (an edit prints the changed file)
--color <WHEN> When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set) [default: auto]
-h, --help Print help
Show the whole computer as one file
The whole computer in one file: the system file merged with all it includes, each line saying which file it came from
`--flat` prints it as YAML, each value's line ending in `# <file>` (computer.nami, ../packages/niri/package.nami, a repo's layer at its commit). Secrets stay sealed. A computer nami makes has it in /etc/nami/computer.flat.nami.
Usage: nami show [OPTIONS] [FILE]
Arguments:
[FILE]
The system file, or a computer's folder, or a config repo's (its only computer) (default: /etc/nami/computer.nami)
Options:
--flat
--json
Print it as JSON (without the comments saying where each value came from)
--color <WHEN>
When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set)
[default: auto]
-h, --help
Print help (see a summary with '-h')
List every option a nami file can have
Every nami file option, with examples
Usage: nami options [OPTIONS]
Options:
--json
Print them as JSON
--schema <FILE>
A JSON Schema of one kind of file, for editors: computer, user, package, project or checks
--color <WHEN>
When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set)
[default: auto]
-h, --help
Print help (see a summary with '-h')
Seal secrets in nami files, and open them
Secrets in nami files (`key: !secret ...`): seal, edit, show, and who can open them
Usage: nami secret [OPTIONS] <COMMAND>
Commands:
seal Encrypt each `!secret` still written plain, in place (no files: the repo's nami files)
edit Edit a nami file in $EDITOR with its secrets opened; they're sealed again after
show Print one secret, like `env.STRIPE_KEY` (for scripts); without a key, list them
allow Let someone (or a computer) open the repo's secrets: add their public key to .nami-recipients and seal everything again; --remove takes them out
key Your public key, for someone to `nami secret allow` (made if you have none)
hook Install a git pre-commit hook that refuses secrets that aren't sealed
check List secrets that aren't sealed (and fail if there are); --staged: in what git is about to commit
help Print this message or the help of the given subcommand(s)
Options:
--color <WHEN>
When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set)
[default: auto]
-h, --help
Print help (see a summary with '-h')
Encrypt each !secret still written plain, in place (no files: the repo's nami files)
Usage: nami secret seal [OPTIONS] [FILES]...
Arguments:
[FILES]...
Options:
--color <WHEN> When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set) [default: auto]
-h, --help Print help
Edit a nami file in $EDITOR with its secrets opened; they're sealed again after
Usage: nami secret edit [OPTIONS] <FILE>
Arguments:
<FILE>
Options:
--color <WHEN> When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set) [default: auto]
-h, --help Print help
Print one secret, like env.STRIPE_KEY (for scripts); without a key, list them
Usage: nami secret show [OPTIONS] <FILE> [KEY]
Arguments:
<FILE>
[KEY]
Options:
--color <WHEN> When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set) [default: auto]
-h, --help Print help
Let someone (or a computer) open the repo's secrets: add their public key to .nami-recipients and seal everything again; --remove takes them out
Usage: nami secret allow [OPTIONS] <NAME> [KEY]
Arguments:
<NAME>
[KEY] An age key (age1...), an SSH public key, or a .pub file
Options:
--remove
--color <WHEN> When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set) [default: auto]
-h, --help Print help
Your public key, for someone to nami secret allow (made if you have none)
Usage: nami secret key [OPTIONS]
Options:
--color <WHEN> When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set) [default: auto]
-h, --help Print help
Install a git pre-commit hook that refuses secrets that aren't sealed
Usage: nami secret hook [OPTIONS]
Options:
--color <WHEN> When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set) [default: auto]
-h, --help Print help
List secrets that aren't sealed (and fail if there are); --staged: in what git is about to commit
Usage: nami secret check [OPTIONS] [FILES]...
Arguments:
[FILES]...
Options:
--staged
--color <WHEN> When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set) [default: auto]
-h, --help Print help
Keep or undo what apps changed in their settings
Settings files apps may edit (mutable: true): what they changed, and keeping or undoing it
Usage: nami home [OPTIONS] <COMMAND>
Commands:
diff What apps changed in their settings files, setting by setting
keep Write what apps changed into your nami file (all files, or the ones named), then apply
undo Put the spec's version back, throwing away what the app changed
adopt Start managing an app's settings file: its current settings go into nami file (as an editable file), then apply
help Print this message or the help of the given subcommand(s)
Options:
--config <CONFIG>
The nami file to write kept changes into
--color <WHEN>
When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set)
[default: auto]
-h, --help
Print help (see a summary with '-h')
What apps changed in their settings files, setting by setting
Usage: nami home diff [OPTIONS]
Options:
--json
--config <CONFIG> The nami file to write kept changes into
--color <WHEN> When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set) [default: auto]
-h, --help Print help
Write what apps changed into your nami file (all files, or the ones named), then apply
Usage: nami home keep [OPTIONS] [FILES]...
Arguments:
[FILES]...
Options:
--config <CONFIG> The nami file to write kept changes into
--color <WHEN> When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set) [default: auto]
-h, --help Print help
Put the spec's version back, throwing away what the app changed
Usage: nami home undo [OPTIONS] [FILES]...
Arguments:
[FILES]...
Options:
--config <CONFIG> The nami file to write kept changes into
--color <WHEN> When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set) [default: auto]
-h, --help Print help
Start managing an app's settings file: its current settings go into nami file (as an editable file), then apply
Usage: nami home adopt [OPTIONS] [FILES]...
Arguments:
[FILES]...
Options:
--config <CONFIG> The nami file to write kept changes into
--color <WHEN> When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set) [default: auto]
-h, --help Print help
Pin and update layers from git repos
The layers a nami file includes from git repos (github:owner/repo/layer, git+<url>#layer), each at the commit nami.lock pins it to
New ones are pinned (and said); --update moves each to the newest commit of its branch or tag. Nothing else moves a pin: not the computer's automatic updates (a project's: `nami shell --upgrade` too).
Usage: nami layers [OPTIONS] [FILE]
Arguments:
[FILE]
The nami file, or a project's folder (default: the project you're in; else computer.nami for admins, your ~/user.nami for others)
Options:
--update
Move the pins to the newest commits, and say what moved
--json
Print JSON: {"file", "lock", "layers": [{"include", "rev", "url"}]}
--color <WHEN>
When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set)
[default: auto]
-h, --help
Print help (see a summary with '-h')
Turn a Nix setup or old computer into nami files
Turn a Nix setup into nami files (a flake's dev shell into the project's project.nami, home-manager into your ~/user.nami, a NixOS configuration into computer.nami), or an old computer into a config repo (`nami import /` on Ubuntu or Debian, or Windows' disk)
Read without Nix (when Nix is installed, `nix eval` fills in what the reader can't). Merges into the target, keeping what's there; what has no nami equivalent is listed, and noted at the end of the file. Applies nothing: run `nami apply` (or `nami shell`) next.
A whole computer (`/`, an old disk mounted somewhere, or Windows' C:) becomes a config repo, ~/nami-config: the apps, Wi-Fi networks (sealed; `sudo` reads them), settings, shell and dotfiles. Your files stay out of it: `--home` says how to move them.
Usage: nami import [OPTIONS] <PATH>
Arguments:
<PATH>
A flake (its directory or flake.nix), shell.nix, a home-manager file (home.nix or a module), a NixOS configuration.nix; or a computer: / (Ubuntu, Debian), or Windows' disk
Options:
--out <OUT>
A computer: the config repo to write (default ~/nami-config); run again, it merges
--user <USER>
A computer: whose settings, when several people use it
--repo <REPO>
A computer: the repo's address once pushed (github:you/nami-config), for your first login
--recipes
A computer: write recipes from Ubuntu's packages for apt apps the catalog doesn't have
--home [<TARGET>]
A computer: how to move your files; with a folder (or host:folder), copy them there
--only <ONLY>
A computer, with --home: only these of your files (`Documents,firefox`; --home --json lists them)
--to <TO>
Which file it goes into (default: by what it is)
[possible values: system, user, project]
--file <FILE>
Write into this nami file instead
--dry-run
Show the result; write nothing
--json
What was found, and the resulting file, as JSON (a computer, with --home: your files, for nami-gui)
--color <WHEN>
When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set)
[default: auto]
-h, --help
Print help (see a summary with '-h')
Changes and backups
Undo the last change
Or go back to a given change: `nami history` lists them.
Usage: nami undo [OPTIONS] [CHANGE]
Arguments:
[CHANGE]
Options:
--json
Print JSON: {"ok": true} once it's done; an error as {"error": {"code", "message", "hint"}}
--mine
Your own profile's (an admin's own apps, and their user.nami), not the computer's
--color <WHEN>
When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set)
[default: auto]
-h, --help
Print help (see a summary with '-h')
Examples:
# Undo the last change
$ nami undo
# Go back to change 12
$ nami undo 12
List past changes, to go back to
Every change, each one you can go back to
Usage: nami history [OPTIONS]
Options:
--json
Print JSON
--mine
Your own profile's (an admin's own apps: Flathub's, and their user.nami's), not the computer's
--color <WHEN>
When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set)
[default: auto]
-h, --help
Print help (see a summary with '-h')
Examples:
# Every change, newest last
$ nami history
Show what changed between two changes
What changed between two changes, in words (`nami diff 12`: from change 12 to now; default: the previous and the current)
Usage: nami diff [OPTIONS] [FROM] [TO]
Arguments:
[FROM]
The change to compare from (default: the one before the current)
[TO]
The change to compare to (default: the current)
Options:
--raw
The files' lines as `diff -u` has them
--json
As JSON (for nami-gui)
--color <WHEN>
When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set)
[default: auto]
-h, --help
Print help (see a summary with '-h')
Examples:
# What changed since change 12
$ nami diff 12
Back up your home, and restore from it
Your home's backups, every hour, to go back to: now, list, restore, status
namiOS backs up each person's home every hour (kept hourly for a day, daily for a month, weekly after), on this computer and onto a drive when one's chosen: `namios: backups:` in your user.nami (Settings → Backups).
Usage: nami backup [OPTIONS] <COMMAND>
Commands:
now Back up your home now (waiting for one under way)
list The backups to go back to, newest first
restore Bring a file or folder back as it was (default: the newest backup that has it)
status How your backups are doing: the last, where to, the space they use, what's left out
versions A file's earlier versions (for Files' Restore an Earlier Version)
help Print this message or the help of the given subcommand(s)
Options:
--color <WHEN>
When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set)
[default: auto]
-h, --help
Print help (see a summary with '-h')
Examples:
# Back up now
$ nami backup now
# List the backups
$ nami backup list
Back up your home now (waiting for one under way)
Usage: nami backup now [OPTIONS]
Options:
--color <WHEN> When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set) [default: auto]
-h, --help Print help
The backups to go back to, newest first
Usage: nami backup list [OPTIONS]
Options:
--json
--place <PLACE> A drive's backups: the folder they're in (default: this computer's)
--color <WHEN> When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set) [default: auto]
-h, --help Print help
Bring a file or folder back as it was (default: the newest backup that has it)
--from: an id from `nami backup list`, a day (2026-11-09: its last backup), a day and time (2026-11-09 10:00), `yesterday`, or a while ago (2h, 3d, 1w). If there's a file there now, both are kept (the one brought back is named for its time) unless --replace (the one there now goes to the Trash).
Usage: nami backup restore [OPTIONS] [PATHS]...
Arguments:
[PATHS]...
Options:
--from <FROM>
--to <TO>
Into this folder instead of where it was
--replace
--place <PLACE>
--json
--color <WHEN>
When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set)
[default: auto]
-h, --help
Print help (see a summary with '-h')
How your backups are doing: the last, where to, the space they use, what's left out
Usage: nami backup status [OPTIONS]
Options:
--json
--color <WHEN> When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set) [default: auto]
-h, --help Print help
A file's earlier versions (for Files' Restore an Earlier Version)
Usage: nami backup versions [OPTIONS] <FILE>
Arguments:
<FILE>
Options:
--json
--place <PLACE>
--color <WHEN> When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set) [default: auto]
-h, --help Print help
Keep your setup the same on all your computers
Your setup on all your computers: on, now, status, undo, off
Your user.nami (apps, shell, settings) kept the same on each computer you turn it on on, Ubuntu with nami or namiOS alike, through a private git repo of yours (GitHub's, signed in to in your browser, or any git server's). What changes on one reaches the others within 15 minutes; where both changed one thing, the later change wins and the other is in `nami sync status`, to undo. A computer's own displays, graphics card, backup drive and sound stay its own.
Usage: nami sync [OPTIONS] <COMMAND>
Commands:
on Turn it on: your user.nami kept in a private git repo of yours, and the same on each computer you turn it on on. No repo: your GitHub account's nami-setup (made private, signed in to in your browser, if need be)
now Sync now: what changed here goes to the repo, what changed on your other computers comes here (and is applied)
status Whether it's on, the last sync, your computers, and what came in
undo Undo what one sync changed here (`nami sync status` numbers them); the undoing is synced too
sign-in Sign in to GitHub in your browser (through GitHub's own tool, gh)
off Turn it off on this computer (the repo, your file and your other computers stay as they are)
help Print this message or the help of the given subcommand(s)
Options:
--color <WHEN>
When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set)
[default: auto]
-h, --help
Print help (see a summary with '-h')
Examples:
# Turn it on for this computer
$ nami sync on
# See what's synced
$ nami sync status
Turn it on: your user.nami kept in a private git repo of yours, and the same on each computer you turn it on on. No repo: your GitHub account's nami-setup (made private, signed in to in your browser, if need be)
Usage: nami sync on [OPTIONS] [REPO]
Arguments:
[REPO] github:you/repo, a git URL (https://..., git@host:path), or a folder
Options:
--json Each step as a JSON line (for Settings)
--color <WHEN> When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set) [default: auto]
-h, --help Print help
Sync now: what changed here goes to the repo, what changed on your other computers comes here (and is applied)
Usage: nami sync now [OPTIONS]
Options:
--quiet Say nothing unless something went wrong (the timer)
--settle <SETTLE> Wait this many seconds first, for a file still being written to settle [default: 0]
--json
--color <WHEN> When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set) [default: auto]
-h, --help Print help
Whether it's on, the last sync, your computers, and what came in
Usage: nami sync status [OPTIONS]
Options:
--json
--color <WHEN> When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set) [default: auto]
-h, --help Print help
Undo what one sync changed here (nami sync status numbers them); the undoing is synced too
Usage: nami sync undo [OPTIONS] <ID>
Arguments:
<ID>
Options:
--color <WHEN> When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set) [default: auto]
-h, --help Print help
Sign in to GitHub in your browser (through GitHub's own tool, gh)
Usage: nami sync sign-in [OPTIONS]
Options:
--json
--color <WHEN> When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set) [default: auto]
-h, --help Print help
Turn it off on this computer (the repo, your file and your other computers stay as they are)
Usage: nami sync off [OPTIONS]
Options:
--color <WHEN> When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set) [default: auto]
-h, --help Print help
Projects
Start from an example computer, project or service
Start from one of nami's examples: a computer, a project, or a service (no name: list them)
The example's files become yours: `nami new laptop --from namios` writes laptop/computer.nami and copies namios with every package it lists into ../packages (what's there is kept); `nami new shop --from node` writes shop/project.nami; `nami new shop --from postgres` shop/services/postgres.nami.
Usage: nami new [OPTIONS] [FOLDER]
Arguments:
[FOLDER]
The folder: a computer's (named after it), or a project's (default: here)
Options:
--from <FROM>
The example
--force
Replace a project.nami or service file that's there
--json
The examples as JSON (no --from), for nami-gui
--color <WHEN>
When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set)
[default: auto]
-h, --help
Print help (see a summary with '-h')
Examples:
# List the examples
$ nami new
# A Node project in ./shop
$ nami new shop --from node
Open a shell with a project's tools
A shell with this project's tools (its nami file), like a dev shell
Usage: nami shell [OPTIONS] [PROJECT]
Arguments:
[PROJECT]
A directory, a project's project.nami, or github:owner/repo[/dir][@ref] (default: the nearest project)
Options:
--locked
Fail instead of changing nami.lock
--upgrade
Take the catalog's current versions and rewrite the lock
--color <WHEN>
When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set)
[default: auto]
-h, --help
Print help (see a summary with '-h')
Examples:
# A shell with this project's tools
$ nami shell
# Another project's, from GitHub
$ nami shell github:ada/site
Run a project's task, or a command with its tools
Run a task from the project's project.nami (`nami run test`), or any command (`nami run -- npm test`)
Usage: nami run [OPTIONS] <COMMAND>...
Arguments:
<COMMAND>...
A task's name, or `--` and a command
Options:
--project <PROJECT>
A directory, a project's project.nami, or github:owner/repo[/dir][@ref] (default: the nearest project)
--locked
Fail instead of changing nami.lock
--color <WHEN>
When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set)
[default: auto]
-h, --help
Print help (see a summary with '-h')
Examples:
# Run the project's test task
$ nami run test
# Run any command with the project's tools
$ nami run -- npm test
Run a command without installing it
Run a command once, without installing it: `nami run-once cowsay hi` (`, cowsay hi` in namiOS's shells)
The package that has the command is fetched into the store if it isn't there (anyone may: no admin needed), run, and left for the next `nami gc`; again, it starts at once. Several packages have it: you pick (or --package names one).
Usage: nami run-once [OPTIONS] [COMMAND]...
Arguments:
[COMMAND]...
Options:
-p, --package <PACKAGE>
The package to run it from (default: the one the command's in)
--update-table
Find out again which packages have which commands (weekly by itself)
--color <WHEN>
When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set)
[default: auto]
-h, --help
Print help (see a summary with '-h')
Examples:
# Run cowsay without installing it
$ nami run-once cowsay hi
Start a project's services
Start the project's services (its project.nami's `services:`, or the ones named): in the foreground, their output prefixed with their names, until Ctrl-C stops them
Usage: nami up [OPTIONS] [NAMES]...
Arguments:
[NAMES]...
Only these (default: all of them)
Options:
-d, --detach
In the background: back once they're ready
--project <PROJECT>
A directory or a project's project.nami (default: the nearest project)
--locked
--color <WHEN>
When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set)
[default: auto]
-h, --help
Print help (see a summary with '-h')
Examples:
# Start every service, in the foreground
$ nami up
# Start postgres in the background
$ nami up -d postgres
Stop a project's services
Stop the project's services (or the ones named)
Usage: nami down [OPTIONS] [NAMES]...
Arguments:
[NAMES]...
Only these (default: all of them)
Options:
--project <PROJECT>
A directory or a project's project.nami (default: the nearest project)
--color <WHEN>
When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set)
[default: auto]
-h, --help
Print help (see a summary with '-h')
Follow a project's services' output
Follow the output of the project's services (or one's), until Ctrl-C
Usage: nami logs [OPTIONS] [NAME]
Arguments:
[NAME]
Only this service's
Options:
--project <PROJECT>
A directory or a project's project.nami (default: the nearest project)
--color <WHEN>
When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set)
[default: auto]
-h, --help
Print help (see a summary with '-h')
List a project's tasks and services, or projects
A project's tasks or services, or your projects (`nami new <folder> --from <starter>` starts one)
Usage: nami project [OPTIONS] <COMMAND>
Commands:
tasks The tasks this project defines
services The services this project defines, and which are running (`nami up` starts them)
list Projects on this computer you've used (`--json` for the app)
help Print this message or the help of the given subcommand(s)
Options:
--color <WHEN>
When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set)
[default: auto]
-h, --help
Print help (see a summary with '-h')
The tasks this project defines
Usage: nami project tasks [OPTIONS]
Options:
--json Print JSON: [{"name", "run", "description", "depends"}]
--color <WHEN> When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set) [default: auto]
-h, --help Print help
The services this project defines, and which are running (nami up starts them)
Usage: nami project services [OPTIONS]
Options:
--json
--color <WHEN> When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set) [default: auto]
-h, --help Print help
Projects on this computer you've used (--json for the app)
Usage: nami project list [OPTIONS]
Options:
--json
--color <WHEN> When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set) [default: auto]
-h, --help Print help
Ship your apps
Make your program one file that runs on any Linux
Make your program one file that runs on any Linux distribution (glibc, x86_64), with nothing to install first
From a recipe folder (`nami bundle ./myapp`), a package from the
catalog (`nami bundle jq`), a store path, or a program you built
(`nami bundle ./target/release/myapp`). The file carries the
program's whole closure, glibc
and its loader too; started, it unpacks itself once into ~/.cache
and runs from there, with the computer's own graphics drivers,
fonts, locale and certificates. With --update-url, it updates itself.
`<file> --nami-bundle-help` lists what the file itself can do.
Usage: nami bundle [OPTIONS] [WHAT]
Arguments:
[WHAT]
A project folder (`.`: Rust, Go, CMake, Meson, or programs already built), a release tarball, a recipe folder, a package, a store path, or a program
Options:
-o, --out <OUT>
The file to write (default: ./<program>-x86_64)
--program <PROGRAM>
Which of the package's programs runs (default: its main one)
--mesa
Also carry nixpkgs' Mesa, for computers with no graphics driver the bundle can use (bigger)
--appimage
Also write <file>.AppImage: the same, in AppImage's format (for AppImage tools; it needs FUSE, or --appimage-extract-and-run)
--desktop
Also write <file>.desktop and its icon, the app menu entry
--level <LEVEL>
zstd level, 1-22: higher is smaller and slower to make
[default: 19]
--exclude <NAME>
Leave out store paths named so (`--exclude gst-plugins-bad`), and what only they need: for what the program never uses
--thin
Leave out what cache.nixos.org has: a small file that fetches (and checks) the rest when it first starts, so it needs the network once
--verify <FILE>
Check a bundle against its own hash instead
--name <NAME>
A project's name, where its files don't say (also `bundle: name:` in project.nami)
--app-version <VERSION>
A project's version, where its files and tags don't say (also `bundle: version:`)
--icon <FILE>
A project's icon, .png or .svg (also `bundle: icon:`)
--desktop-file <FILE>
A project's app menu entry, a .desktop file (also `bundle: desktop:`)
--update-url <URL>
Make it update itself from this folder (an https:// URL, or github:<owner>/<repo> for its latest release): updates are signed with your key (~/.config/nami/bundle-signing.key, made the first time; NAMI_BUNDLE_SIGNING_KEY in CI)
--publish-dir <DIR>
Also write what to upload to the --update-url folder here: the signed feed, the parts and the bundle
--previous <FILE|DIR|URL>
With --publish-dir, the release before this one, for updates that download only what changed: its bundle file, the folder it was published from, or its URL; `none` for none (default: what --publish-dir has from the last time, else what --update-url serves now)
--developer <NAME>
Your name, as people know you: shown with the key that signs its updates (also `bundle: developer:`)
--sandbox [<RIGHTS>]
Run it in a sandbox (bubblewrap) where the computer has one, with only these rights: network, documents, downloads, music, pictures, videos, desktop, home, gpu, audio, camera (also `bundle: sandbox:`)
--show-signing-key
Print your bundle signing key's public half (making the key if there's none)
--rotate-key
Make a new signing key, handed over to by the one you have: your next release carries the handover, and the copies people have follow it (the old key is kept beside it)
--test
Then run it on Ubuntu 20.04 and 24.04, Debian 12, Fedora, Arch, openSUSE and Linux Mint, each in a clean container (rootless podman), and say where it started and opened its window (`nami bundle --test <bundle>`: one made before)
--test-on <DISTRO>
With --test: only these distributions (ubuntu:20.04, ubuntu:24.04, debian:12, fedora, arch, opensuse, mint)
--test-args <ARGS>
With --test, for a command: what to run it with (default: --version)
--json
With --test: the results as JSON
--arch <ARCH>
The computers it's for: x86_64 (this one), or aarch64 (ARM) for a package from the catalog (`nami bundle jq --arch aarch64`)
[default: x86_64]
[possible values: x86_64, aarch64]
--color <WHEN>
When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set)
[default: auto]
-h, --help
Print help (see a summary with '-h')
Examples:
# This folder's project as one file
$ nami bundle .
# A package from the catalog
$ nami bundle jq
# Then test it on seven distributions
$ nami bundle . --test
Build a package recipe
Build a package recipe (a directory with package.nami) and print its store path
Usage: nami build [OPTIONS] <RECIPE>
Arguments:
<RECIPE>
Options:
-K, --keep-failed
Keep the build directory when the build fails
--color <WHEN>
When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set)
[default: auto]
-h, --help
Print help (see a summary with '-h')
Write a recipe from a Debian package
Write a recipe for you: `nami recipe from-deb <url | file.deb | Ubuntu package>`
Usage: nami recipe [OPTIONS] <COMMAND>
Commands:
from-deb A recipe from a Debian package: a URL, a .deb file, or a package in Ubuntu's archive by name. Writes <dir>/package.nami to check and build
help Print this message or the help of the given subcommand(s)
Options:
--color <WHEN>
When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set)
[default: auto]
-h, --help
Print help (see a summary with '-h')
A recipe from a Debian package: a URL, a .deb file, or a package in Ubuntu's archive by name. Writes <dir>/package.nami to check and build
Usage: nami recipe from-deb [OPTIONS] <WHAT>
Arguments:
<WHAT>
Options:
-o, --out <OUT> Where to write it (default: ./<package name>)
--release <RELEASE> The Ubuntu release to look a name up in [default: resolute]
--color <WHEN> When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set) [default: auto]
-h, --help Print help
Upload what this computer built to a cache
Upload what this machine built to a cache directory (serve it anywhere)
Usage: nami push [OPTIONS] <DEST> [TARGETS]...
Arguments:
<DEST>
The cache directory
[TARGETS]...
Recipes or store paths (default: everything in the current change)
Options:
--key <KEY>
Sign with this key (its name, from `nami keygen`)
--color <WHEN>
When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set)
[default: auto]
-h, --help
Print help (see a summary with '-h')
Apps from other distributions
Start a program built for another distribution
Start a program built for another distribution (a download, an AppImage), as Files does when you open one: it's made a program first if it isn't one yet (asked), and what it lacks is said
Usage: nami start [OPTIONS] <FILE> [ARGS]...
Arguments:
<FILE>
[ARGS]...
Options:
--color <WHEN>
When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set)
[default: auto]
-h, --help
Print help (see a summary with '-h')
Find the libraries a program is missing
Why a program built for another distribution won't start: the libraries it needs that this computer doesn't have, and the packages that have them (--add: add them to your programs' libraries)
Usage: nami libraries [OPTIONS] <PROGRAM>
Arguments:
<PROGRAM>
Options:
--add
--color <WHEN>
When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set)
[default: auto]
-h, --help
Print help (see a summary with '-h')
Add a downloaded app to the launcher
Put a program built for another distribution (an AppImage, a downloaded app) in the launcher, with its own name and picture when it brings them
Usage: nami add-to-launcher [OPTIONS] <FILE>
Arguments:
<FILE>
Options:
--color <WHEN>
When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set)
[default: auto]
-h, --help
Print help (see a summary with '-h')
Describe a download before installing it
What a downloaded package (.deb, .rpm, AppImage, tarball) is, before it's installed: its name, version, maker, size, and what won't work
Usage: nami package-info [OPTIONS] <FILE>
Arguments:
<FILE>
Options:
--json
--color <WHEN>
When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set)
[default: auto]
-h, --help
Print help (see a summary with '-h')
List and update apps installed from downloads
The apps you installed from downloads (`nami install ./foo.deb`); --updates: whether their makers have newer ones; --update [app]: update them now
Usage: nami file-apps [OPTIONS] [APP]
Arguments:
[APP]
One app: its id, package or name
Options:
--json
--updates
Say whether there's a newer version of each (nothing is installed)
--update
Update them now (or only APP): each checked as its maker signed it, then put in place
--automatic <on|off>
Turn APP's automatic updates on or off
[possible values: on, off]
--color <WHEN>
When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set)
[default: auto]
-h, --help
Print help (see a summary with '-h')
namiOS
Make a USB drive that starts namiOS
Make a USB drive that boots the namiOS computer a system file describes (`nami new laptop --from namios` makes one): a config repo (github:you/cfg/laptop: its computer laptop), a folder, or the file
Usage: nami usb [OPTIONS] [CONFIG]
Arguments:
[CONFIG]
Options:
--list
List the USB drives and removable disks plugged in, and stop
--json
Progress (and --list) as JSON lines, for nami-gui
--password-stdin
The new computer's passwords (for whoever has none) from stdin: a login:password line each
--to <TO>
Write it onto this USB drive (a whole disk, like /dev/sdb; it's erased)
--out <OUT>
Copy the image to this file instead (for a VM, or another tool)
--yes
Don't ask before erasing the USB drive
--system-only <SYSTEM_ONLY>
No image: the system for a VM, into this folder (its kernel, initrd and a root disk; the VM shares the store). For tests/vm-quick.sh
--for-anyone
An image anyone may download: nobody on it yet (namiOS's login screen asks at the first start), no secrets, and no Secure Boot key of its own (each computer makes one)
--color <WHEN>
When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set)
[default: auto]
-h, --help
Print help (see a summary with '-h')
Examples:
# List the USB drives plugged in
$ nami usb --list
# Make one from your config repo
$ nami usb github:ada/nami-config/laptop --to /dev/sdb
Try a namiOS computer in a window
Try a namiOS computer before making its USB drive: it starts in a window, its store shared with this one (nothing is written to a disk). --check: no window; it logs in and runs nami doctor there
Usage: nami try [OPTIONS] [CONFIG]
Arguments:
[CONFIG]
The system file, or a computer's folder, or a config repo's
Options:
--disk <DISK>
A whole computer's disk image instead (namiOS's release image, as the namiOS Installer writes it): started from it, as a PC starts (UEFI); what it changes is kept in the file
--check
No window: log in as its first admin and run `nami doctor`
--password-stdin
Passwords as login:password lines on stdin (--check: the admin's)
--memory <MEMORY>
Its memory, in GB
[default: 4]
--color <WHEN>
When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set)
[default: auto]
-h, --help
Print help (see a summary with '-h')
Install this namiOS computer onto a disk
Put this computer (one `nami usb` made, started from its USB drive) onto a disk of its own: its people, files, apps and settings come along. The disk is erased; with Windows on it, it asks whether to keep Windows and install next to it. Without a disk, lists them
Usage: nami install-to [OPTIONS] [DISK]
Arguments:
[DISK]
The whole disk, like /dev/nvme0n1 or /dev/sda
Options:
--yes
Don't ask (with Windows on the disk, say --next-to-windows or --whole-disk too)
--encrypt
Encrypt the disk (it asks for a password at every start; scripts: NAMI_DISK_PASSWORD)
--next-to-windows
Keep Windows: install next to it, in free space or room made on C:
--whole-disk
Erase the whole disk, Windows too
--size <SIZE>
Next to Windows: how much space this computer gets, like 120G
--list
The disks there are, as JSON, and the room this computer needs (for nami-gui)
--json
Progress as JSON lines (for nami-gui)
--password-stdin
Encrypt it, with the password on stdin (for nami-gui)
--color <WHEN>
When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set)
[default: auto]
-h, --help
Print help (see a summary with '-h')
Control the namiOS desktop from scripts
The namiOS desktop from the command line, for scripts and agents: what Control Center does (sound, brightness, Wi-Fi, Bluetooth, Do Not Disturb, dark or light, Night Shift), Settings' pages, screenshots, windows, notifications and locking (--json for JSON)
It asks the desktop running in this session (namiOS), which does it as its own switches do; what's kept (look, Night Shift, Do Not Disturb, wallpaper) goes into your user.nami.
Usage: nami desktop [OPTIONS] <COMMAND>
Commands:
status Everything at once: sound, screens, network, Bluetooth, Do Not Disturb, look, Night Shift, battery, windows
volume The sound's volume: show it, or set it (40, +5, -5)
mute Mute the sound (on), unmute it (off), or switch (toggle; the default)
output The sound outputs, or use one (by its id or name)
brightness Each screen's brightness, or set it (1-100)
wifi Wi-Fi: whether it's on and to what; on, off, list, connect
bluetooth Bluetooth: whether it's on, and the devices paired; on, off, list
dnd Do Not Disturb: show it, turn it on (until turned off, --for a while, or --until a time), or off
look Light or dark (or auto: by the sun), as Control Center's Dark switch sets it; kept in your user.nami
night Night Shift: off, on (always) or sunset (sunset to sunrise); kept in your user.nami
wallpaper The wallpaper: show it, or set a picture (kept in your user.nami)
settings Open Settings, at a page (appearance, network, bluetooth, sound, displays, notifications, ...; none: its first)
screenshot A screenshot of the screen (or one window), written to a PNG file, quietly
windows The open windows: id, app, title, workspace, which is in use
focus Bring a window to the front (its id, app or title)
close Close a window (its id, app or title), as its close button does
notify Show a notification
lock Lock the screen
help Print this message or the help of the given subcommand(s)
Options:
--json
Print JSON (errors too: {"error": {"code", "message", "hint"}})
--color <WHEN>
When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set)
[default: auto]
-h, --help
Print help (see a summary with '-h')
Everything at once: sound, screens, network, Bluetooth, Do Not Disturb, look, Night Shift, battery, windows
Usage: nami desktop status [OPTIONS]
Options:
--json Print JSON (errors too: {"error": {"code", "message", "hint"}})
--color <WHEN> When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set) [default: auto]
-h, --help Print help
The sound's volume: show it, or set it (40, +5, -5)
Usage: nami desktop volume [OPTIONS] [LEVEL]
Arguments:
[LEVEL] A percentage (0-100), or a step (+5, -10)
Options:
--json Print JSON (errors too: {"error": {"code", "message", "hint"}})
--color <WHEN> When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set) [default: auto]
-h, --help Print help
Mute the sound (on), unmute it (off), or switch (toggle; the default)
Usage: nami desktop mute [OPTIONS] [STATE]
Arguments:
[STATE] [possible values: on, off, toggle]
Options:
--json Print JSON (errors too: {"error": {"code", "message", "hint"}})
--color <WHEN> When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set) [default: auto]
-h, --help Print help
The sound outputs, or use one (by its id or name)
Usage: nami desktop output [OPTIONS] [DEVICE]
Arguments:
[DEVICE]
Options:
--json Print JSON (errors too: {"error": {"code", "message", "hint"}})
--color <WHEN> When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set) [default: auto]
-h, --help Print help
Each screen's brightness, or set it (1-100)
Usage: nami desktop brightness [OPTIONS] [PERCENT]
Arguments:
[PERCENT]
Options:
--screen <SCREEN> Only this screen (its name, as listed)
--json Print JSON (errors too: {"error": {"code", "message", "hint"}})
--color <WHEN> When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set) [default: auto]
-h, --help Print help
Wi-Fi: whether it's on and to what; on, off, list, connect
Usage: nami desktop wifi [OPTIONS] [COMMAND]
Commands:
on
off
list The networks in range (looks again first)
connect Join a network; a password comes on stdin (--password-stdin), never on the command line
help Print this message or the help of the given subcommand(s)
Options:
--json Print JSON (errors too: {"error": {"code", "message", "hint"}})
--color <WHEN> When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set) [default: auto]
-h, --help Print help
Usage: nami desktop wifi on [OPTIONS]
Options:
--json Print JSON (errors too: {"error": {"code", "message", "hint"}})
--color <WHEN> When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set) [default: auto]
-h, --help Print help
Usage: nami desktop wifi off [OPTIONS]
Options:
--json Print JSON (errors too: {"error": {"code", "message", "hint"}})
--color <WHEN> When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set) [default: auto]
-h, --help Print help
The networks in range (looks again first)
Usage: nami desktop wifi list [OPTIONS]
Options:
--json Print JSON (errors too: {"error": {"code", "message", "hint"}})
--color <WHEN> When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set) [default: auto]
-h, --help Print help
Join a network; a password comes on stdin (--password-stdin), never on the command line
Usage: nami desktop wifi connect [OPTIONS] <NETWORK>
Arguments:
<NETWORK>
Options:
--password-stdin Read the password from stdin (one line)
--json Print JSON (errors too: {"error": {"code", "message", "hint"}})
--color <WHEN> When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set) [default: auto]
-h, --help Print help
Bluetooth: whether it's on, and the devices paired; on, off, list
Usage: nami desktop bluetooth [OPTIONS] [COMMAND]
Commands:
on
off
list The devices paired, and which are connected
help Print this message or the help of the given subcommand(s)
Options:
--json Print JSON (errors too: {"error": {"code", "message", "hint"}})
--color <WHEN> When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set) [default: auto]
-h, --help Print help
Usage: nami desktop bluetooth on [OPTIONS]
Options:
--json Print JSON (errors too: {"error": {"code", "message", "hint"}})
--color <WHEN> When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set) [default: auto]
-h, --help Print help
Usage: nami desktop bluetooth off [OPTIONS]
Options:
--json Print JSON (errors too: {"error": {"code", "message", "hint"}})
--color <WHEN> When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set) [default: auto]
-h, --help Print help
The devices paired, and which are connected
Usage: nami desktop bluetooth list [OPTIONS]
Options:
--json Print JSON (errors too: {"error": {"code", "message", "hint"}})
--color <WHEN> When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set) [default: auto]
-h, --help Print help
Do Not Disturb: show it, turn it on (until turned off, --for a while, or --until a time), or off
Usage: nami desktop dnd [OPTIONS] [STATE]
Arguments:
[STATE] [possible values: on, off]
Options:
--for <DURATION> For this long: 30m, 2h (as nami writes durations)
--until <UNTIL> Until this evening, tomorrow (morning), or a time: "2026-11-19 18:00"
--json Print JSON (errors too: {"error": {"code", "message", "hint"}})
--color <WHEN> When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set) [default: auto]
-h, --help Print help
Light or dark (or auto: by the sun), as Control Center's Dark switch sets it; kept in your user.nami
Usage: nami desktop look [OPTIONS] [LOOK]
Arguments:
[LOOK]
Possible values:
- light
- dark
- auto: Light by day, dark at night
Options:
--json
Print JSON (errors too: {"error": {"code", "message", "hint"}})
--color <WHEN>
When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set)
[default: auto]
-h, --help
Print help (see a summary with '-h')
Night Shift: off, on (always) or sunset (sunset to sunrise); kept in your user.nami
Usage: nami desktop night [OPTIONS] [WHEN]
Arguments:
[WHEN]
Possible values:
- off
- on: On all the time (same as always)
- always
- sunset: From sunset to sunrise
Options:
--warmth <WARMTH>
How warm, in kelvin (2500 warmest, 5000 least)
--json
Print JSON (errors too: {"error": {"code", "message", "hint"}})
--color <WHEN>
When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set)
[default: auto]
-h, --help
Print help (see a summary with '-h')
The wallpaper: show it, or set a picture (kept in your user.nami)
Usage: nami desktop wallpaper [OPTIONS] [PICTURE]
Arguments:
[PICTURE]
Options:
--json Print JSON (errors too: {"error": {"code", "message", "hint"}})
--color <WHEN> When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set) [default: auto]
-h, --help Print help
Open Settings, at a page (appearance, network, bluetooth, sound, displays, notifications, ...; none: its first)
Usage: nami desktop settings [OPTIONS] [PAGE]
Arguments:
[PAGE]
Options:
--json Print JSON (errors too: {"error": {"code", "message", "hint"}})
--color <WHEN> When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set) [default: auto]
-h, --help Print help
A screenshot of the screen (or one window), written to a PNG file, quietly
Usage: nami desktop screenshot [OPTIONS] <FILE>
Arguments:
<FILE>
Options:
--window <WINDOW> Only this window (its id, app or title, as `nami desktop windows` lists them)
--pointer With the pointer in it
--json Print JSON (errors too: {"error": {"code", "message", "hint"}})
--color <WHEN> When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set) [default: auto]
-h, --help Print help
The open windows: id, app, title, workspace, which is in use
Usage: nami desktop windows [OPTIONS]
Options:
--json Print JSON (errors too: {"error": {"code", "message", "hint"}})
--color <WHEN> When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set) [default: auto]
-h, --help Print help
Bring a window to the front (its id, app or title)
Usage: nami desktop focus [OPTIONS] <WINDOW>
Arguments:
<WINDOW>
Options:
--json Print JSON (errors too: {"error": {"code", "message", "hint"}})
--color <WHEN> When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set) [default: auto]
-h, --help Print help
Close a window (its id, app or title), as its close button does
Usage: nami desktop close [OPTIONS] <WINDOW>
Arguments:
<WINDOW>
Options:
--json Print JSON (errors too: {"error": {"code", "message", "hint"}})
--color <WHEN> When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set) [default: auto]
-h, --help Print help
Show a notification
Usage: nami desktop notify [OPTIONS] <TITLE> [BODY]
Arguments:
<TITLE>
[BODY]
Options:
--app <APP> Who it's from (default: Terminal)
--json Print JSON (errors too: {"error": {"code", "message", "hint"}})
--color <WHEN> When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set) [default: auto]
-h, --help Print help
Lock the screen
Usage: nami desktop lock [OPTIONS]
Options:
--json Print JSON (errors too: {"error": {"code", "message", "hint"}})
--color <WHEN> When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set) [default: auto]
-h, --help Print help
Agents
Connect an AI agent to nami over MCP
Serve nami's tools to an AI agent over MCP (stdio): `claude mcp add nami -- nami mcp`
Search, look up, install and remove your apps, change and apply your user.nami, look back and undo, and propose changes to computer.nami for an administrator to approve. It never changes the computer's file itself.
Usage: nami mcp [OPTIONS]
Options:
--color <WHEN>
When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set)
[default: auto]
-h, --help
Print help (see a summary with '-h')
Ask an administrator to change computer.nami
Ask an administrator to change computer.nami: for agents and other tools, without the password
The change is an edit as `nami config json` takes it, or a list of them (`-` reads it from stdin). It's checked (`nami check`) and kept until someone decides: Settings shows it with its reason, and Apply asks for an administrator's password. `nami proposals` lists them. Your own user.nami needs no approval: change it with `nami config`.
Usage: nami propose [OPTIONS] --reason <REASON> <EDIT>
Arguments:
<EDIT>
The edit: {"add": {"path": ["packages"], "value": "docker"}}, or a list of edits
Options:
--reason <REASON>
Why, in a sentence, for the person approving it
--by <BY>
Who's asking, as the person approving it reads it (default: "An app")
--wait
Wait for the decision, then print the result as JSON
--timeout <SECONDS>
With --wait: give up after this many seconds (default: wait as long as it takes)
[default: 0]
--json
Print the proposal as JSON
--quiet
Don't post a notification
--color <WHEN>
When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set)
[default: auto]
-h, --help
Print help (see a summary with '-h')
List, approve or reject proposed changes
Changes to computer.nami waiting for approval (`nami propose`): list, show, apply or reject them
Usage: nami proposals [OPTIONS] <COMMAND>
Commands:
list The proposals waiting for a decision (--all: those decided lately too)
show One proposal: who asks, why, and what it changes, in words and lines
apply Approve one: an administrator's password is asked for, then computer.nami is changed and applied
reject Don't allow one: it's discarded, and whoever asked is told
help Print this message or the help of the given subcommand(s)
Options:
--color <WHEN>
When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set)
[default: auto]
-h, --help
Print help (see a summary with '-h')
The proposals waiting for a decision (--all: those decided lately too)
Usage: nami proposals list [OPTIONS]
Options:
--all
--json
--color <WHEN> When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set) [default: auto]
-h, --help Print help
One proposal: who asks, why, and what it changes, in words and lines
Usage: nami proposals show [OPTIONS] <ID>
Arguments:
<ID>
Options:
--json
--color <WHEN> When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set) [default: auto]
-h, --help Print help
Approve one: an administrator's password is asked for, then computer.nami is changed and applied
Usage: nami proposals apply [OPTIONS] <ID>
Arguments:
<ID>
Options:
--expect <EXPECT> Only if it's still the proposal with this fingerprint (`show --json`), as it was shown
--color <WHEN> When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set) [default: auto]
-h, --help Print help
Don't allow one: it's discarded, and whoever asked is told
Usage: nami proposals reject [OPTIONS] <ID>
Arguments:
<ID>
Options:
--color <WHEN> When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set) [default: auto]
-h, --help Print help
nami itself
Show who you are to nami, and its catalog
Who you are to nami, your profile and the catalog
Usage: nami status [OPTIONS]
Options:
--json
Print JSON
--color <WHEN>
When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set)
[default: auto]
-h, --help
Print help (see a summary with '-h')
Check that this computer's setup works
Show what GUI support (drivers, locales, fonts) is active; on a computer nami made, whether what its packages set up works (their checks)
Usage: nami doctor [OPTIONS]
Options:
--json
Each check's result as a JSON line (for nami-gui)
--hardware
Only which of nami's packages this computer's hardware is for
--about
Only what the computer is: its model, processor, memory, graphics, disks, battery and network
--color <WHEN>
When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set)
[default: auto]
-h, --help
Print help (see a summary with '-h')
Examples:
# Check this computer
$ nami doctor
Tell nami's makers something's wrong
Tell nami's makers something's wrong: what happened, with nami doctor, the last changes and your nami files (secrets left out), shown first
Usage: nami report [OPTIONS]
Options:
--message <MESSAGE>
What happened (asked for if not given)
--yes
Send without asking
--no-files
Leave out the nami files
--show
Only show what would be sent
--json
Print JSON
--color <WHEN>
When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set)
[default: auto]
-h, --help
Print help (see a summary with '-h')
Update nami itself
Installs the newest nami, signed, from where the catalog comes from.
Usage: nami self-update [OPTIONS]
Options:
--check
Only say whether there's a newer version
--json
Print JSON
--color <WHEN>
When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set)
[default: auto]
-h, --help
Print help (see a summary with '-h')
Examples:
# Is there a newer nami?
$ nami self-update --check
Free space: delete old changes
Delete old changes (by the rules given), then unused store paths. Without --old, --keep or --older-than, only what nothing uses goes. Old changes also go by themselves, as `cleanup:` says (30 days, the 3 newest kept): with --auto, as the daily update does it
Usage: nami gc [OPTIONS]
Options:
--auto
As the daily update does: old changes as `cleanup:` says (root: the computer's, then each person's as them), then what nothing uses, quietly
--now
By `cleanup:`'s rules, without waiting: every old change but the newest it keeps (3) and the current one (Settings' Clean Up Now)
--old
Delete every change but the current one
--keep <KEEP>
Keep the newest N changes
--older-than <OLDER_THAN>
Keep changes younger than this (30d, 12h, 2w)
--dry-run
Delete nothing: say what would go, and how much it frees
--json
Print JSON
--color <WHEN>
When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set)
[default: auto]
-h, --help
Print help (see a summary with '-h')
Examples:
# See what would be freed
$ nami gc --dry-run
# Keep the last month of changes
$ nami gc --older-than 30d
Print the shell script for Tab completion
Tab completes nami's commands, options, packages (`nami install fi<Tab>`), versions (`firefox@<Tab>`), the project's tasks and services, changes and nami file keys. nami's installer and namiOS set it up for every shell they find; for your own dotfiles: `eval "$(nami completions bash)"` in ~/.bashrc, `eval "$(nami completions zsh)"` in ~/.zshrc (after compinit), `nami completions fish | source` in fish's config.
Usage: nami completions [OPTIONS] <SHELL>
Arguments:
<SHELL>
bash, zsh or fish
[possible values: bash, zsh, fish]
Options:
--color <WHEN>
When to use colour: auto, always or never (auto: in a terminal, unless NO_COLOR is set)
[default: auto]
-h, --help
Print help (see a summary with '-h')