nami alpha Docs

user.nami

Keep your apps, dotfiles, environment, shell and desktop settings in one file, ~/user.nami.

Write your file

~/user.nami is yours: what you install, how your programs are set up, and your shell. It works the same on any distribution and on namiOS.

~/user.nami
packages:  - ripgrep  - git:      ~/.gitconfig:                  # git's settings, under git        user: { name: Ada, email: ada@example.org }env:  EDITOR: nvimaliases:  ll: ls -la
nami apply

You can also keep it at ~/.config/nami/user.nami. Each apply is a change you can undo, dotfiles included.

Which file to use

nami reads three files with the same keys. The file decides whose setup it is.

FileWhere it livesWho changes itWhat it’s for
user.nami~/user.namiyouyour apps, dotfiles, shell and desktop settings
computer.nami/etc/nami/computer.namiadminsapps for everyone, services, /etc files (more)
project.namia project’s folderanyone with the codea project’s tools, tasks and services (more)

nami apply uses computer.nami if you’re an admin and ~/user.nami otherwise. An admin applies their own with nami apply ~/user.nami, and nami config path says which file nami would use.

Keep a dotfile

Put a program’s settings under its package, so they go when the package goes. Nested YAML is written in the file’s own format.

~/user.nami
packages:  - vim:      ~/.vimrc: |                    # text, written as it is        set number  - alacritty:      ~/.config/alacritty/alacritty.toml:   # settings, written as TOML        font: { size: 12 }files:  ~/notes/todo.md: |                 # a file that belongs to no program    - water the plants

nami writes JSON, TOML, YAML, INI, gitconfig and .env files from settings. Anything else, like a vimrc or a shell script, is text. Every path starts with ~/.

source: takes a file or folder next to your nami file.

~/.config/nami/user.nami
packages:  - neovim:      ~/.config/nvim: { source: ./files/nvim }

When the source is inside your home, nami links straight to it, so an edit is live at once and ready to commit. A file already at that path is moved to .nami-backup, never deleted.

Let an app change its settings file

Dotfiles are read-only links. For a file an app saves to itself, like VS Code’s, mark it mutable.

~/user.nami
packages:  - vscode:      ~/.config/Code/User/settings.json:        mutable: true        content:          editor.fontSize: 14

When both you and the app change it, nami merges them setting by setting, and your file wins where both changed the same one. nami home diff shows what apps changed, and nami home keep writes it into your file:

nami home keep
~/user.nami
packages:  - vscode:      ~/.config/Code/User/settings.json:        mutable: true        content:          editor.fontSize: 14          editor.fontSize: 16          workbench.colorTheme: Solarized Light

To start managing a settings file that’s already there, adopt it:

nami home adopt ~/.config/zed/settings.json
~/user.nami
…files:  ~/.config/zed/settings.json:    mutable: true    content:      theme: One Dark      ui_font_size: 16

Set your environment and aliases

env: reaches bash, zsh, fish and your desktop session. aliases: work in all three shells.

~/user.nami
env:  EDITOR: nvim  PATH: $HOME/.local/bin:$PATH       # refers to the variable beforealiases:  ll: ls -la  gs: git status

A new terminal has them at once. Apps you start from the menu get them after you log in again. For a token, use a secret.

Add lines to your shell’s startup

shell: holds lines run at the end of each interactive shell’s startup, like prompts and plugins.

~/user.nami
packages:  - starship  - zsh-autosuggestionsshell:  zsh: |    source "$(nami_share zsh-autosuggestions/zsh-autosuggestions.zsh)"    eval "$(starship init zsh)"  bash: |    eval "$(starship init bash)"

nami_share finds a package’s share/ files, so a plugin’s path survives updates. Applying adds one marked line at the end of ~/.bashrc and ~/.zshrc, and leaves your own lines alone:

~/.zshrc
…[ -r "$HOME/.config/nami/shell.zsh" ] && . "$HOME/.config/nami/shell.zsh"  # added by nami (home.shell)

Choose the shell your terminals open

~/user.nami
packages:  - zsh:      login-shell: true    # or fish

Terminals open zsh without chsh or root. Your login shell stays bash, so if zsh is ever missing, you can still get in.

Set desktop settings

GNOME and GTK apps keep their settings in GSettings. List them by schema under settings:.

~/user.nami
settings:  org.gnome.desktop.interface:    color-scheme: prefer-dark    clock-format: 24hpackages:  - gnome-text-editor:      org.gnome.TextEditor:          # an app's settings, under the app        show-line-numbers: true

nami sets them again on every apply, so take a value out of the file to keep your own. To find a setting, run dconf watch / and flip the switch in the app. Over ssh, settings wait for your desktop session.

KDE, niri and sway keep their settings in files, so write those as dotfiles, mutable when the desktop saves to them.

Run a service for yourself

A service in user.nami runs as you, in your session.

~/user.nami
packages:  - syncthingservices:  - syncthing.service    # the package's own unit

It starts when you apply and each time you log in. How to write your own is in computer.nami.

Change your file from the command line

These commands keep your file’s comments and layout.

nami install ripgrep              # add it and apply
nami config add packages tree     # add it, apply nothing
nami config set env.EDITOR nvim   # change one value, apply nothing
✓ env.EDITOR is nvim in user.nami · nami apply to use it
~/user.nami
packages:  - firefox  - ripgrep  - treeenv:  EDITOR: vim  EDITOR: nvim

nami config remove packages tree and nami config unset env.EDITOR take them out again, and nami config get packages prints what’s there. A key with dots in it goes in brackets: nami config set 'files["~/.gitconfig"].user.name' Ada. Your first nami install writes a ~/user.nami with the apps you already had.

Check your file

nami check finds mistakes without changing anything, and nami apply runs it first.

nami check ~/user.nami
user.nami:3: error: fiefox isn't in the catalog (did you mean `firefox`?)

It exits with 1 on an error, so CI can run it. Set up your editor to see mistakes as you type.

See the whole file

Your file can list other files. nami show --flat prints it merged, with where each value came from.

nami show --flat ~/user.nami
packages:
  - ripgrep  # work.nami
  - htop  # user.nami

To start a file from apps you installed before you had one, nami export prints them as a nami file. How files build on each other is in Config repos and sets.

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