nami alpha Docs

Commands

All 52 commands and their subcommands (116 in all), with every flag: what nami <command> --help prints.

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

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')

Something wrong or missing here? nami report tells us, or Report a problem in the nami window.