Skip to content

Cli tools

About

One of available interfaces to use PAA capabalities is cli tools. After installing package-auto-assembler one can view the list of available cli tools like shown below.

paa --help

Usage: paa [OPTIONS] COMMAND [ARGS]...

  Package Auto Assembler CLI tool.

Options:
  --help  Show this message and exit.

Commands:
  add-mcp                      Register package MCP module in codex/claude...
  checkpoint-create            Create a package checkpoint in internal...
  checkpoint-list              List package checkpoints from internal...
  checkpoint-prune             Prune local checkpoint history.
  checkpoint-show              Show details for a specific checkpoint...
  cleanup-agent-skills         Clean PAA-managed skills from .agents/.claude...
  checkout                     Checkout package checkpoint.
  check-deps-compat            Check compatibility of declared dependency...
  check-licenses               Check licenses of the module.
  check-vulnerabilities        Check vulnerabilities of the module.
  convert-drawio-to-png        Converts drawio file to .png
  extract-module-artifacts     Extracts artifacts from packaged module.
  extract-module-mcp           Extract MCP module from packages that have it...
  extract-module-pyproject     Extracts package pyproject metadata from...
  extract-module-requirements  Extract module requirements.
  extract-module-routes        Extracts routes for fastapi from packages...
  extract-module-site          Extracts static mkdocs site from packaged...
  extract-module-streamlit     Extracts streamlit from packages that have...
  extract-skill                Extract a single skill from an installed...
  extract-skills               Extract all skills from an installed package.
  extract-tracking-version     Get latest package version.
  init-config                  Initialize config file
  init-api-config              Initialize API run config file.
  init-api                     Create API routes scaffold for a package in...
  init-cli                     Create CLI scaffold for a package in PPR.
  init-streamlit-config        Initialize Streamlit run config file.
  init-streamlit               Create Streamlit scaffold for a package in PPR.
  init-mcp-config              Initialize MCP run config file.
  init-mcp                     Create MCP module scaffold for a package in...
  init-paa                     Initialize paa tracking files and...
  init-ppr                     Initialize ppr for a given workflows...
  make-package                 Package with package-auto-assembler.
  refresh-module-artifacts     Refreshes module artifact from links.
  remove-package               Remove paa package from ppr
  rename-package               Rename paa package in ppr
  run-api-routes               Run fastapi with provided routes.
  run-mcp                      Run MCP application from package or filepath.
  run-pylint-tests             Run pylint tests for a given module, file,...
  run-streamlit                Run streamlit application from the package.
  show-module-artifacts        Shows module artifacts.
  show-module-artifacts-links  Shows module artifact links.
  show-module-info             Shows module info.
  show-module-licenses         Shows module licenses.
  show-module-list             Shows module list.
  show-module-mcp              Show MCP module availability and registered...
  show-module-requirements     Shows module requirements.
  show-ref-local-deps          Shows paths to local dependencies...
  test-install                 Test install module into local environment.
  unfold-package               Unfold paa package inside ppr
  update-release-notes         Update release notes.

Available cli tools usually employ multiple internal components and range from relatively simple ones to more complex. For interface-level guidance on package CLI module layout and imports, see interfaces/cli.md.

Description of tools

Initializing PAA

Creating config file could be useful to avoid providing parameters manually. If no config file will be provided, by default values from .paa.config will be used.

paa init-config  --help

Usage: paa init-config [OPTIONS]

  Initialize config file

Options:
  --full  If checked, dirs beyond essential would be mapped.
  --help  Show this message and exit.

MCP hosting config scaffold can be initialized separately:

paa init-mcp-config --help

Usage: paa init-mcp-config [OPTIONS]

  Initialize MCP run config file.

Options:
  --config TEXT  Path to mcp config scaffold file.  [default: .paa.mcp.config]
  --force        If checked, existing mcp config will be overwritten.
  --help         Show this message and exit.

FastAPI run config scaffold can be initialized separately:

paa init-api-config --help

Usage: paa init-api-config [OPTIONS]

  Initialize API run config file.

Options:
  --config TEXT  Path to api config scaffold file.  [default: .paa.api.config]
  --force        If checked, existing api config will be overwritten.
  --help         Show this message and exit.

API routes scaffold can be initialized separately:

paa init-api --help

Usage: paa init-api [OPTIONS] MODULE_NAME

  Create API routes scaffold for a package in PPR.

Options:
  --config TEXT  Path to config file for paa.  [default: .paa.config]
  --force        If checked, overwrite existing api routes module.
  --help         Show this message and exit.

CLI scaffold can be initialized separately:

paa init-cli --help

Usage: paa init-cli [OPTIONS] MODULE_NAME

  Create CLI scaffold for a package in PPR.

