Configuration, Profiles & Monorepos

Project configuration

Use valid JSON: aliases, env and tools map names to strings. root is a boolean. Comments are not accepted. This example establishes a project boundary and a Node version range.

{
  "root": true,
  "tools": { "node": "22" },
  "aliases": { "dev": "npm run dev", "build": "npm run build" },
  "env": { "NODE_ENV": "development" }
}

Merge order

Global ~/.avm.json supplies defaults. Project JSON files merge from parents to the current directory; nearer directories win for each key. Within each directory, the order is .avm.json, selected .avm.<profile>.json files in profile order, then .avm.local.json.

All child layers override all parent layers. Missing keys are inherited. A base .avm.json with root: true includes that directory and stops JSON traversal above it; global defaults still apply. It does not stop the separate searches for .env, version files or .avm.lock.

Select environment profiles

AVM_ENV selects profiles for subsequent commands and shell refreshes. The global --env option overrides it for one invocation. Later profiles win on shared keys; --env with an empty string selects no profiles. Names may contain letters, digits, underscores and hyphens.

# Bash / zsh
export AVM_ENV=ci,staging
avm which node
avm --env production run build
avm --env "" list

# PowerShell
$env:AVM_ENV = "ci,staging"

Personal overrides and edits

Put personal overrides in .avm.local.json; avm init adds that filename to .gitignore. Config-editing commands write the current directory’s base .avm.json, or ~/.avm.json with --global. They do not edit a selected profile.

Review and trust every contributing file that supplies aliases or env. Trust parent files explicitly. Use which and list to inspect the winning values and their origins.

avm --env ci trust
avm trust ../.avm.json
avm which build
avm which node
avm list

Global settings

trusted_paths and idiomatic_version_files are read from the global base ~/.avm.json only. trusted_paths grants trust to matching directories; use it only for repositories you control. Set idiomatic_version_files to false to disable tool-specific discovery such as .nvmrc and .java-version; .tool-versions remains supported.

Legacy flat alias maps are accepted and converted to the structured format on the next save. Invalid JSON causes an error and is not replaced with an empty configuration.

{
  "tools": { "node": "22" },
  "trusted_paths": ["~/work/my-project/**"],
  "idiomatic_version_files": true
}