Installing the CLI

Installation methods

Choose one of the following installation methods based on your preferences and environment.

uv

Prerequisites

• git 2.27+ exists on your $PATH

1. Install uv 0.6.15+ (released 2025-04-21) if you haven't already.

2. Install the platform CLI:

   uv tool install git+https://github.com/navapbc/platform-cli
   

3. Done. Can now use nava-platform directly as in the docs.

For one-off executions:

uvx --from git+https://github.com/navapbc/platform-cli -- <platform_cli_args>

Management commands

Updating:

uv tool upgrade nava-platform-cli

Uninstalling:

uv tool uninstall nava-platform-cli

Nix

Prerequisites

None! Nix provides everything needed.

1. Install Nix if you haven't already.

2. Install the platform CLI:

   nix profile add github:navapbc/platform-cli
   

3. Done. Can now use nava-platform directly as in the docs.

For one-off executions:

nix run github:navapbc/platform-cli -- <platform_cli_args>

Management commands

Updating:

nix profile upgrade platform-cli

Uninstalling:

nix profile remove platform-cli

pipx

Prerequisites

• git 2.27+ exists on your $PATH
• Python 3.11+ available on your system

1. Install pipx if you haven't already
   • Note, pipx requires Python 3.10+ to run itself, but installed tools are isolated from system Python packages.

2. Install the platform CLI:

   pipx install git+https://github.com/navapbc/platform-cli
   

   Don't have Python 3.11+? Let pipx fetch it for you:

   pipx install --fetch-missing-python --python 3.12 git+https://github.com/navapbc/platform-cli
   

3. Done. Can now use nava-platform directly as in the docs.

For one-off executions:

pipx run --spec git+https://github.com/navapbc/platform-cli nava-platform <platform_cli_args>

Management commands

Updating:

pipx upgrade nava-platform-cli

Uninstalling:

pipx uninstall nava-platform-cli

Container

Prerequisites

• Docker (or another container runtime)

Container images are not currently published, so you'll need to build it yourself.

1. Clone the repository

2. Build the container image:

   make build
   

3. Instead of using a nava-platform command directly, use the wrapper script for simplified execution:

   ./bin/docker-wrapper infra install ./my_project_directory
   

   (or create an alias in your shell like alias nava-platform = <path_to_checkout>/bin/docker-wrapper)

Warning

The docker-wrapper script makes assumptions about your environment. Review the script comments before use.

Running manually

After building, you will have a nava-platform-cli image locally available that you can run like:

docker run --rm -it nava-platform-cli

For pretty much anything useful, you will need to mount the relevant locations from your host system into the container. For example if running the tool in the directory of your target project:

docker run --rm -it -v "$(pwd):/project-dir" nava-platform-cli infra install /project-dir

Shell autocompletion

Enable tab completion for your shell:

nava-platform --install-completion

To manually configure completion, get the configuration output:

nava-platform --show-completion