Options:
  --config TEXT  Path to config file for paa.  [default: .paa.config]
  --force        If checked, overwrite existing cli module.
  --help         Show this message and exit.

Streamlit config scaffold can be initialized separately:

paa init-streamlit-config --help

Usage: paa init-streamlit-config [OPTIONS]

  Initialize Streamlit run config file.

Options:
  --config TEXT  Path to streamlit config scaffold file.  [default:
                 .paa.streamlit.config]
  --force        If checked, existing streamlit config will be overwritten.
  --help         Show this message and exit.

Streamlit app scaffold can be initialized separately:

paa init-streamlit --help

Usage: paa init-streamlit [OPTIONS] MODULE_NAME

  Create Streamlit scaffold for a package in PPR.

Options:
  --config TEXT  Path to config file for paa.  [default: .paa.config]
  --force        If checked, overwrite existing streamlit module.
  --help         Show this message and exit.

Packaging repository needs a place to keep some tracking files. Running it first time also initializes .paa.config and the second time will create directories specified there, if not already created. 

paa init-paa  --help

Usage: paa init-paa [OPTIONS]

  Initialize paa tracking files and directores from .paa.config

Options:
  --full  If checked, dirs beyond essential would be mapped.
  --help  Show this message and exit.

init-paa runs in two steps:

  1. If .paa.config is missing, it is created first and command exits.
  2. On the next run, directories are initialized from config values, with runtime defaults used for omitted path keys.

The package provides some templates for packaging repositories. Packaging repository after some additional preparations should allow to create and publish new packages with a use of ci/cd pipeline. 

paa init-ppr --help

Usage: paa init-ppr [OPTIONS]

  Initialize ppr for a given workflows platform.

Options:
  --github  If checked, git actions template would be set up.
  --azure   If checked, azure devops pipelines template would be set up.
  --full    If checked, dirs beyond essential would be mapped.
  --help    Show this message and exit.

init-ppr requires selecting a platform (--github or --azure).

On first run with selected platform: - workflow templates are initialized (.github or .azure); - .paa.config is also initialized if missing.

To initialize directories from config after that, run either: - paa init-ppr --<selected-platform> again, or - paa init-paa.

For a full field reference of .paa.config, see: - extra_docs/package_auto_assembler/components/.paa.config.md

Creating packages

Installing packages for a test in local environments could be a useful step to make sure everything works as expected before pushing changes to publishing repo. This creates an instance of the package in local environment with default version, with a greatly simplified building process that avoids making documentation, versioning and so on.

paa test-install [OPTIONS] MODULE_NAME

Usage: paa test-install [OPTIONS] MODULE_NAME

  Test install module into local environment.

Options:
  --config TEXT                   Path to config file for paa.
  --module-filepath TEXT          Path to .py file to be packaged.
  --mapping-filepath TEXT         Path to .json file that maps import to
                                  install dependecy names.
  --cli-module-filepath TEXT      Path to .py file that contains cli logic.
  --fastapi-routes-filepath TEXT  Path to .py file that routes for fastapi.
  --dependencies-dir TEXT         Path to directory with local dependencies of
                                  the module.
  --default-version TEXT          Default version.
  --check-vulnerabilities         If checked, checks module dependencies with
                                  pip-audit for vulnerabilities.
  --skip-deps-compat-check        If checked, skips dependency compatibility
                                  check.
  --check-full-deps-compat        If checked, runs full dependency resolver
                                  compatibility check.
  --build-mkdocs                  If checked, builds mkdocs documentation.
  --check-licenses                If checked, checks module dependencies
                                  licenses.
  --keep-temp-files               If checked, setup directory won't be removed
                                  after setup is done.
  --skip-deps-install             If checked, existing dependencies from env
                                  will be reused.
  --checkpoint                    If checked, creates checkpoint before package
                                  build/install.
  --help                          Show this message and exit.

Checkpoint behavior for test-install: - Default: no checkpoint. - Use --checkpoint to store a checkpoint for the tested state. - The checkpoint version label uses effective run version (usually 0.0.0 unless overridden).

Making package based on provided parameters can be useful in ci/cd pipelines to streamline creation of packages before publishing from something that could be as simple as .py file.

paa make-package --help

Usage: paa make-package [OPTIONS] MODULE_NAME

  Package with package-auto-assembler.

