Reference

Commands

IVPM (Integrated View Package Manager) - A polyglot package manager that fetches dependencies from diverse sources and assembles unified project views.

usage: ivpm [-h] [--log-level {INFO,DEBUG,WARN,NONE}]
            {activate,build,cache,clone,destroy,init,pkg-info,share,show,snapshot,status,sync,update}
            ...

Positional Arguments

{activate,build,cache,clone,destroy,init,pkg-info,share,show,snapshot,status,sync,update}: Possible choices: activate, build, cache, pkg-info, share, clone, update, init, git-status, git-update, snapshot, sync, destroy, status, show

Named Arguments

--log-level

Possible choices: INFO, DEBUG, WARN, NONE

Set the logging level (default: NONE)

Default: 'NONE'

Sub-commands

activate

Starts a new shell that contains the activated python virtual environment

ivpm activate [-h] [-c C] [-p PROJECT_DIR] [args ...]

Positional Arguments

args

Named Arguments

-c: When specified, executes the specified string
-p, --project-dir: Specifies the project directory to use (default: cwd)

build

Build all sub-projects with an IVPM-supported build infrastructure (Python)

ivpm build [-h] [-d DEP_SET] [-g]

Named Arguments

-d, --dep-set

Uses dependencies from specified dep-set instead of default

-g, --debug

Enables debug for native extensions

Default: False

cache

Manage the IVPM package cache

ivpm cache [-h] {clean,info,init} ...

Positional Arguments

{clean,info,init}: Possible choices: init, info, clean

Sub-commands

init

Initialize a new cache directory

ivpm cache init [-h] [-s] [-f] cache_dir

Positional Arguments

cache_dir: Path to the cache directory to initialize

Named Arguments

-s, --shared

Set group inheritance (chmod g+s) for shared cache usage

Default: False

-f, --force

Force reinitialization of existing directory

Default: False

info

Show cache information (packages, versions, sizes)

ivpm cache info [-h] [-c CACHE_DIR] [-v]

Named Arguments

-c, --cache-dir

Cache directory (default: $IVPM_CACHE)

-v, --verbose

Show detailed version information

Default: False

clean

Remove old cache entries

ivpm cache clean [-h] [-c CACHE_DIR] [-d DAYS] [-n]

Named Arguments

-c, --cache-dir

Cache directory (default: $IVPM_CACHE)

-d, --days

Remove entries unused for more than this many days (default: 7)

Default: 7

-n, --dry-run

List entries that would be removed without deleting anything

Default: False

pkg-info

Collect paths/files for a listed set of packages

ivpm pkg-info [-h] [-k KIND]
              {incdirs,paths,libdirs,libs,flags} pkgs [pkgs ...]

Positional Arguments

type

Possible choices: incdirs, paths, libdirs, libs, flags

Specifies what info to query

pkgs

Named Arguments

-k, --kind: Specifies qualifiers on the type of info to query

clone

Create a new workspace from a Git URL or path

ivpm clone [-h] [--ssh] [-a] [--git-auth-order GIT_AUTH_ORDER] [-b BRANCH]
           [-d DEP_SET] [--py-uv] [--py-pip] [--py-system-site-packages]
           [--no-cache] [-D VAR=VALUE]
           src [workspace_dir]

Positional Arguments

src: Source URL or path to clone
workspace_dir: Target workspace directory; defaults to basename of src

Named Arguments

--ssh

Force SSH: rewrite an https:// URL to git@host:path form before cloning

Default: False

-a, --anonymous

Force HTTPS: clone the URL as written (do not rewrite to SSH)

Default: False

--git-auth-order

Comma-separated git auth order to try (gh,ssh,https); overrides IVPM_GIT_AUTH_ORDER and site config

-b, --branch

Target branch; checks out existing or creates new

-d, --dep-set

Dependency set to use for ivpm update

--py-uv

Use ‘uv’ to manage virtual environment

Default: False

--py-pip

Use ‘pip’ to manage virtual environment

Default: False

--py-system-site-packages

Inherit system site-packages in the virtual environment (default: isolated)

Default: False

--no-cache

Disable the cache for this clone’s update; forces a null cache provider

Default: False

-D

Set variable VAR to VALUE, overriding the default in vars:

Default: []

update

Fetches packages specified in ivpm.yaml that have not already been loaded

ivpm update [-h] [-D VAR=VALUE] [-p PROJECT_DIR] [-d DEP-SET] [-j JOBS]
            [--ssh] [-a] [--git-auth-order GIT_AUTH_ORDER] [--skip-py-install]
            [--force-py-install] [--py-prerls-packages] [--py-uv] [--py-pip]
            [--py-system-site-packages] [--lock-file LOCK_FILE]
            [--from PATH-OR-URL] [--deps-dir DIR] [--deps-source PATH]
            [--trust-deps-source] [--deps-source-mode {link,copy}]
            [--no-worktree-deps-source] [--refresh-all] [--force] [--no-cache]
            [-v]

