plano/cli

plano CLI - Local Development

This guide will walk you through setting up the plano CLI for local development using uv.

Install uv

First, install the uv package manager. This is required for managing dependencies and running the development version of planoai.

On macOS and Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

On Windows:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Setup

1. Install dependencies

   In the cli directory, run:

   uv sync
   

   This will create a virtual environment in .venv and install all dependencies from pyproject.toml.

2. Install the CLI tool globally (optional)

   To install planoai as a global tool on your system:

   uv tool install --editable .
   

   This installs planoai globally in editable mode, allowing you to run planoai commands from anywhere while still using the source code from this directory. Any changes you make to the code will be reflected immediately.

3. Run plano commands

   Use uv run to execute plano commands with the development version:

   uv run planoai build
   

   Or, if you installed globally with uv tool install .:

   planoai build
   

   Note: uv run automatically uses the virtual environment - no activation needed.

Development Workflow

Build plano:

uv run planoai build

View logs:

uv run planoai logs --follow

Run other plano commands:

uv run planoai <command> [options]

CI: Keep CLI templates and demos in sync

The CLI templates in cli/planoai/templates/ are the source of truth for mapped demo config.yaml files.

Use the sync utility to write mapped demo configs from templates:

uv run python -m planoai.template_sync

Optional: Manual Virtual Environment Activation

While uv run handles the virtual environment automatically, you can activate it manually if needed:

source .venv/bin/activate
planoai build  # No need for 'uv run' when activated

Note: For end-user installation instructions, see the Plano documentation.