The command line

Everything you click in Wazza OS, a terminal can do too. wazza --gui … commands talk to the Wazza OS that is running for you, in the background, and answer in JSON: for scripts, for a server with no screen, and for agents outside Wazza OS.

Before you start#

• wazza, wazzaos and wazza-os are the same program; this manual writes wazza.
• Wazza OS must be running for the same user: wazza --gui status says so. The commands never open a second window, and only change what you see when you ask (the --focus options).
• Answers are JSON on standard output. Exit codes: 0 done; 1 refused, failed, or Wazza OS not reachable; 2 the command was wrong and nothing was sent (the usage is printed).
• Passwords, keys and tokens are read only from standard input (--stdin, --password-stdin, --key-stdin), never as a word of the command: they stay out of your shell history and the process list.
• wazza --version prints the program's version and the installed package's (version, build and date).
• For agents that take MCP servers rather than a shell, wazza-os mcp offers these same commands as MCP tools (Connect an agent from outside; every tool: Every Wazza OS MCP tool).

$ wazza --gui status
$ wazza --version

Check this computer#

wazza --check runs the same checks as the first start, without starting Wazza OS and without a screen: KVM, the systemd user session, the X11 display, the Chat sandbox, the graphics driver and the VM display buffers. Each line says what was found, what it means, and the commands that fix it.

$ wazza --check
$ wazza --check --json

Exit 0: nothing missing; 1: something is missing (VMs or the window would not start). A limited item (for example software graphics) does not fail the check. What each item means: First start › What is checked.

Set up without clicks#

A setup file does the first start's steps: your Wazza OS account, plan logins, API keys, apps, and appearance. Write it once and run it on every computer:

{
  "account": {"email": "me@example.com", "passwordFile": "~/secrets/wazza-password"},
  "logins": ["claude", "chatgpt"],
  "keys": [{"provider": "openrouter", "name": "work", "keyFile": "~/secrets/openrouter.key"}],
  "whenOneRunsOut": {"openrouter": "take turns"},
  "apps": ["gimp", "blender"],
  "vm": {"memory": "auto", "cpus": "auto"},
  "appearance": {"theme": "dark", "glass": "reduced", "reduceMotion": false},
  "tabs": {"limit": 0}
}

$ wazza --gui setup run --file ~/wazza-setup.json
$ wazza --gui setup status
$ wazza --gui setup reset-first-run

It runs only the steps not done yet, so running it twice changes nothing. Each step prints one line as it ends: ✓ done, → waiting for you (a login prints its link and reads the code you paste in the terminal), ✗ failed. Exit 0: all done; 1: a step needs you or failed; 2: the file is malformed (nothing ran). --file - reads the file from standard input; --json prints one JSON line per step.

VMs#

$ wazza --gui vm list
$ wazza --gui vm create
$ wazza --gui vm start vm-2
$ wazza --gui vm stop vm-2
$ wazza --gui vm backup vm-2
$ wazza --gui vm backups
$ wazza --gui vm restore BACKUP_ID

Memory, disk and graphics#

$ wazza --gui vm-resources
$ wazza --gui vm-memory status
$ wazza --gui vm-memory auto 50
$ wazza --gui vm-disk set 64
$ wazza --gui gpu status

The same settings, explained: Settings › VM resources.

Keys and sign-ins#

$ wazza --gui wazza-account login --email me@example.com --password-stdin < ~/secrets/wazza-password
$ wazza --gui provider-keys add --stdin < ~/secrets/keys.json
$ wazza --gui provider-keys list --credit
$ wazza --gui provider-signin status

keys.json holds {"keys": [{"providerId": "openrouter", "key": "…"}]}; keep it readable only by you, or pipe it from your password manager. Also: provider-keys remove PROVIDER, wazza-account status and logout, copilot key-from-gh (GitHub Copilot from your gh sign-in). Plan logins that open a browser are easiest with the setup file above. Details: Sign in › From the command line.

Chats#

$ wazza --gui chat-model set openrouter/xiaomi/mimo-v2.6-flash
$ wazza --gui chat-transcript --tab t5 --last 4
$ wazza --gui chat-transcript --tab t5 --kinds tool,bash > t5-tools.json
$ wazza --gui timeouts set --command 1800

Tab ids (t5) come from the window's tabs_read action (below). To send a message to a Chat: the window action chat_send.

Apps#

$ wazza --gui app list
$ wazza --gui invoke modules_call packages install_request '{"appId":"gimp","vmId":"vm-1"}'
$ wazza --gui app status gimp --vm vm-1 --refresh
$ wazza --gui app uninstall gimp --vm vm-1 --focus

Files#

$ wazza --gui explorer list Documents --vm vm-1
$ wazza --gui explorer copy-to-vm ~/report.pdf --vm vm-1 --folder Documents
$ wazza --gui explorer upload Pictures/circle.png --vm vm-1
$ wazza --gui clipboard files --to-computer allow

The window, and everything else#

Every action of the window has a name, and ui do runs it with its arguments; ui catalog lists them all (about 200: open an app, read the tabs, send to a Chat, read what you see, start a VM, read the settings…).

$ wazza --gui invoke modules_call ui catalog '{}'
$ wazza --gui invoke modules_call ui do '{"action":"tabs_read","args":{}}'
$ wazza --gui invoke modules_call ui do '{"action":"open_app","args":{"appId":"inkscape"}}'
$ wazza --gui invoke modules_call drive look '{"vmId":"vm-1","tabId":"t3"}' --image-out ./t3

Arguments larger than a command line holds: - reads them from standard input, @file.json from a file. Also: data status (Wazza OS's folders on your computer and their sizes), data remove-all --confirm "REMOVE ALL DATA" (Remove all data), quit. On a server, screenshot and record capture Wazza OS's own screen (Wazza OS on a server).

When an agent runs these commands#

A command run by the agent of a Chat (from its shell) is that Chat's: it may not change your view (focus, quit), reach another tab's Chat, copy files for another VM, or do what only you can do (Let this Chat edit my files, loosening the file-copy rules, Local services on). An agent outside Wazza OS that you started yourself runs the commands as you, in its shell or through wazza-os mcp (Connect an agent from outside).