Named Arguments

-D

Set variable VAR to VALUE, overriding the default in vars:

Default: []

-p, --project-dir

Specifies the project directory to use (default: cwd)

-d, --dep-set

Uses dependencies from specified dep-set instead of default. May be repeated (or comma-separated) to install several dep-sets at once, e.g. -d default -d gui-tools

-j, --jobs

Maximum number of parallel package fetches (default: number of CPU cores)

--ssh

Force SSH: rewrite https:// git URLs to git@host:path form before cloning

Default: False

-a, --anonymous-git

Force HTTPS: clone git URLs as written (do not rewrite to SSH)

Default: False

--git-auth-order

Comma-separated git auth order to try (gh,ssh,https); overrides IVPM_GIT_AUTH_ORDER and site config

--skip-py-install, --py-skip-install

Skip installation of Python packages

Default: False

--force-py-install, --py-force-install

Forces a re-install of Python packages

Default: False

--py-prerls-packages

Enable installation of pre-release packages

Default: False

--py-uv

Use ‘uv’ to manage virtual environment

Default: False

--py-pip

Use ‘pip’ to manage virtual environment

Default: False

--py-system-site-packages

Inherit system site-packages in the virtual environment (default: isolated)

Default: False

--lock-file

Reproduce workspace from a package-lock.json file (ignores ivpm.yaml)

--from