Options:
  --config TEXT                   Path to config file for paa.
  --module-filepath TEXT          Path to .py file to be packaged.
  --mapping-filepath TEXT         Path to .json file that maps import to
                                  install dependecy names.
  --cli-module-filepath TEXT      Path to .py file that contains cli logic.
  --fastapi-routes-filepath TEXT  Path to .py file that routes for fastapi.
  --dependencies-dir TEXT         Path to directory with local dependencies of
                                  the module.
  --kernel-name TEXT              Kernel name.
  --python-version TEXT           Python version.
  --default-version TEXT          Default version.
  --ignore-vulnerabilities-check  If checked, does not check module
                                  dependencies with pip-audit for
                                  vulnerabilities.
  --skip-deps-compat-check        If checked, skips dependency compatibility
                                  check.
  --skip-full-deps-compat-check   If checked, skips full dependency resolver
                                  compatibility check.
  --ignore-licenses-check         If checked, does not check module licenses
                                  for unexpected ones.
  --example-notebook-path TEXT    Path to .ipynb file to be used as README.
  --execute-notebook              If checked, executes notebook before turning
                                  into README.
  --log-filepath TEXT             Path to logfile to record version change.
  --versions-filepath TEXT        Path to file where latest versions of the
                                  packages are recorded.
  --no-checkpoint                 If checked, skips checkpoint creation before
                                  package build.
  --help                          Show this message and exit.

Checkpoint behavior for make-package: - Default: checkpoint is created. - Use --no-checkpoint to skip checkpoint creation. - Packaged checkpoint history is automatically pruned to exclude 0.0.0 checkpoints.

Execution flows

The following summarizes what happens internally for the main packaging commands.

make-package flow

  1. Load .paa.config and resolve package-specific paths.
  2. Initialize PackageAutoAssembler with packaging, docs, artifacts, and validation settings.
  3. Read metadata from module/CLI and calculate version (plus release notes when enabled).
  4. Prepare setup directory and merge local dependencies.
  5. Extract requirements from module, CLI, API routes, and streamlit sources.
  6. Build docs inputs (README/extra docs/mkdocs).
  7. Create checkpoint by default (unless --no-checkpoint).
  8. Export pruned checkpoint history for packaging (drop 0.0.0 checkpoints).
  9. Collect artifacts and build package files (setup.py + distribution artifacts).

test-install flow

  1. Load .paa.config and resolve package-specific paths.
  2. Initialize PackageAutoAssembler for local build/install flow.
  3. Read metadata and assign default version.
  4. Prepare setup directory and merge local dependencies.
  5. Extract requirements from module, CLI, API routes, and streamlit sources.
  6. Optionally build mkdocs, then prepare artifacts and setup file.
  7. Optionally create checkpoint when --checkpoint is provided.
  8. Build package and install it into current environment.
  9. Remove temporary setup directory unless --keep-temp-files is set.

check-deps-compat flow

  1. Load .paa.config and resolve package paths.
  2. Initialize PackageAutoAssembler in compatibility-check mode.
  3. Prepare temporary setup directory and resolve effective requirements.
  4. Run static constraint compatibility check.
  5. Optionally run full resolver check when --full is provided.
  6. Print pass/fail status and clean temporary setup directory.

Compatibility defaults

Command Static check Full resolver check
paa make-package enabled by default enabled by default
paa test-install enabled by default disabled by default
paa check-deps-compat enabled optional (--full)

History flow

This section summarizes how checkpoint history is stored, created, packaged, and restored.

Where history lives: - Local unfolded history: .paa/history/<package>/git - Packaged history payload: .paa.tracking/git (work tree) and .paa.tracking/git_repo (git metadata)

History creation: - Manual: paa checkpoint-create <package> - Test install: paa test-install <package> --checkpoint (optional) - Make package: paa make-package <package> (default unless --no-checkpoint)

History packaging behavior: - make-package exports a pruned checkpoint history for packaged artifacts. - By default, checkpoints with version 0.0.0 are excluded from packaged history. - Local history is not modified by this packaging-time pruning. - To prune local history explicitly, use paa checkpoint-prune.

History restore and usage: - paa checkpoint-list / paa checkpoint-show read available checkpoint history from package context. - paa checkout restores selected checkpoint content. - Default checkout target is latest stable tag (vX.Y.Z); use explicit dev-latest or commit hash when needed.

History maintenance: - paa checkpoint-prune <package> defaults to pruning 0.0.0 checkpoints. - --dry-run previews prune effect. - --version <x.y.z> prunes specific version checkpoints. - --commit <sha_prefix> prunes a specific checkpoint commit.

Typical sequence:

# 1) Create local dev checkpoint(s)
paa checkpoint-create package-auto-assembler

# 2) Build package (checkpoint created by default; packaged history prunes 0.0.0)
paa make-package package-auto-assembler

# 3) Inspect history
paa checkpoint-list package-auto-assembler

# 4) Restore explicit checkpoint into unfolded files only
paa checkout package-auto-assembler dev-latest --unfold --no-install

