nami alpha Docs

Scripts and agents

Read nami's output as JSON, handle its errors by code, run it with nobody to answer questions, and control the namiOS desktop from the command line.

Get JSON

Add --json to any command whose output a program reads. It prints one JSON value on stdout, and nothing else there.

nami search ripgrep --json        # [{"attr": "ripgrep", "version": "14.1.1", ...}]
nami list --json                  # what's installed
nami status --json                # who you are to nami, your change, the catalog
nami history --json               # every change, to go back to
nami check user.nami --json       # problems in a file, by line
nami apply --dry-run --json       # what would change, without changing it

Commands that only change something, such as install, remove, apply, undo and update, print {"ok": true} when they’re done. What they say along the way goes to stderr.

These also take --json: info, diff, doctor, upgrade --dry-run, gc --dry-run, layers, show, options, config get, project list, project tasks, project services, backup list, backup status, sync status, home diff, package-info, file-apps, new, and every nami desktop command.

Handle errors

With --json, a command that fails prints an error object on stdout, and its plain message on stderr as always:

{"error": {"code": "not_found", "message": "unknown package \"rigrep\"; did you mean: ripgrep", "hint": "`nami search rigrep` looks for it."}}

hint is there only when there’s something to suggest. Match on code; the message is for people and may change. The codes stay the same from one nami to the next:

CodeWhat happened
invalid_argsThe command line or a value on it is wrong.
not_foundA package, file, change, window, network or page isn’t there.
invalid_fileA nami file has an error in it. nami check lists them by line.
needs_adminIt changes the computer for everyone: an administrator’s password is needed.
needs_inputIt would ask a question and nobody can answer. Pass the answer as a flag.
networkNo connection, or a download failed. Trying again later may work.
conflictSomething else is changing it, it changed meanwhile, or it already exists.
deniedRefused: a wrong password, or not allowed.
not_runningThe namiOS desktop isn’t running in this session.
unsupportedNot on this computer: no hardware for it, or not namiOS.
failedAnything else.

The exit code says the same, with or without --json:

Exit codeMeaning
0It worked.
1It failed (failed, not_found, invalid_file and the rest).
2The command line is wrong (invalid_args).
75The network (network): try again later.
77An administrator is needed (needs_admin).

Run with nobody to answer

Set NAMI_NONINTERACTIVE=1 and nothing waits for an answer, in the terminal or in a window. A command that would ask fails with needs_input, and its hint names the flag that answers it:

export NAMI_NONINTERACTIVE=1
nami report                       # needs_input: pass --message "..."
nami usb laptop --to /dev/sdb     # needs_input: pass --yes

Without a terminal, nami asks nothing in one either, but a change to the computer’s file can still bring up a password box on the desktop. With NAMI_NONINTERACTIVE set, no box comes up: the command fails with needs_admin, unless an administrator’s password was given in the last few minutes.

Control the desktop

On namiOS, nami desktop does what Control Center does, for the person logged in. Each command shows the current state, or changes it and shows the new one.

nami desktop status --json        # everything at once
nami desktop volume 40            # also +5, -5
nami desktop mute                 # on, off, or toggle (the default)
nami desktop output               # the sound outputs; `output "USB Speakers"` uses one
nami desktop brightness 70
nami desktop wifi list            # also on, off; `wifi connect Home --password-stdin`
nami desktop bluetooth off        # also on, list
nami desktop dnd on --for 1h      # Do Not Disturb; also --until evening, or off
nami desktop look dark            # also light, auto
nami desktop night on             # Night Shift; also sunset, off, --warmth 3500
nami desktop wallpaper ~/Pictures/sea.jpg
nami desktop settings sound       # opens Settings at a page
nami desktop screenshot shot.png  # quietly; --window firefox for one window
nami desktop windows              # id, app, title, which is in use
nami desktop focus firefox        # or close; by id, app or title
nami desktop notify "Build done" "All tests passed"
nami desktop lock

What’s kept goes into your ~/user.nami, as Control Center and Settings write it, so the file stays the truth:

~/user.nami
namios:  appearance: { look: dark, wallpaper: /home/ada/Pictures/sea.jpg }  night: { when: always }  notifications: { quiet: true, quiet-until: "2026-11-19 18:00" }

nami desktop talks to the desktop over a socket only you can use ($XDG_RUNTIME_DIR/nami-desktop.sock). From another session, such as SSH, it fails with not_running.

Tell your agent about nami

nami new <folder> --from <starter> writes an AGENTS.md next to project.nami. It tells coding agents how to run the project’s tasks, add a tool, and read nami’s JSON. A file that’s already there is kept.

For an overview of nami to give a language model, see /llms.txt.

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