avr [flags] [--] [COMMAND [ARGS...]]
avr [flags] SUBCOMMAND [ARGS...]
avar reads a command line from the left, in three steps:
-- ends avar’s flags and makes everything after it a command to run
in Linux, even a word that names an avar subcommand. avr -- on its own
opens a shell.Nothing at or after that deciding token is read as an avar flag. The command in Linux keeps its own flags:
avr npm test --watch # --watch goes to npm
avr --arch amd64 make # --arch is avar's: it comes first
avr make --arch amd64 # --arch goes to make
With no deciding token at all, avr opens an interactive shell.
These are the only flags avar reads, and only in the flag position.
| Flag | Value | What it does |
|---|---|---|
--distro |
ubuntu, debian or fedora, optionally name:version |
Chooses the distribution. See the environment matrix |
--arch |
arm64 or amd64 |
Chooses the guest CPU architecture |
--isolate |
none | Uses an environment dedicated to this project, and remembers that choice for the project |
--shared |
none | Uses the environment shared by every project, for this invocation only |
--env |
NAME or NAME=value |
Forwards the host’s NAME, or sets NAME to value, in the guest session. Repeatable |
--env-file |
a path | Forwards every KEY=value line of the file into the guest session |
--ssh-agent |
none | Lends the guest your SSH agent for this invocation |
--native-fs |
none | Runs the session in a copy of the project on the Linux filesystem. Windows only; see Platform notes |
--help, -h |
none | Shows avar’s help |
--version, -v |
none | Prints avar’s version |
=:
--arch amd64 and --arch=amd64 are the same.=, such
as --isolate=false. Anything that is not a boolean is refused.--distro names are case-insensitive. A colon with nothing after it, as in
--distro fedora:, is refused.--isolate and --shared together are refused.--distro, --arch, --isolate and --shared select the environment for
the shell, a one-shot command, and the management commands that act on
“this environment”: stop, reset, destroy, snapshot, restore,
sync, code, cursor, zed, ports and open. They also choose what
avr init proposes for. avr status, avr stop --all, avr ports --all
and avr destroy --all or --orphaned act across environments instead.--env, --env-file and --ssh-agent apply only to a shell or a one-shot
command.--native-fs applies to a shell, a one-shot command and the editor
commands.Each of these exits with status 2 and changes nothing:
| Command line | Why |
|---|---|
avr --arhc amd64 |
A token starting with - in the flag position that is not an avar flag. The message suggests avr --help, or avr -- --arhc ... to pass it to Linux |
avr --distro arch |
A distribution avar does not know |
avr --distro fedora: |
A colon with no version |
avr --arch |
A flag that needs a value, at the end of the line |
avr --isolate=maybe |
Not a boolean |
avr --isolate --shared |
The two contradict each other |
avr --ssh-agent on Windows |
avar cannot forward your SSH agent there yet. It says so rather than starting a session without the agent |
A release that is not in the environment matrix, such as --distro fedora:41,
passes the grammar and is refused a moment later when avar resolves the
environment, also with status 2.
The first word after avar’s flags decides everything. These names are avar’s subcommands, so they never reach Linux as the start of a command:
code cursor destroy help init internal isolate open ports reset restore snapshot status stop sync update version zed
internal runs avar’s own scheduled idle check and is not a command you run.
To run a program in Linux whose name is on that list, put -- first:
avr -- sync # the guest's sync(1), or your project's ./sync
avr -- open file.txt # a program called open inside Linux
avr -- init # a program called init inside Linux
avr -- update # your project's update script, not avr update
The ones most likely to catch you are sync, a standard Unix command, and
open and update, common names for a project script. Without --, avar runs
its own command instead of yours.