Creating checkpoints

Use checkpoint-create for explicit/manual checkpoints.

paa checkpoint-create --help

Usage: paa checkpoint-create [OPTIONS] MODULE_NAME

  Create a package checkpoint in internal history store.

Options:
  --version-label TEXT  Version label to tag checkpoint with.  [default:
                        0.0.0]
  --source-event TEXT   Source event label recorded in checkpoint commit
                        message.  [default: manual]
  --help                Show this message and exit.

Examples:

# Manual dev checkpoint
paa checkpoint-create package-auto-assembler

# Explicit version checkpoint
paa checkpoint-create package-auto-assembler --version-label 1.2.3 --source-event release

Use checkpoint-list to navigate available checkpoints and checkpoint-show for details.

paa checkpoint-list package-auto-assembler
paa checkpoint-show package-auto-assembler dev-latest

paa checkpoint-list --help

Usage: paa checkpoint-list [OPTIONS] MODULE_NAME

  List package checkpoints from internal history store.

Options:
  --limit INTEGER  Maximum number of checkpoints to list.  [default: 20]
  --help           Show this message and exit.

Checking out previous versions

Checkout target resolution: - Default paa checkout <package> looks for latest stable tag (vX.Y.Z). - If stable tags are not present, use explicit target such as dev-latest or commit hash.

Checkout behavior: - Default checkout applies target state in a temporary workspace and runs test-install from there; unfolded files are not changed. - --unfold additionally syncs the checked-out state into unfolded package files in current workspace. - --no-install skips the reinstall step. - --unfold --no-install updates unfolded files only (no reinstall).

Checkout change summary: - written: files created in unfolded package scope. - updated: existing files overwritten to match checkpoint target. - deleted: package-scoped files removed because they are absent in checkpoint target.

Examples:

# Preview planned checkout changes
paa checkout package-auto-assembler dev-latest --dry-run --unfold --no-install

# Apply only to unfolded files (no reinstall)
paa checkout package-auto-assembler dev-latest --unfold --no-install

# Apply and reinstall from checked-out temp workspace
paa checkout package-auto-assembler dev-latest

Pruning history

Use checkpoint-prune to remove old or specific checkpoints from local history.

paa checkpoint-prune --help

Usage: paa checkpoint-prune [OPTIONS] MODULE_NAME

  Prune local checkpoint history.

Options:
  --commit TEXT   Specific checkpoint commit (or prefix) to remove.
  --version TEXT  Remove checkpoints for a specific version label.
  --dry-run       Show what would be pruned without changing history.
  --help          Show this message and exit.

Examples:

# Default prune behavior: remove checkpoints with version=0.0.0
paa checkpoint-prune package-auto-assembler

# Preview prune effect without modifying history
paa checkpoint-prune package-auto-assembler --dry-run

# Remove checkpoints for a specific version
paa checkpoint-prune package-auto-assembler --version 0.1.2

# Remove one specific checkpoint commit
paa checkpoint-prune package-auto-assembler --commit 03aa890

Working with packages within PAA

Published packages could be installed and unfolded for editing anywhere, given that they are independent of a packaging repositories and enviroment that produced them.

paa unfold-package --help

Usage: paa unfold-package [OPTIONS] MODULE_NAME

  Unfold paa package inside ppr

Options:
  --debug  If checked, debug messages will be shown.
  --help   Show this message and exit.

Since packaging repository is just a workbench, ability to remove packages that no longer being published there could be useful. 

paa remove-package --help

Usage: paa remove-package [OPTIONS] MODULE_NAME

  Remove paa package from ppr

Options:
  --debug  If checked, debug messages will be shown.
  --help   Show this message and exit.

Ability to unfold packages created with package-auto-assembler, paired with a method to rename them, would allow to fork the package and start publishing it in the same package storage, just under different name.

paa rename-package --help

Usage: paa rename-package [OPTIONS] MODULE_NAME NEW_MODULE_NAME

  Rename paa package in ppr

Options:
  --debug  If checked, debug messages will be shown.
  --help   Show this message and exit.

Checking dependencies

Checking vulnerabilities with pip-audit is usefull. This checks vulnerabilities of .py files and its local dependencies with pip-audit.

paa check-vulnerabilities --help

Usage: paa check-vulnerabilities [OPTIONS] MODULE_NAME

  Check vulnerabilities of the module.

Options:
  --config TEXT               Path to config file for paa.
  --module-filepath TEXT      Path to .py file to be packaged.
  --mapping-filepath TEXT     Path to .json file that maps import to install
                              dependecy names.
  --cli-module-filepath TEXT  Path to .py file that contains cli logic.
  --dependencies-dir TEXT     Path to directory with local dependencies of the
                              module.
  --help                      Show this message and exit.

