avr init

Looks at the project’s manifests, proposes a .avr.toml that pins the environment they describe, and writes it only if you confirm. It installs nothing and starts nothing.

1. Help
2. Examples
3. What it does
   1. What it proposes
   2. After writing
4. Exit status
5. Errors
   1. already exists
   2. no terminal
   3. takes no arguments

Help

This is exactly what avr help init or avr init --help prints.

Usage:
  avr [selector flags] init

Look at this project's manifests (package.json, pyproject.toml, go.mod, Cargo.toml, Dockerfile, docker-compose.yml, .tool-versions, mise.toml), show the stack they describe and the .avr.toml that would pin it, and write that file only if you confirm. Nothing is written without a terminal, and an existing .avr.toml is never replaced. Writing the file installs nothing: the next `avr` asks before installing its packages. --distro and --arch choose what the proposal is for.

`init` is an avar command, so it does not reach the guest: to run a program called `init` in Linux, use `avr -- init`.

Selector flags such as --arch and --distro must come before the command; run `avr --help` to see them.

Examples

avr init                       # propose a .avr.toml for this project
avr --distro fedora init       # propose one for Fedora
avr --arch amd64 init          # propose one pinned to amd64

What it does

1. Finds the project for the current directory. If it already has a .avr.toml, avar stops: avr init never replaces a file.

2. Reads these manifests from the project directory itself, not its subdirectories:

   package.json, pyproject.toml, go.mod, Cargo.toml, .tool-versions, mise.toml, Dockerfile, docker-compose.yml, docker-compose.yaml

   A manifest larger than 1 MiB is noted but not read.

3. Prints what it found, any notes, and the exact file it would write, with the full path.
4. Asks Write <path>? (y/N). Only y or yes writes the file.

When no manifest is found, it says avar needs no configuration and exits 0.

What it proposes

• distro, always: the --distro you gave, otherwise the distribution of the Dockerfile’s final FROM image when avar can match it (Ubuntu, Debian, Fedora, and official language images based on Debian), otherwise avar’s default.
• arch, only from --arch, or from --platform=linux/<arch> on the Dockerfile’s final FROM.
• packages: the distribution’s own packages for each runtime it detects.

It never proposes cpus, memory or forward_env: no manifest states a size, and a proposal to forward credentials is exactly what a detected file must not make.

Its notes say what the proposal does not do. When a manifest pins a runtime version, the note says the distribution’s package version is what will be installed, not the pinned one. Docker Compose is reported and proposes nothing, because installing a container engine is not a package line. A tool listed in .tool-versions or mise.toml that maps to none of the runtimes above is named as having no proposal.

After writing

Writing the file is not approval. The next avr in the project lists the packages and asks before installing them.

Exit status

Errors

already exists

avr: <project>/.avr.toml already exists, and avr init only writes a new one; nothing was changed. Edit it, or remove it and run avr init again

Exit status 1.

no terminal

avr: nothing was written: avr init writes .avr.toml only after you confirm, so run it from a terminal

The proposal is still printed first. There is no --yes. Exit status 1.

takes no arguments

avr: `avr init` takes no arguments, but got "<args>"; selector flags such as --distro go before it, as in `avr --distro fedora init`

Exit status 2.