Module install

agpm_cli::cli

Module install 

Source
Expand description

Install Claude Code resources from manifest dependencies.

This module provides the install command which reads dependencies from the agpm.toml manifest file, resolves them, and installs the resource files to the project directory. The command supports both fresh installations and updates to existing installations with advanced parallel processing capabilities.

§Features

  • Dependency Resolution: Resolves all dependencies defined in the manifest
  • Transitive Dependencies: Automatically discovers and installs dependencies declared in resource files
  • Lockfile Management: Generates and maintains agpm.lock for reproducible builds
  • Worktree-Based Parallel Installation: Uses Git worktrees for safe concurrent resource installation
  • Multi-Phase Progress Tracking: Shows detailed progress with phase transitions and real-time updates
  • Resource Validation: Validates markdown files and content during installation
  • Cache Support: Advanced cache with instance-level optimizations and worktree management
  • Concurrency Control: User-configurable parallelism via --max-parallel flag
  • Cycle Detection: Prevents circular dependency loops in transitive dependency graphs

§Examples

Install all dependencies from manifest:

agpm install

Force reinstall all dependencies:

agpm install --force

Install without creating lockfile:

agpm install --no-lock

Use frozen lockfile (CI/production):

agpm install --frozen

Disable cache and clone fresh:

agpm install --no-cache

Install only direct dependencies (skip transitive):

agpm install --no-transitive

Preview installation without making changes:

agpm install --dry-run

§Installation Process

  1. Manifest Loading: Reads agpm.toml to understand dependencies
  2. Source Synchronization: Clones/fetches Git repositories for all sources
  3. Dependency Resolution: Resolves versions and creates dependency graph
  4. Transitive Discovery: Extracts dependencies from resource files (YAML/JSON metadata)
  5. Cycle Detection: Validates dependency graph for circular references
  6. Worktree Preparation: Pre-creates Git worktrees for optimal parallel access
  7. Parallel Resource Installation: Installs resources concurrently using isolated worktrees
  8. Progress Coordination: Updates multi-phase progress tracking throughout installation
  9. Configuration Updates: Updates hooks and MCP server configurations as needed
  10. Lockfile Generation: Creates or updates agpm.lock with checksums and metadata
  11. Artifact Cleanup: Removes old artifacts from removed or relocated dependencies

§Error Conditions

  • No manifest file found in project
  • Invalid manifest syntax or structure
  • Dependency resolution conflicts
  • Circular dependency loops detected
  • Invalid transitive dependency metadata (malformed YAML/JSON)
  • Network or Git access issues
  • File system permissions or disk space issues
  • Invalid resource file format

§Performance

The install command is optimized for maximum performance:

  • Worktree-based parallelism: Each dependency gets its own isolated Git worktree
  • Instance-level caching: Optimized worktree reuse within command execution
  • Configurable concurrency: --max-parallel flag controls dependency-level parallelism
  • Pre-warming strategy: Creates all needed worktrees upfront for optimal parallel access
  • Atomic file operations: Safe, corruption-resistant file installation
  • Multi-phase progress: Real-time progress updates with phase transitions

Structs§

InstallCommand
Command to install Claude Code resources from manifest dependencies.