Checking compatibility of dependency constraints can be done separately as a dedicated CLI call.

paa check-deps-compat --help

Usage: paa check-deps-compat [OPTIONS] MODULE_NAME

  Check compatibility of declared dependency constraints for the module.

Options:
  --config TEXT               Path to config file for paa.
  --module-filepath TEXT      Path to .py file to be packaged.
  --mapping-filepath TEXT     Path to .json file that maps import to install
                              dependecy names.
  --cli-module-filepath TEXT  Path to .py file that contains cli logic.
  --dependencies-dir TEXT     Path to directory with local dependencies of the
                              module.
  --full                      If checked, runs full dependency resolver
                              compatibility check.
  --help                      Show this message and exit.

Compatibility defaults by command: - paa make-package: static and full compatibility checks run by default. Use --skip-deps-compat-check and/or --skip-full-deps-compat-check to disable. - paa test-install: static compatibility check runs by default, full resolver check is off by default. Use --check-full-deps-compat to enable full resolver check.

When compatibility fields in .paa.config are omitted or set to null, command defaults above are used.

Checking license labels of module dependencies tree could be useful to prevent using some dependencies early on.

Usage: paa check-licenses [OPTIONS] MODULE_NAME

  Check licenses of the module.

Options:
  --config TEXT                   Path to config file for paa.
  --module-filepath TEXT          Path to .py file to be packaged.
  --mapping-filepath TEXT         Path to .json file that maps import to
                                  install dependecy names.
  --license-mapping-filepath TEXT
                                  Path to .json file that maps license labels
                                  to install dependecy names.
  --cli-module-filepath TEXT      Path to .py file that contains cli logic.
  --dependencies-dir TEXT         Path to directory with local dependencies of
                                  the module.
  --skip-normalize-labels         If checked, package license labels are not
                                  normalized.
  --help                          Show this message and exit.

Running apps from packages

Packaging process could help building APIs as well. This package would call routes stored within other packages and routes stored in files to form one application, so that repeatable structure does not need to copied between projects, but instead built in one places and extended with some config files in many. Since routes are python code that can have its dependencies, it makes sense to store them within packages sometimes to take advantage of automated dependency handling and import code straight from the package, eliminating in turn situation when package release in no compatible anymore with routes based on them.

Parameters for fastapi app description, middleware and run could be supplied via optional .paa.api.config file, with DESCRIPTION , MIDDLEWARE and RUN dictionary of parameters respectively.

It could be beneficial to add a static page with documentation, so additional pages could be addded. First one would be accessible via \mkdocs and the following ones via \mkdocs {i+1}. Static package within package, that were packages by package-auto-assemble>0.5.1 would be accessible via \{package_name}\docs if available.

paa run-api-routes --help

Usage: paa run-api-routes [OPTIONS]

  Run fastapi with provided routes.

Options:
  --api-config TEXT  Path to yml config file with app description, middleware
                     parameters, run parameters, `.paa.api.config` is used by
                     default.
  --host TEXT        The host to bind to.
  --port TEXT        The port to bind to.
  --package TEXT     Package names from which routes will be added to the app.
  --route TEXT       Paths to routes which will be added to the app.
  --docs TEXT        Paths to static docs site which will be added to the app.
  --help             Show this message and exit.

For detailed FastAPI interface workflows, see interfaces/fastapi.md.

One of the convinient ways to access packaged code could be a streamlit application. This package allows for streamlit application to be stored within a package and then run with the following. Parameters that would be passed to ~/.streamlit/config.toml can be provided via optional .paa.streamlit.config file, at which point it would copied to default location. The command can be used to run streamlit apps from a selected package, built with the tool, or from normal .py file with streamlit app.

paa run-streamlit --help

Usage: paa run-streamlit [OPTIONS]

  Run streamlit application from the package.

Options:
  --app-config TEXT  Path to yml config for streamlit app.
  --host TEXT        The host to bind to.
  --port TEXT        The port to bind to.
  --package TEXT     Package name from which streamlit app should be run.
  --path TEXT        Path to streamlit app.
  --help             Show this message and exit.

For detailed Streamlit interface workflows, see interfaces/streamlit.md.

MCP tools

PAA supports MCP module scaffolding, package extraction, local execution, and agent registration.

paa init-mcp --help

Usage: paa init-mcp [OPTIONS] MODULE_NAME

  Create MCP module scaffold for a package in PPR.

Options:
  --config TEXT            Path to config file for paa.
  --module-name TEXT       Module name if different from argument label.
  --mcp-module-filepath TEXT
                           Path to .py file for MCP module.
  --force                  If checked, overwrite existing MCP module.
  --help                   Show this message and exit.

