Open source tools for every layer of government service delivery.

Strata is a gold-standard target architecture and suite of open-source tools that gives government agencies everything they need to run a modern service.

Nava PBC Platform CLI

A command-line tool that simplifies installing, upgrading, and managing Nava Strata.

Table of Contents

• Quick Start
• Installation
  • uv (Recommended)
  • pipx
  • Nix
  • Docker/Container
• Getting Started
• Development
• Credits

---

Quick Start

Try the tool immediately after installation:

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

For detailed usage and integration with existing projects, see the documentation.

---

Installation

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

uv

Recommended for most users.

Prerequisites:

• git 2.27+ on your $PATH

Steps:

1. Install uv 0.5.8+ (released 2024-12-11)

2. Install the platform CLI:

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

One-off execution (without installing):

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

Management commands:

# Upgrade
uv tool upgrade nava-platform-cli

# Uninstall
uv tool uninstall nava-platform-cli

pipx

Good alternative if you already have Python installed.

Prerequisites:

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

Steps:

1. Install pipx if you haven't already

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

One-off execution (without installing):

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

Management commands:

# Upgrade
pipx upgrade nava-platform-cli

# Uninstall
pipx uninstall nava-platform-cli

Note: pipx requires Python 3.8+ to run itself, but installed tools are isolated from system Python packages.

Nix

For users who prefer reproducible builds and declarative environments.

Warning

Currently broken on macOS due to upstream issues

Prerequisites:

• None! Nix provides everything needed.

Steps:

1. Install Nix if you haven't already

2. Install the platform CLI:

   nix profile install github:navapbc/platform-cli

One-off execution (without installing):

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

Management commands:

# Upgrade
nix profile upgrade platform-cli

# Uninstall
nix profile remove platform-cli

For local development:

# From within the cloned repository
nix run . -- <platform_cli_args>

Note: First-time execution may take longer due to building dependencies. Subsequent runs will be faster.

Docker/Container

For containerized environments or when you want complete isolation.

Prerequisites:

• Docker (or another container runtime)

Steps:

1. Clone the repository

2. Build the Docker image:

   make build

3. Use the wrapper script for simplified execution:

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

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

Manual execution:

After building, run the container directly:

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

With volume mounting (required for most operations):

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

Tip: Consider creating shell aliases for common invocations.

---

Getting Started

Once you have nava-platform installed, you can start using it immediately.

Basic Usage

Test the installation with a simple command:

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

Documentation

For comprehensive guides on using the platform CLI with existing projects:

• Getting Started Guide
• New Project Setup
• Migrating from Legacy Template

Shell Completion

Enable tab completion for your shell:

nava-platform --install-completion

To manually configure completion, get the configuration output:

nava-platform --show-completion

---

Development

Contributing to the platform CLI? Here's how to set up your development environment.

Setup Options

Option 1: Standard Setup (Recommended)

Prerequisites:

• GNU Make

Steps:

1. Install uv 0.5.8+ (released 2024-12-11):

   # Or use: make setup-tooling

   Installation guide

2. Install dependencies:

   make deps

3. Run the CLI:

   uv run nava-platform

Option 2: Nix Development Environment

Warning

Currently broken on macOS due to upstream issues

Enter the development shell:

nix develop

Automate with direnv:

Basic setup:

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

Recommended: Use nix-direnv for better caching. Add to .envrc:

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

Note: Check the nix-direnv docs for the latest version and hash.

Development Workflow

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

Useful commands:

# See all available commands
make help

# Run quality checks
make check

Best practices:

• Run make check before pushing changes
• Consider setting up a pre-commit hook for automated checks
• See CONTRIBUTING.md for detailed contribution guidelines

Credits

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

Built with: Copier – Template project generator

---

License

This project is licensed under the Apache 2.0 License. See the LICENSE file for details.

Community

• Code of Conduct
• Contributing Guidelines
• Security Policy