CLI Application

The Project-Env CLI represents the raw core of Project-Env which allows the setup of tools based on a project-env.toml configuration file and therefore the integration of Project-Env into an existing environment (e.g. IDE, shell, CI).

Installation

Homebrew (macOS)
Winget (Windows)

brew install --cask project-env/tap/project-env-cli

winget install ProjectEnv.ProjectEnvCli

The binary is called project-env-cli.

Configuration file

# Directory where the tools should be installed.
# Must be located in the project directory.
tools_directory = "<path>"

[jdk]
# Distribution version according the tools index.
# See https://raw.githubusercontent.com/Project-Env/project-env-tools/main/index.json
version = "<version>"
# Distribution name according the tools index (usage of synonym possible too)
# See https://raw.githubusercontent.com/Project-Env/project-env-tools/main/index.json
distribution = "<name>"
# [optional]
# Arbitrary commands which should be executed after extracting.
post_extraction_commands = [
    "<command>",
]

[maven]
# The Maven version.
# See https://raw.githubusercontent.com/Project-Env/project-env-tools/main/index.json
version = "<version>"
# [optional]
# The project-relative path to a Maven settings file which should be used as a global settings file.
# Note that the parameter is ignored, in case the file cannot not be found.
global_settings_file = "<path>"
# [optional]
# The project-relative path to a Maven settings file which should be used as a user settings file.
# Note that the parameter is ignored, in case the file cannot not be found.
user_settings_file = "<path>"
# [optional]
# Arbitrary commands which should be executed after extracting.
post_extraction_commands = [
    "<command>",
]

[gradle]
# The Gradle version.
# See https://raw.githubusercontent.com/Project-Env/project-env-tools/main/index.json
version = "<version>"
# [optional]
# Arbitrary commands which should be executed after extracting.
post_extraction_commands = [
    "<command>",
]

[nodejs]
# The NodeJS version.
# See https://raw.githubusercontent.com/Project-Env/project-env-tools/main/index.json
version = "<version>"
# [optional]
# Arbitrary commands which should be executed after extracting.
post_extraction_commands = [
    "<command>",
]

[git]
# A directory with Git hooks which should be copied into the '.git/hooks' directory.
hooks_directory = "<path>"

[[generic]]
# [optional]
# The name of the tool.
name = "<name>"
# [optional], if 'download_urls' is configured
# The URL to download the tool from.
download_url = "<url>"
# [optional], if 'download_url' is configured
# OS specific download URL's (they have precedence over the non-OS download URL).
# Valid values for os are 'macos', 'windows' and 'linux'.
download_urls = [
    { target_os = "<os>", download_url = "<url>" },
]
# [optional]
# The main executable of the tool.
# The executable is resolved according the configured path elements.
primary_executable = "<path>"
# [optional]
# A map of environment variables, which need to be exposed.
# All values are resolved according the tool distribution root.
environment_variables = { "<key>" = "<value>" }
# [optional]
# A list of path elements, which needs to be added to the PATH variable.
# All values are resolved according the tool distribution root.
path_elements = ["<path>"]
# [optional]
# Arbitrary commands which should be executed after extracting.
post_extraction_commands = [
    "<command>",
]

Examples

See project-env.toml used for integration testing.

Usage of environment variables

If needed, environment variables can be injected by using the syntax ${<env>}.

Special case username: As the name of the environment variable containing the username is OS specific, both USERNAME and USER can be used to inject the username. If USERNAME is used, but no environment variable with that name can be found, the value of the variable USER is used. This works in the opposite direction too.

Commands

`install`

Installs the tools as configured in the project-env.toml configuration file. This is the default command — if no command is specified, install is executed.

# These are equivalent
project-env-cli
project-env-cli install

Flags

Flag	Default	Description
`--project-root`	`.`	Path to the project root directory
`--config-file`	`project-env.toml`	Path to the config file (resolved relative to `--project-root` when using the default value)
`--output-template`	(none)	Output format template: `sh`, `pwsh`, `cygwin`, or a path to a custom Pebble template
`--output-file`	(none)	Write output to a file instead of stdout
`--debug`	`false`	Activate debug output

Output formats

By default, install outputs JSON with tool info (paths, environment variables). This is what integrations like the GitHub Action consume programmatically.

For shell integration, use the --output-template flag to generate a sourceable script:

# Source directly
source <(project-env-cli install --output-template=sh)

# Or with a specific config file
source <(project-env-cli install --config-file=/path/to/project-env.toml --output-template=sh)

# Source directly
project-env-cli install --output-template=pwsh | Invoke-Expression

# Or write to file and source
project-env-cli install --output-template=pwsh --output-file=setup-env.ps1
. .\setup-env.ps1

source <(project-env-cli install --output-template=cygwin)

`upgrade`

Upgrades the tool versions in the project-env.toml configuration file either as specified with the --force-scope option or according to the version property upgrade scope flag.

# Upgrade all tools to latest (major+minor+patch)
project-env-cli upgrade --force-scope=*

# Upgrade only minor+patch versions
project-env-cli upgrade --force-scope=^

# Upgrade only patch versions
project-env-cli upgrade --force-scope=~

# Upgrade specific tools only
project-env-cli upgrade --include-tools=jdk,maven

The following upgrade scope flags are supported:

*: Upgrade tool version to latest version including major, minor and patch versions
^: Upgrade tool version to latest version including minor and patch versions
~: Upgrade tool version to latest version including patch versions

These flags can also be added as a prefix to the version property in the config file (e.g. version = "^11.0.16.1+1"). The --force-scope flag overrides per-tool prefixes.

`mcp`

Starts a Model Context Protocol server over stdio for AI assistant integration. This exposes project tool information to MCP-compatible AI tools.

project-env-cli mcp

Custom index

The PROJECT_ENV_TOOL_INDEX_V2 env var can be used to specify a custom index URL. Note that the custom index needs to follow the format of the V2 format (see index-v2.json).

Cache

All downloaded tool archives are cached, so they don’t need to be downloaded multiple times.

Windows: C:\Users\<username>\AppData\Local\Project-Env\Cache\Downloads\<archive>
macOS: /Users/<username>/Library/Caches/Project-Env/Downloads/<archive>
Linux: /home/<username>/.cache/project-env/downloads/<archive>