paa add-mcp --help

Usage: paa add-mcp [OPTIONS] MODULE_NAME

  Register package MCP module in codex/claude client.

Options:
  --target [codex|claude]  Agent target for MCP registration.
  --python-path TEXT       Python interpreter to run MCP module with.
  --server-name TEXT       Optional MCP server name override.
  --help                   Show this message and exit.

Notes: - add-mcp registers MCP from installed package files. - If no installed MCP module is found for selected package, command fails.

Example:

paa add-mcp your-package-1 --target codex --python-path /path/to/your/python

Flag guidance: - --target is optional when auto-detection resolves a single target. - --python-path is optional if default python points to desired environment. - --server-name is optional unless you need a custom server ID in client config.

paa show-module-mcp --help

Usage: paa show-module-mcp [OPTIONS] LABEL_NAME

  Show MCP module availability and registered tool list for an installed
  package.

Options:
  --tools  If checked, inspect and show registered tool names.
  --help   Show this message and exit.

paa run-mcp --help

Usage: paa run-mcp [OPTIONS]

  Run hosted MCP application(s) from package(s) and/or filepath(s).

Options:
  --mcp-config TEXT               Path to yml config file with MCP run settings and sources.
  --package TEXT                  Package names from which MCP app should be run.
  --path TEXT                     Path(s) to MCP module file.
  --host TEXT                     Host to bind MCP server to.
  --port INTEGER                  Port to bind MCP server to.
  --transport [sse|streamable-http]
                                  Hosted MCP transport mode.
  --mount-path TEXT               Optional mount path for SSE transport.
  --mode [split|combine]          Run mode for MCP hosting.
  --server-prefix TEXT            Server name prefix. In split mode used only
                                  when explicitly provided.
  --help                          Show this message and exit.

run-mcp source selection can come from flags (--package, --path) and/or .paa.mcp.config:

RUN:
  host: "0.0.0.0"
  port: 8000
  transport: "streamable-http"
  mount_path: null
  mode: "split"
  server_prefix: null

SOURCES:
  packages:
    - your-package-1
    - your-package-2
  paths: []

Mode and naming behavior: - split (default): one server per source. - combine: one server for all sources. - In split, default naming has no prefix; prefix is applied only when explicitly provided (--server-prefix or config RUN.server_prefix). - In combine, server name defaults to paa-http unless overridden.

For detailed MCP workflows, see interfaces/mcp.md.

run-mcp flag guidance: - if .paa.mcp.config exists, command can run without explicit source flags. - --host / --port only needed for non-default bind settings. - --mode defaults to split. - in split, --server-prefix is optional and applied only when explicitly set.

paa extract-module-mcp --help

Usage: paa extract-module-mcp [OPTIONS] PACKAGE_NAME

  Extract MCP module from packages that have it into a file.

Options:
  --output-dir TEXT   Directory where MCP module extracted from the package
                      will be copied to.
  --output-path TEXT  Filepath to which MCP module extracted from the package
                      will be copied to.
  --help              Show this message and exit.

Extracting files from packages

Storing routes within package could be convinient, but extracting them from a package is not. To mitigate that, the following exists to extract routes.py from a package that contains it.

paa extract-module-routes --help

Usage: paa extract-module-routes [OPTIONS] PACKAGE_NAME

  Extracts routes for fastapi from packages that have them into a file.

Options:
  --output-dir TEXT   Directory where routes extracted from the package will
                      be copied to.
  --output-path TEXT  Filepath to which routes extracted from the package will
                      be copied to.
  --help              Show this message and exit.

paa extract-module-site --help

Usage: paa extract-module-site [OPTIONS] PACKAGE_NAME

  Extracts static mkdocs site from packaged module.

Options:
  --output-dir TEXT   Directory where routes extracted from the package will
                      be copied to.
  --output-path TEXT  Filepath to which routes extracted from the package will
                      be copied to.
  --help              Show this message and exit.

Another option to access the artifacts is to copy them to a selected directory.

paa extract-module-artifacts --help

Usage: paa extract-module-artifacts [OPTIONS] PACKAGE_NAME

  Extracts artifacts from packaged module.

Options:
  --artifact TEXT     Name of the artifact to be extracted.
  --output-dir TEXT   Directory where artifacts extracted from the package
                      will be copied to.
  --output-path TEXT  Filepath to which artifact extracted from the package
                      will be copied to.
  --help              Show this message and exit.

Another option to access the packaged streamlit app is to copy it to a selected directory.

paa extract-module-streamlit --help

Usage: paa extract-module-streamlit [OPTIONS] PACKAGE_NAME

  Extracts streamlit from packages that have them into a file.