Drive the update from an external manifest instead of the cwd ivpm.yaml; resolved deps land in the current directory. Accepts a manifest file, or a directory/URL containing ivpm.yaml (e.g. https://edapack.github.io)

--deps-dir

Directory to populate (overrides manifest ‘deps-dir’; default: packages)

--deps-source

Search PATH (a sibling deps/ dir) before the shared cache. Repeatable.

--trust-deps-source

Trust deps-source entries by name (skip lock-file verification)

Default: False

--deps-source-mode

Possible choices: link, copy

How to materialize a deps-source hit (default: link)

Default: 'link'

--no-worktree-deps-source

Disable automatic deps-source detection of the parent git worktree

Default: False

--refresh-all

Re-fetch all packages regardless of existing package-lock.json state

Default: False

--force

Suppress safety errors during refresh; implies –refresh-all

Default: False

--no-cache

Disable the cache for this update; forces a null cache provider

Default: False

-v, --verbose

Increase transcript output detail (-v: activity, -vv: subprocess lines)

Default: 0

init

Creates an initial ivpm.yaml file

ivpm init [-h] [-v VERSION] [-f] name

Positional Arguments

name

Named Arguments

-v, --version: Default: '0.0.1'
-f, --force: Default: False

git-status

Undocumented

ivpm git-status [-h] [-p PROJECT_DIR]

Named Arguments

-p, -project-dir

git-update

Undocumented

ivpm git-update [-h] [-p PROJECT_DIR]

Named Arguments

-p, -project-dir

snapshot

Creates a snapshot of required packages

ivpm snapshot [-h] [-p PROJECT_DIR] [-r] snapshot_dir

Positional Arguments

snapshot_dir: Specifies the directory where the snapshot will be created

Named Arguments

-p, -project-dir

-r, --rls-deps

Uses release deps from project root instead of dev deps

Default: False

sync

Synchronizes dependent packages with an upstream source (if available)

ivpm sync [-h] [-p PROJECT_DIR] [-n] [-j JOBS] [--no-rich] [-v]

Named Arguments

-p, --project-dir

-n, --dry-run

Fetch and report sync-ability without merging

Default: False

-j, --jobs

Number of parallel sync operations (default: CPU count)

Default: 0

--no-rich

Plain-text output without Rich formatting

Default: False

-v, --verbose

Increase transcript output detail (-v: per-package activity)

Default: 0

destroy

Remove a root project and all its imports (inverse of clone)

ivpm destroy [-h] [--deps-only] [-p PROJECT_DIR] [-n] [-f] [-y] [-j JOBS]
             [--no-rich] [-v]
             [wsdir]

Positional Arguments

wsdir: Workspace directory to remove (required unless –deps-only)

Named Arguments

--deps-only

Remove only the imports/venv; keep the root project and ivpm.yaml

Default: False

-p, --project-dir

Workspace root for –deps-only mode (default: cwd)

-n, --dry-run

Report what would be removed and the gate verdict; change nothing

Default: False

-f, --force

Delete even when packages hold local modifications or unpushed commits

Default: False

-y, --yes

Skip the interactive confirmation prompt

Default: False

-j, --jobs

Number of parallel gate/teardown operations (default: CPU count)

Default: 0

--no-rich

Plain-text output without Rich formatting

Default: False

-v, --verbose

Increase per-package detail (-v: list the blocking files/commits)

Default: 0

status

Checks the status of sub-dependencies such as git repositories

ivpm status [-h] [-p PROJECT_DIR] [-v] [--no-rich]

Named Arguments

-p, --project-dir

-v, --verbose

Show modified/untracked files (-v); also show pypi packages (-v -v)

Default: 0

--no-rich

Plain-text output without Rich formatting

Default: False

show

Introspect registered package sources, content types, and handlers

ivpm show [-h] [--schema] [--json] [--no-rich]
          {deps,handler,site-config,source,type} ...

Positional Arguments

{deps,handler,site-config,source,type}: Possible choices: source, src, type, handler, deps, site-config, config

Named Arguments

--schema

Emit a JSON Schema for ivpm.yaml covering all registered sources and types

Default: False

--json

Emit JSON instead of rich/text output

Default: False

--no-rich

Plain-text output without Rich formatting

Default: False

Sub-commands

source (src)

List registered package sources (where packages come from)

ivpm show source [-h] [--json] [--no-rich] [name]

Positional Arguments

name: Show detailed info for this source (omit to list all)

Named Arguments

--json

Emit JSON output

Default: False

--no-rich

Plain-text output

Default: False

type

List registered content types (what IVPM does with a package after fetching)

ivpm show type [-h] [--json] [--no-rich] [name]

Positional Arguments

name: Show detailed info for this type (omit to list all)

Named Arguments

--json

Emit JSON output

Default: False

--no-rich

Plain-text output

Default: False

handler

List registered package handlers (post-fetch processing hooks)

ivpm show handler [-h] [--order] [--json] [--no-rich] [name]

Positional Arguments

name: Show detailed info for this handler (omit to list all)

Named Arguments

--order

Show the resolved root-phase execution order of all handlers

Default: False

--json

Emit JSON output

Default: False

--no-rich

Plain-text output

Default: False

deps

Show project dependency tree and package information

ivpm show deps [-h] [--tree] [--json] [--no-rich] [-p PROJECT_DIR]
               [-d DEP_SET] [--dot] [-o OUTPUT] [--from PATH-OR-URL]
               [name]

Positional Arguments

name: Show full detail for this specific dependency (omit to list all)

Named Arguments

--tree, -t

Show hierarchical dependency tree instead of flat list

Default: False

--json

Emit JSON output

Default: False

--no-rich

Plain-text output without Rich formatting

Default: False

-p, --project-dir

Project root directory (default: cwd)

-d, --dep-set

Dependency set to inspect (default: project default)

--dot

Emit a Graphviz DOT graph of the dependency relationships

Default: False

-o, --output

Write output to FILE instead of stdout (useful with –dot)

--from

Browse an external manifest’s catalog (descriptions + dep-sets) without fetching dependencies. Accepts a manifest file, or a directory/URL containing ivpm.yaml (e.g. https://edapack.github.io)

site-config (config)

Show registered site configurations and the active effective settings

ivpm show site-config [-h] [--json] [--no-rich] [name]

Positional Arguments

name: Show detailed info for this site config (omit to list all)

Named Arguments

--json

Emit JSON output

Default: False

--no-rich

Plain-text output without Rich formatting

Default: False

Agent skill documentation: /home/runner/work/ivpm/ivpm/src/ivpm/share/skills/ivpm/SKILL.md

Command Details

activate

Activate the project-local Python virtual environment.

Synopsis:

ivpm activate [-c <command>] [-p <project-dir>] [args ...]

Options:

-c <command>: Execute a command in the activated environment and exit
-p, --project-dir <dir>: Specify project directory (default: current directory)
args: Arguments passed to shell or command

Examples:

# Start interactive shell
$ ivpm activate

# Run single command
$ ivpm activate -c "python script.py"
$ ivpm activate -c "pytest"

# Different project directory
$ ivpm activate -p /path/to/project -c "pytest"

Behavior:

Sources packages/python/bin/activate
Sets VIRTUAL_ENV and modifies PATH
Applies environment variables from env-sets
Without -c, starts an interactive shell
With -c, runs command and exits

build

Build Python packages with native extensions.

Synopsis:

ivpm build [-d <dep-set>] [-g|--debug]

Options:

-d, --dep-set <name>: Use dependencies from specified dep-set (default: project’s default)
-g, --debug: Enable debug symbols in native extensions

Examples:

# Build all packages
$ ivpm build

# Debug build
$ ivpm build --debug

# Specific dependency set
$ ivpm build -d default-dev

Behavior:

Finds all Python packages with native extensions
Runs python setup.py build_ext
Installs built extensions
Debug mode: sets DEBUG=1, adds -g flag

cache

Manage the IVPM package cache.

Synopsis:

ivpm cache <subcommand> [options]

Subcommands:

init: Initialize a new cache directory
info: Show cache statistics and contents
clean: Remove old cache entries

cache init

Initialize a cache directory.

Synopsis:

ivpm cache init [-s|--shared] [-f|--force] <cache_dir>

Options:

-s, --shared: Set group inheritance (chmod g+s) for shared access
-f, --force: Reinitialize existing directory

Examples:

# Personal cache
$ ivpm cache init ~/.cache/ivpm

# Shared team cache
$ sudo ivpm cache init --shared /shared/ivpm-cache
$ sudo chown :devteam /shared/ivpm-cache

cache info

Display cache information.

Synopsis:

ivpm cache info [-c|--cache-dir <dir>] [-v|--verbose]

Options:

-c, --cache-dir <dir>: Cache directory (default: $IVPM_CACHE)
-v, --verbose: Show detailed version information

Examples:

$ ivpm cache info
$ ivpm cache info --verbose
$ ivpm cache info --cache-dir /path/to/cache

cache clean

Remove old cache entries.

Synopsis:

ivpm cache clean [-c|--cache-dir <dir>] [-d|--days <n>]

Options:

-c, --cache-dir <dir>: Cache directory (default: $IVPM_CACHE)
-d, --days <n>: Remove entries older than N days (default: 7)

Examples:

$ ivpm cache clean
$ ivpm cache clean --days 30
$ ivpm cache clean --cache-dir /shared/cache --days 14

clone

Create a new workspace from a Git repository.

Synopsis:

ivpm clone [options] <src> [workspace_dir]

Arguments:

src: Git URL or local path to clone
workspace_dir: Target directory (default: basename of src)

Options:

--ssh: Force SSH: rewrite an https:// URL to git@host:path form
-a, --anonymous: Force HTTPS: clone the URL as written (do not rewrite to SSH)
--git-auth-order <list>: Comma-separated git auth order to try (gh,ssh,https); overrides IVPM_GIT_AUTH_ORDER and the config files for this invocation. See Git Integration for how the transport is selected.
-b, --branch <name>: Checkout branch; create if doesn’t exist
-d, --dep-set <name>: Dependency set for ivpm update
--py-uv: Use ‘uv’ for Python package management
--py-pip: Use ‘pip’ for Python package management
--py-system-site-packages: Inherit the base Python’s system site-packages inside the created virtual environment. By default the environment is isolated (system packages are not visible). Pass this flag only when you intentionally need access to system-installed packages (e.g. hardware-specific Python bindings that cannot be installed via pip).

Examples:

# Basic clone
$ ivpm clone https://github.com/org/project.git

# Custom directory
$ ivpm clone https://github.com/org/project.git my-workspace

# Specific branch
$ ivpm clone -b develop https://github.com/org/project.git

# Force HTTPS (as-written) clone with dep-set
$ ivpm clone -a -d default https://github.com/org/project.git

# Use uv for package management
$ ivpm clone --py-uv https://github.com/org/project.git

Behavior:

Clones Git repository
Enters directory
Automatically runs ivpm update with specified options

Note: Since clone automatically runs update, you don’t need to run ivpm update separately after ivpm clone.

destroy

Remove a root project and all its imports (the inverse of clone), or just the imports (the inverse of update). Gated against losing local work. See Destroying Workspaces for the full guide.

Synopsis:

ivpm destroy [options] [wsdir]

Arguments:

wsdir: Workspace directory to remove (required for a full destroy; ignored with --deps-only).

Options:

--deps-only: Remove only the imports/venv; keep the root project and ivpm.yaml. Runs in place; no wsdir required.
-p, --project-dir <dir>: Workspace root for --deps-only mode (default: current directory).
-n, --dry-run: Report what would be removed and the gate verdict; change nothing.
-f, --force: Delete even when packages hold local modifications or unpushed commits.
-y, --yes: Skip the interactive confirmation prompt (required in non-interactive/CI contexts).
-j, --jobs <n>: Number of parallel gate/teardown operations (default: CPU count).
--no-rich: Plain-text output without the Rich live display.
-v, --verbose: List the blocking files/commits in the report.

Examples:

# Reset the current workspace's dependencies (keep the root)
$ ivpm destroy --deps-only

# Preview a full teardown
$ ivpm destroy -n ../scratch-workspace

# Remove an entire cloned workspace, no prompt
$ ivpm destroy -y ../scratch-workspace

Behavior:

Validates the target is an IVPM workspace (refuses otherwise)
Gates every import (and, in full mode, the root) — refuses if any holds unrecoverable local work, unless --force
Removes each import via its source provider (unlinking cache/symlink deps), then the venv, lock/state, and — in full mode — the deps directory and root

init

Create a new ivpm.yaml file.

Synopsis:

ivpm init [-v|--version <ver>] [-f|--force] <name>

Arguments:

name: Package name

Options:

-v, --version <ver>: Initial version (default: 0.0.1)
-f, --force: Overwrite existing ivpm.yaml

Examples:

$ ivpm init my-project
$ ivpm init my-project -v 1.0.0
$ ivpm init my-project -f  # Overwrite existing

Output:

Creates ivpm.yaml with:

package:
  name: my-project
  version: "0.0.1"

pkg-info

Query package information (paths, libraries, flags).

Synopsis:

ivpm pkg-info <type> [-k <kind>] <packages...>

Arguments:

type: Information type: incdirs, paths, libdirs, libs, flags
packages: Package names to query

Options:

-k, --kind <kind>: Qualifier for query type

Examples:

# Get include directories
$ ivpm pkg-info incdirs my-package

# Get paths by kind
$ ivpm pkg-info paths -k rtl my-package

# Get library directories
$ ivpm pkg-info libdirs package1 package2

Use case: Integration with build systems (CMake, Make, etc.)

show

Inspect registered package sources, content types, and handlers — and view the current project’s resolved dependency graph.

Synopsis:

ivpm show [--json] [--no-rich] [--schema]
ivpm show source  [--json] [--no-rich] [<name>]
ivpm show src     [--json] [--no-rich] [<name>]   # alias for source
ivpm show type    [--json] [--no-rich] [<name>]
ivpm show handler [--json] [--no-rich] [<name>]
ivpm show site-config [--json] [--no-rich] [<name>]
ivpm show config      [--json] [--no-rich] [<name>]   # alias for site-config
ivpm show deps    [-p DIR] [-d DEP-SET] [--tree] [--json] [--no-rich] [<name>]

Sub-commands:

source / src [name]: List all registered package source types, or show full details for a specific source (e.g. ivpm show source git).
type [name]: List all registered content types (python, raw), or show full details for a specific type.
handler [name]: List all registered package handlers, or show full details for a specific handler including activation conditions and CLI options.
site-config / config [name]: List all registered site configurations (the active one is flagged) and the effective settings the active config applies – resolved cache directory, ivpm install arguments, git auth order, and the config files that were loaded. With name, show the detail for one config. See Writing Custom Handlers for how to contribute a site config and how the active one is selected.
deps [name]: Show the resolved dependency graph for the current project (or the project at -p DIR). Without name, all packages are listed as a flat table (default) or tree (--tree). With name, shows full detail for a single package. See Inspecting Dependencies (show deps) for a detailed how-to guide.

Options (show deps):

-p DIR / --project-dir DIR: Project root to inspect (default: current working directory).
-d DEP-SET / --dep-set DEP-SET: Dep-set to load from the root ivpm.yaml (default: default-dev).
--tree / -t: Show the full dependency hierarchy instead of the flat table.
--json: Emit machine-readable JSON.
--no-rich: Plain text output without terminal colours or tables.

Options (show / show source / type / handler / site-config):

--json: Emit JSON output instead of Rich/plain text. Useful for scripting.
--no-rich: Emit plain text without terminal colours or tables.
--schema: Emit a JSON Schema describing the complete registry (sources, types, handlers). Does not require a sub-command.

Examples:

# --- show deps ---

# Flat table of all resolved dependencies (default)
$ ivpm show deps --no-rich
Name      Version  Specifier  Source  URL
--------  -------  ---------  ------  ---
pyyaml    6.0.1    root       pypi
requests  2.31.0   root       pypi

# Dependency tree
$ ivpm show deps --tree --no-rich
my-project
├── pyyaml       6.0.1   (pypi)
└── requests     2.31.0  (pypi)

# Detail for a single package
$ ivpm show deps pyyaml --no-rich
Name:          pyyaml
Specifier:     root
Source:        pypi
Version:       6.0.1
Also requested by: (none)

# Machine-readable flat list
$ ivpm show deps --json | jq '.[].name'

# --- show (registry) ---

# Overview — show all registries at once
$ ivpm show --no-rich

# List registered source types
$ ivpm show source --no-rich

# List content types as JSON
$ ivpm show type --json

# Full detail for the Python handler
$ ivpm show handler python --no-rich

# List registered site configs + the active effective settings
$ ivpm show site-config --no-rich

# Dump complete registry schema
$ ivpm show --schema

Use case: ivpm show deps answers “what is actually installed and who asked for it?” — handy for auditing transitive dependencies, understanding ownership conflicts, and integrating with downstream tooling via JSON output. The other show sub-commands discover what sources, types, and handlers are active in the current environment, including any third-party extensions.

snapshot

Create a self-contained snapshot of the project.

Synopsis:

ivpm snapshot [-p <project-dir>] [-r|--rls-deps] <snapshot_dir>

Arguments:

snapshot_dir: Output directory for snapshot

Options:

-p, -project-dir <dir>: Project directory (default: current)
-r, --rls-deps: Use release deps (default) instead of dev deps

Examples:

$ ivpm snapshot /tmp/my-snapshot
$ ivpm snapshot --rls-deps /tmp/release-snapshot
$ ivpm snapshot -p /path/to/project /tmp/snapshot

Output:

Creates directory with:

Project source
All dependency sources
python_pkgs.txt (list of Python packages)
Updated ivpm.yaml with exact versions

Use case: Archival, reproducible builds, offline distribution

status

Check status of Git dependencies.

Synopsis:

ivpm status

Examples:

$ ivpm status

Output:

For each Git package:

Package name
Current branch
Modified files
Untracked files
Commits ahead/behind remote

Use case: See which dependencies have uncommitted changes.

sync

Synchronize Git dependencies with upstream.

Synopsis:

ivpm sync

Examples:

$ ivpm sync

Behavior:

For each Git package on a branch:

git fetch origin
git merge origin/<branch>

Skips:

Packages on tags (immutable)
Packages on specific commits (immutable)
Packages with uncommitted changes (safety)

After sync completes, packages/package-lock.json is updated to reflect the new commit hashes of all synced packages. See Package Lock File.

update

Fetch dependencies and initialize environment.

Synopsis:

ivpm update [options]

Options:

-p, --project-dir <dir>: Project directory (default: current)
-d, --dep-set <name>: Use specified dependency set
-j, --jobs <n>: Parallel package fetches (default: CPU count)
--ssh: Force SSH: rewrite https:// git URLs to git@host:path form
-a, --anonymous-git: Force HTTPS: clone git URLs as written (do not rewrite to SSH)
--git-auth-order <list>: Comma-separated git auth order to try (gh,ssh,https); overrides IVPM_GIT_AUTH_ORDER and the config files for this invocation.
--skip-py-install: Skip Python package installation
--force-py-install: Force Python package reinstallation
--py-prerls-packages: Allow pre-release Python packages
--py-uv: Use ‘uv’ for package management
--py-pip: Use ‘pip’ for package management
--py-system-site-packages: Inherit the base Python’s system site-packages inside the created virtual environment. By default the environment is isolated (system packages are not visible). Pass this flag only when you intentionally need access to system-installed packages.
--lock-file <path>: Reproduce workspace from a package-lock.json file. ivpm.yaml is not read for packages; the lock file supplies the complete package list at pinned resolved versions. See Package Lock File.
--from <path-or-url>: Drive the update from an external manifest — a local path, a file:// URL, or an http(s):// URL — instead of the cwd ivpm.yaml. Resolved dependencies land in the current directory (under the deps directory). The external manifest is not copied locally; instead the resolved package-lock.json records a source_manifest pointing back at it (see Package Lock File). It is an error to use --from when the target directory already has its own ivpm.yaml (a workspace has exactly one driving manifest), or together with --lock-file. Remote (URL) manifests may not use include:. Combine with -d to pick a dependency set.
--deps-dir <dir>: Directory to populate, overriding the manifest’s deps-dir (default: packages). Useful with --from to place an external manifest’s resolved workspace under a chosen name without editing the upstream manifest.
--refresh-all: Re-fetch all packages regardless of the existing package-lock.json state. Use when you want to pull upstream changes without changing ivpm.yaml specs.
--force: Suppress safety errors during refresh (e.g. uncommitted local changes) and implies --refresh-all.

# Basic update
$ ivpm update

# Specific dependency set
$ ivpm update -d default

# Force HTTPS (as-written) git clones
$ ivpm update -a

# Parallel downloads
$ ivpm update -j 8

# Skip Python install
$ ivpm update --skip-py-install

# Force Python reinstall
$ ivpm update --force-py-install

# Reproduce exact workspace from a committed lock file
$ ivpm update --lock-file ./ivpm.lock

# Install a dependency set from a published catalog into the cwd
$ ivpm update --from https://example.com/acme/ivpm.yaml -d gui-tools

# Place the resolved workspace under a chosen directory
$ ivpm update --from ./catalog.yaml --deps-dir vendor

# Re-fetch all packages (pull upstream changes)
$ ivpm update --refresh-all

Behavior:

Read ivpm.yaml (or --lock-file if provided)
Select dependency set
Fetch missing dependencies (skip up-to-date packages per lock file)
Resolve sub-dependencies recursively
Create Python virtual environment (if needed)
Install Python packages
Write/update packages/package-lock.json

Global Options

These options apply to all commands:

--version, -V: Print the IVPM version and exit.
--log-level <level>: Set logging level: INFO, DEBUG, WARN, NONE (default)

Examples:

$ ivpm --log-level DEBUG update
$ ivpm --log-level INFO status

Environment Variables

IVPM_CACHE

Path to the package cache directory.

export IVPM_CACHE=~/.cache/ivpm

Used by caching system. See Caching.

IVPM_PROJECT

Set automatically by IVPM to project root directory.

Available in env-sets as ${IVPM_PROJECT}.

IVPM_PACKAGES

Set automatically by IVPM to packages directory.

Available in env-sets as ${IVPM_PACKAGES}.

GITHUB_TOKEN

GitHub API token for higher rate limits.

export GITHUB_TOKEN=ghp_your_token_here

Useful for GitHub Releases and API queries.

YAML File Format

JSON Schema

vars

Optional mapping of variable names to default values. Variables can be referenced as ${{name}} in any scalar value elsewhere in the file. Override from the command line with -Dname=value.

package:
  name: my-project
  vars:
    wacfg: default
    cl:    7716052
  dep-sets:
    - name: default
      deps:
        - name: my_env
          src: cbwa
          wacfg: ${wacfg}

See Variables for full details.

IVPM provides a JSON Schema for ivpm.yaml files that enables IDE autocompletion and validation. To use it, add a $schema reference at the top of your file:

$schema: https://fvutils.github.io/ivpm/ivpm.schema.json

package:
  name: my-project
  version: "0.1.0"

The schema is available at:

Primary: https://fvutils.github.io/ivpm/ivpm.schema.json
Legacy (backwards compatibility): https://fvutils.github.io/ivpm/ivpm.json

Most modern editors (VS Code, IntelliJ, Vim with LSP) will automatically provide validation and autocompletion when the $schema field is present.

Package Definition

type	object
properties
name	Name of the package
	type	string
description	One-line summary of what this package/catalog offers
	type	string
version	Version of the package
	type	string
include	Paths (relative to this file) of partial ivpm.yaml files to merge into this package. The including file wins on conflict; dep-sets merge by name (a name defined in two files is an error).
	type	array
	items	type	string
deps-dir	Directory where dependencies are stored (default: ‘packages’)
	type	string
default-dep-set	Default dependency set to use if not specified on command line. If not set, uses the first dep-set in the file
	type	string
dep-sets	List of named dependency sets
	type	array
	items	Named package-dependency set
setup-deps	Setup-time dependencies that must be installed before other packages
	type	array
	items	type	string
paths	Path specifications organized by kind and type
	Organize project paths for tools to discover (e.g., rtl/vlog, dv/sv)
	type	object
	additionalProperties	type	object
		additionalProperties	type	array
			items	type	string
env-sets	Environment variable sets
	type	array
	items	Environment variable set

Dependency Set

Named package-dependency set

type	object
properties
name	Dependency-set identifier. Common names include ‘default’ and ‘default-dev’
	type	string
description	One-line summary of what this dependency set installs
	type	string
kind	Optional classification for catalog views (‘ivpm show deps –from’). ‘package’ is a single installable tool; ‘collection’ is a curated multi-tool bundle. Inferred from dep count / dotted name / ‘uses’ when omitted.
	type	string
	enum	package, collection
uses	Name (or list of names) of other dep-set(s) in this file to use as a base. Non-overlapping packages are inherited; later bases override earlier ones, and packages defined in this dep-set override those from the bases.
	type	string / array
	items	type	string
default-dep-set	Default dep-set name for sub-packages to inherit if not explicitly specified
	type	string
deps	Package dependencies
	type	array
	items	Package Dependency specification

Package Dependency

Package Dependency specification

type	object
properties
required	[‘name’]
name	Package identifier
	type	string
url	URL from which to obtain the dependency. Used for all execpt ‘pypi’
	type	string
src	Specifies the source type. Built-in types are listed below; custom (plugin-provided) source types are also accepted
	type	string
	anyOf	URL points to a Git repository
		const	git
		URL points to an HTTP/HTTPS resource
		const	http
		URL points to a local file (file://path)
		const	file
		URL points to a local directory (file://path)
		const	dir
		URL points to a .jar file. IVPM will not expand
		const	jar
		URL points to a gzip-compressed TAR file. IVPM will expand
		const	tgz
		URL points to a xz-compressed TAR File. IVPM will expand
		const	txz
		URL points to a zip file. IVPM will expand
		const	zip
		Dependency name is a PyPi package to be installed with pip
		const	pypi
		GitHub Release - downloads platform-specific binaries or source from releases
		const	gh-rls
		Environment Module – resolves a module specifier to its modulefile directory
		const	module
		Dep-set factory – pulls the named ‘dep-set’ from a referenced ivpm.yaml (via ‘url’). Contributes deps only; no packages-dir entry.
		const	ivpm.yaml
		Custom (plugin-provided) source type
		type	string
type	Specifies package type. Most of the time auto-detect works
	type	string
	oneOf	Data package. IVPM will not attempt to interpret
		const	raw
		Python package that IVPM will install into the venv
		const	python
		Environment Module – emit module load and/or resolve root directory for handler discovery
		const	module
version	Version-specification string for Python packages from PyPi or GitHub Releases
	type	string
ssh	Force SSH: rewrite the https URL to git@host:path form (overrides the auth order)
	type	boolean
anonymous	anonymous:true clones the https URL as written; anonymous:false defers to the auth order (legacy; use ssh:true to force SSH)
	type	boolean
branch	Git branch to checkout
	type	string
tag	Git tag to checkout
	type	string
commit	Git commit to checkout
	type	string
deps	When set to ‘skip’, sub-dependencies will not be loaded
	type	string
	enum	skip
depth	Git clone depth (number of commits to fetch)
	type	integer
dep-set	Named dep-set(s) to pull from the target IVPM package: a single name, or a list of names to merge (later overrides earlier).
	type	string / array
	items	type	string
cache	Enable caching for this package. true=cached+readonly, false=readonly no cache, unspecified=full history+editable
	type	boolean
link	For ‘dir’ source type: use symlink (true) or copy (false). Default: true
	type	boolean
unpack	For archive files: whether to unpack the archive. Default: true (false for .jar)
	type	boolean
file	For GitHub Releases: specific asset filename to download
	type	string
prerelease	For GitHub Releases: include pre-release versions when selecting. Default: false
	type	boolean
source	For GitHub Releases: force fetching source archive (.tar.gz) instead of platform-specific binary. Default: false
	type	boolean
with	Type-specific parameters. Only valid when ‘type’ is also specified. Parameter names and values are validated at runtime by the content-type handler.
	type	object
module	Module specifier (e.g. gcc/15.2.0). Required when src is module
	type	string
root	Explicit root directory override for src: module
	type	string
resolve-root	Opt-in: parse module show output to determine the install prefix
	type	boolean
	default	False

Environment Set

Environment variable set

type	object
properties
name	Environment set identifier
	type	string
env	List of environment variable specifications
	type	array
	items	Environment variable specification

Environment Specification

Environment variable specification

type	object
properties
name	Environment variable name
	type	string
value	Set the variable to this value (space-separated if array)
	oneOf	type	string
		type	array
		items	type	string
path	Set the variable as a path (colon-separated if array)
	oneOf	type	string
		type	array
		items	type	string
path-append	Append to the variable as a path
	oneOf	type	string
		type	array
		items	type	string
path-prepend	Prepend to the variable as a path
	oneOf	type	string
		type	array
		items	type	string

Common Patterns

Pattern 1: Multi-Environment Project

package:
  name: versatile-project
  default-dep-set: default-dev

  dep-sets:
    - name: default
      deps:
        - name: runtime-lib
          url: https://github.com/org/runtime.git
          tag: v1.0
          cache: true

    - name: default-dev
      deps:
        - name: runtime-lib
          url: https://github.com/org/runtime.git
        - name: pytest
          src: pypi
        - name: coverage
          src: pypi

    - name: ci
      deps:
        - name: runtime-lib
          url: https://github.com/org/runtime.git
          tag: v1.0
          cache: true
          anonymous: true
        - name: pytest
          src: pypi

Pattern 2: Monorepo Structure

package:
  name: monorepo

  dep-sets:
    - name: default-dev
      deps:
        # Shared libraries
        - name: common-lib
          url: file://${IVPM_PROJECT}/../common-lib
          src: dir

        # External deps
        - name: requests
          src: pypi

Pattern 3: Platform-Specific Dependencies

package:
  name: cross-platform

  dep-sets:
    - name: default-dev
      deps:
        - name: common-tool
          url: https://github.com/org/tool
          src: gh-rls
          cache: true

        - name: pytest
          src: pypi

The gh-rls automatically selects platform-specific binaries.

Reference

Commands

Positional Arguments

Named Arguments

Sub-commands

activate

Positional Arguments

Named Arguments

build

Named Arguments

cache

Positional Arguments

Sub-commands

init

Positional Arguments

Named Arguments

info

Named Arguments

clean

Named Arguments

pkg-info

Positional Arguments

Named Arguments

share

Positional Arguments

clone

Positional Arguments

Named Arguments

update

Named Arguments

init

Positional Arguments

Named Arguments

git-status

Named Arguments

git-update

Named Arguments

snapshot

Positional Arguments

Named Arguments

sync

Named Arguments

destroy

Positional Arguments

Named Arguments

status

Named Arguments

show

Positional Arguments

Named Arguments

Sub-commands

source (src)

Positional Arguments

Named Arguments

type

Positional Arguments

Named Arguments

handler

Positional Arguments

Named Arguments

deps

Positional Arguments

Named Arguments

site-config (config)

Positional Arguments

Named Arguments

Command Details

activate

build

cache

cache init

cache info

cache clean

clone

destroy

init

pkg-info

share

show

snapshot