Nava PBC Platform CLI¶

Tooling to make installing, upgrading, and using the Nava Platform easier.

Installation¶

There are a few ways to get the tool as an end user.

uv¶

Important

Prereqs:

git 2.27+ exists on your $PATH

Install uv 0.5.8+ (released 2024-12-11) if you haven't.

Then install the tool with:

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

One-off run:

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

Other notes

uv tool upgrade nava-platform-cli

uv tool uninstall nava-platform-cli

pipx¶

Important

Prereqs:

git 2.27+ exists on your $PATH
Python 3.8+ available on your system

Install pipx if you haven't. This does require you have a working Python 3.8+ installation of some kind so pipx can run itself. Things installed via pipx will not depend on the system Python packages, though may re-use the system interpreter.

Then if you have Python 3.11+ available already, install the tool with:

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

If you don't have Python 3.11+ available

You can have pipx fetch and install an appropriate Python version for you, with the slightly longer:

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

You can now run nava-platform. See Getting Started.

If it's just a one-off operation and you don't want to install the tool to your $PATH, can use:

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

Other notes

If you want to get rid of it:

pipx uninstall nava-platform-cli

Upgrade with:

pipx upgrade nava-platform-cli

(or uninstall and install again)

Nix¶

Install nix if you haven't. This approach requires nothing else in your environment.

Note, the first time running via nix might take a while building things (as there's no project shared cache setup currently)! But subsequent runs will be faster.

You can install the tool with:

nix profile install github:navapbc/platform-cli

You can now run nava-platform. See Getting Started.

For one-off runs:

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

Other notes

Upgrade with:

nix profile upgrade platform-cli

Uninstall with:

nix profile remove platform-cli

Alternatively for one-offs, you can checkout the project locally and in the repository run:

nix run . -- <platform_cli_args>

Docker/Container¶

Install Docker if you haven't already. Note, Docker is the default for these instructions, but other container runtimes may be similar.

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

To get a Docker image, clone the repository and run:

make build

bin/docker-wrapper exists to streamline running via Docker, so you can just:

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

(it can be a little fragile, so treat gently and read about the assumptions it makes in the comments of the script)

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

(you may want to define some aliases in your shell for commons invocations like this)

Getting Started¶

After you have nava-platform installed, if you want to see the tool in action immediately, try:

nava-platform infra install ./just-a-test

Then read the docs for how to apply it to existing projects and more.

Shell Completion¶

You can install completion support for the CLI by running:

nava-platform --install-completion

Or if you want to put the config in a particular location for your shell manually, you need the output from:

nava-platform --show-completion

Development¶

Setup¶

For hacking on the tool itself, there are a couple setup options.

Standard¶

Important

Prereqs:

GNU Make (not strictly, but practically)

Install uv 0.5.8+ (released 2024-12-11) if you haven't (make setup-tooling for convenience).

Run make deps

Then you can run uv run nava-platform

Nix¶

nix develop will drop you into a shell with all dev tooling and python dependencies installed.

You can automate this with direnv.

echo "use flake" > .envrc && direnv allow

But you probably want to use nix-direnv (though there are other options, see the direnv wiki page for Nix). Which the easiest way for that is to simply have your .envrc source in the right version with something like:

if ! has nix_direnv_version || ! nix_direnv_version 3.0.6; then
  source_url "https://raw.githubusercontent.com/nix-community/nix-direnv/3.0.6/direnvrc" "sha256-RYcUJaRMf8oF5LznDrlCXbkOQrywm0HDv1VjYGaJGdM="
fi

use flake

The exact version and hash is probably out of date, refer to the upstream docs for best info.

You can then use the uv command as normal, or run tooling directly.

Process¶

The project is a standard Python project using uv for dependency management.

The Makefile has a number of useful commands, see the output of make help.

You may want to consider setting up a pre-commit hook for or just manually running make check before pushing work, as this will run useful checks.

Credits¶

Icon designed by OpenMoji – the open-source emoji and icon project. License: CC BY-SA 4.0

Built on the back of Copier.