Options:
  --output-dir TEXT   Directory where streamplit extracted from the package
                      will be copied to.
  --output-path TEXT  Filepath to which streamlit extracted from the package
                      will be copied to.
  --help              Show this message and exit.

To make package metadata directly reusable with uv/poetry, pyproject can be extracted from installed package tracking files, or generated in poetry style.

paa extract-module-pyproject --help

Usage: paa extract-module-pyproject [OPTIONS] PACKAGE_NAME

  Extracts package pyproject metadata from installed package tracking.

Options:
  --format [pep621|uv|poetry]  Output format for extracted pyproject.
                               [default: pep621]
  --output-dir TEXT            Directory where extracted pyproject will be
                               copied/generated.
  --output-path TEXT           Filepath where extracted pyproject will be
                               copied/generated.
  --help                       Show this message and exit.

By default, the command writes to ./pyproject.toml, which can be used directly by tools like uv and poetry.

paa extract-module-pyproject package_auto_assembler --format uv
paa extract-module-pyproject package_auto_assembler --format poetry --output-path ./pyproject.toml

PAA can also extract packaged agent skills.

paa extract-skill --help

Usage: paa extract-skill [OPTIONS] PACKAGE_NAME SKILL_NAME

  Extract a single skill from an installed package.

Options:
  --target [codex|claude]  Agent target for auto-detected output path.
  --output-dir TEXT        Destination skills root. If omitted, target path is
                           auto-detected.
  --help                   Show this message and exit.

paa extract-skills --help

Usage: paa extract-skills [OPTIONS] PACKAGE_NAME

  Extract all skills from an installed package.

Options:
  --target [codex|claude]  Agent target for auto-detected output path.
  --output-dir TEXT        Destination skills root. If omitted, target path is
                           auto-detected.
  --help                   Show this message and exit.

Auto-detection behavior for skill extraction: - If --output-dir is provided, it is used directly. - Otherwise PAA searches upward from the current directory and detects target roots from markers (.agents/.claude, AGENTS.md/CLAUDE.md). - If both targets are detected, provide --target or --output-dir. - If no target markers are found, PAA defaults to user-level codex path: ~/.agents/skills.

Examples:

paa extract-skill package_auto_assembler dependency-management-audit --target codex
paa extract-skills package_auto_assembler --target claude

Agent skills maintenance

Installed skills extracted by PAA include a small marker (.paa_skill_meta.yml), enabling safe cleanup of only PAA-managed entries.

paa cleanup-agent-skills --help

Usage: paa cleanup-agent-skills [OPTIONS]

  Clean PAA-managed skills from .agents/.claude skills root.

Options:
  --target [codex|claude]  Agent target for auto-detected output path.
  --output-dir TEXT        Skills root to clean. If omitted, target path is
                           auto-detected.
  --help                   Show this message and exit.

paa cleanup-agent-skills --target codex

Show modules info

Cli interface provides some additional tools to analyse locally installed packages if they were build with package-auto-assembler>0.4.2. These include methods to list modules, show module info, extract requirements.

paa show-module-list --help

Usage: paa show-module-list [OPTIONS]

  Shows module list.

Options:
  --tags TEXT  Keyword tag filters for the package.
  --help       Show this message and exit.

paa show-module-info --help

Usage: paa show-module-info [OPTIONS] LABEL_NAME

  Shows module info.

Options:
  --keywords      If checked, returns keywords for the package.
  --classifiers   If checked, returns classfiers for the package.
  --docstring     If checked, returns docstring of the package.
  --author        If checked, returns author of the package.
  --author-email  If checked, returns author email of the package.
  --version       If checked, returns installed version of the package.
  --pip-version   If checked, returns pip latest version of the package.
  --help          Show this message and exit.

paa show-module-requirements --help

Usage: paa show-module-requirements [OPTIONS] LABEL_NAME

  Shows module requirements.

Options:
  --help  Show this message and exit.

paa show-module-licenses --help

Usage: paa show-module-licenses [OPTIONS] PACKAGE_NAME

  Shows module licenses.

Options:
  --normalize-labels  If checked, package license labels are normalized.
  --help              Show this message and exit.

There is an option to package artifacts with the code. Packaged artifacts can be listed. 

paa show-module-artifacts --help

Usage: paa show-module-artifacts [OPTIONS] LABEL_NAME

  Shows module artifacts.

Options:
  --help  Show this message and exit.

It might be useful to inspect which artifacts come from links, whether these links are available and refresh these artifacts within installed package.

paa show-module-artifacts-links --help

Usage: paa show-module-artifacts-links [OPTIONS] LABEL_NAME

  Shows module artifact links.

Options:
  --help  Show this message and exit.

A module can referance multiple other local dependencies. The following is meant to extract all of paths relates to the module within PPR.

paa show-ref-local-deps --help

Usage: paa show-ref-local-deps [OPTIONS] LABEL_NAME

  Shows paths to local dependencies referenced in the module.

Options:
  --config TEXT            Path to config file for paa.
  --module-dir TEXT        Path to folder with .py file to be packaged.
  --dependencies-dir TEXT  Path to directory with local dependencies of
                           the module.
  --help                   Show this message and exit.

Other

Some artifacts can come from links and there might be a need to refresh or even download these files (depending on how a link was provided). 

paa refresh-module-artifacts --help

Usage: paa refresh-module-artifacts [OPTIONS] LABEL_NAME

  Refreshes module artifact from links.

Options:
  --help  Show this message and exit.

Core of paa automation is the ability to extract requirements from .py files. The tool shown below is a part of requirements extraction pipeline, designed to run within PPR, but could also work outside, if imports are handled in a specific way (more in description).

paa extract-module-requirements --help

Usage: paa extract-module-requirements [OPTIONS] MODULE_NAME

  Extract module requirements.

Options:
  --config TEXT                   Path to config file for paa.
  --module-dir TEXT               Path to folder where module is stored.
  --mapping-filepath TEXT         Path to .json file that maps import to
                                  install dependecy names.
  --cli-module-filepath TEXT      Path to .py file that contains cli logic.
  --routes-module-filepath TEXT   Path to .py file that contains fastapi
                                  routes.
  --streamlit-module-filepath TEXT
                                  Path to .py file that contains streamlit
                                  app.
  --dependencies-dir TEXT         Path to directory with local dependencies of
                                  the module.
  --show-extra                    If checked, list will show which
                                  requirements are extra.
  --skip-extra                    If checked, list will not include extra.
  --help                          Show this message and exit.

Maintaining release notes could be very useful, but also tedious task. Since commit messages are rather standard practice, by taking advantage of them and constructing release notes based on them, each release could contain notes with appropriate version automatically, when itegrated into ci/cd pipeline, given that commit messages are written in a specific way. 

paa update-release-notes --help

Usage: paa update-release-notes [OPTIONS] LABEL_NAME

  Update release notes.

Options:
  --version TEXT           Version of new release.
  --notes TEXT             Optional manually provided notes string, where each
                           note is separated by ; and increment type is
                           provide in accordance to paa documentation.
  --notes-filepath TEXT    Path to .md wit release notes.
  --max-search-depth TEXT  Max search depth in commit history.
  --use-pip-latest         If checked, attempts to pull latest version from
                           pip.
  --help                   Show this message and exit.

Running pylint tests is useful and usually done in pull request to PPR. It could also be run locally for all the modules or select modules and their local dependencies to identify modules that need improvements to pass preset threshold. 

paa run-pylint-tests --help

Usage: paa run-pylint-tests [OPTIONS] [FILES]...

  Run pylint tests for a given module, file, files or files in a directory.

Options:
  --config TEXT      Path to config file for paa.
  --label-name TEXT  Label name.
  --module-dir TEXT  Path to a directory where .py files are stored.
  --threshold TEXT   Pylint threshold.
  --help             Show this message and exit.

It might be useful to know what is the last version a given module that was published from the PPR, mostly within ci/cd workflows.

paa extract-tracking-version --help

Usage: paa extract-tracking-version [OPTIONS] MODULE_NAME

  Get latest package version.

Options:
  --config TEXT  Path to config file for paa.
  --help         Show this message and exit.

Some pieces of documentation within PPR may come from drawio files. One of the steps in packaging process is to convert .drawio file for a package into .png files. For this functionality to work, first some dependencies would need to be installed.

sudo apt-get update
sudo apt-get install -y wget xvfb libnotify4 libxml2-utils
wget https://github.com/jgraph/drawio-desktop/releases/download/v24.6.4/drawio-amd64-24.6.4.deb
sudo dpkg -i drawio-amd64-24.6.4.deb
sudo apt-get install -f

paa convert-drawio-to-png --help

Usage: paa convert-drawio-to-png [OPTIONS]

  Converts drawio file to .png

Options:
  --config TEXT      Path to config file for paa.
  --label-name TEXT  Label name.
  --drawio-dir TEXT  Path to a directory where drawio files are stored.
  --docs-dir TEXT    Path to the output directory for .png file.
  --help             Show this message and exit.

Before conversion, existing drawio-generated PNG files for the selected package are cleaned from docs output to remove stale tabs from removed/renamed drawio pages. Notebook-generated PNG files (for example *_cell23_out0.png) are preserved.