Introduction

The ipm export command enables you to export packages from IPMHub directly to local folders without configuring them as workspaces. This is particularly useful for scenarios where you need to extract package contents for reference, inspection, or integration into non-IPM environments.

Key Benefits

  • Direct Export: Extract package files to any folder without workspace configuration
  • Version Control: Export specific versions of packages
  • Simplified Access: Get package content without creating workspace dependencies
  • Reference Material: Create local copies of packages for documentation or learning
  • Flexible Destinations: Export to empty or non-empty directories with --force
  • Audit Documentation: Generate compliance reports with --summary-file

Use Cases

The export command is designed for scenarios such as:

  • Creating reference copies of packages for documentation
  • Sharing package contents with team members who don’t use IPM
  • Inspecting package structure and files
  • Integrating package contents into other build systems
  • Creating templates based on existing packages
  • Compliance documentation and audit trail generation
  • Emergency package recovery and analysis

Using the Export Command

Basic Export

To export the latest version of a package to a local folder:

ipm export --package publisher/package-name --destination ./export-folder

Export Specific Version

To export a specific version of a package:

ipm export --package publisher/package-name --version 1.2.3 --destination ./export-folder

Force Export to Non-Empty Directory

IPM 0.10.0 introduces the --force parameter for greater operational flexibility:

ipm export --package publisher/package-name --destination ./existing-folder --force

The --force parameter allows exports into non-empty directories, providing flexibility for:

  • Integration workflows where destination folders contain other files
  • Development environments with mixed content
  • Automated processes that don’t control destination folder state
  • Rapid prototyping and experimentation scenarios

Export with Audit Reporting

Generate comprehensive audit documentation for compliance requirements:

ipm export --package publisher/package-name --destination ./export-folder --summary-file ./audit/export-report.json

Non-Interactive Export

For automated scenarios, you can use non-interactive authentication:

ipm export --package publisher/package-name --destination ./export-folder --non-interactive --client-secrets YOUR_SECRET

Complete Export with All Features

Combine all available features for maximum functionality:

ipm export --package publisher/package-name --version 1.2.3 --destination ./export-folder --force --summary-file ./audit/export-report.json --non-interactive --client-secrets YOUR_SECRET

Audit Reporting for Export Operations

Export Audit Reports

When using the --summary-file parameter, export operations generate comprehensive audit reports containing:

Package Information

  • Source package name and version
  • Publisher and metadata details
  • Authentication and authorization records
  • Download source and timing information

Destination Analysis

  • Target directory path and status
  • Pre-existing content analysis (when using --force)
  • File conflict resolution details
  • Directory creation and permission settings

Content Verification

  • Package integrity validation
  • File transfer completion status
  • Hash verification for downloaded content
  • Verification badge status (for verified packages)

Compliance Documentation

  • User authentication and authorization logs
  • Data access and export justification
  • Regulatory compliance markers
  • Audit trail timestamps and signatures

Example Export Audit Report 

{
  "operation": "export",
  "timestamp": "2025-06-08T14:48:53.195792+00:00",
  "package": {
    "name": "publisher/package-name",
    "version": "1.2.3",
    "verified": true,
    "downloadSource": "ipmhub.io"
  },
  "destination": {
    "path": "./export-folder",
    "existed": false,
    "forceUsed": false,
    "filesCreated": 23
  },
  "compliance": {
    "userAuthentication": "verified",
    "authorization": "approved",
    "dataClassification": "internal",
    "exportJustification": "development-testing"
  },
  "summary": {
    "status": "success",
    "duration": "00:00:03.456",
    "bytesTransferred": 2048576,
    "integrityVerified": true
  }
}

For comprehensive audit reporting capabilities, see the Audit Reporting guide.

Important Notes

  • The destination folder (--destination) must be empty or non-existent unless using --force
  • The --force parameter allows overwriting existing content in destination directories
  • The command will create the destination folder if it doesn’t exist
  • Exported packages contain all files from the original package
  • The export command requires authentication, similar to ipm add
  • Verified packages maintain their verification status in audit reports
  • Summary files provide complete compliance documentation

Differences Between Export and Add

While both export and add retrieve package content from IPMHub, they serve different purposes:

Feature ipm export ipm add
Creates workspace files No Yes
Adds entries to ipmhub.json No Yes
Supports any destination folder Yes No (uses workspace structure)
Supports --force parameter Yes No
Compatible with ipm sync No Yes
Package tracking No Yes
Audit reporting Yes (with --summary-file) No
Verified package support Yes (documented in reports) Yes

Enterprise Use Cases

Compliance and Governance

Export with audit reporting supports enterprise requirements:

Regulatory Compliance 

# SOX compliance export with full documentation
ipm export --package company/financial-module --version 2.1.0 \
  --destination ./compliance-review \
  --summary-file ./audit/sox-export-$(date +%Y%m%d).json

Security Reviews 

# Security assessment export with verification
ipm export --package company/security-module --destination ./security-review \
  --summary-file ./audit/security-export.json

Data Governance 

# Controlled data export with justification
ipm export --package company/data-processor --destination ./analysis \
  --force --summary-file ./audit/data-export.json

Development Workflows

Template Creation 

# Export for template development
ipm export --package templates/web-app --destination ./new-project-base --force

Integration Testing 

# Export for integration testing
ipm export --package company/api-client --version 1.0.0 \
  --destination ./test-environment/libs \
  --summary-file ./test-audit/export.json

Documentation Generation 

# Export for documentation purposes
ipm export --package company/public-api --destination ./docs/examples

Example Workflow

Here’s a common workflow for using the export command with full enterprise features:

  1. Identify the package and requirements
  2. Prepare destination and audit directories
  3. Execute export with appropriate parameters
  4. Review audit report for compliance
  5. Access exported content for intended use
# Prepare directories
mkdir -p ./exported-packages ./audit-reports

# Export with full documentation
ipm export --package publisher/my-package --version 2.0.0 \
  --destination ./exported-packages/my-package-v2 \
  --summary-file ./audit-reports/export-$(date +%Y%m%d-%H%M%S).json

# Verify export success
if [ $? -eq 0 ]; then
  echo "Export successful - reviewing audit report"
  jq '.summary.status' ./audit-reports/export-*.json
else
  echo "Export failed - check error logs"
fi

# Explore the contents
ls -la ./exported-packages/my-package-v2

Best Practices

Security and Compliance

  • Use Audit Reporting: Always use --summary-file for enterprise environments
  • Document Purpose: Include export justification in compliance workflows
  • Secure Storage: Store audit reports in secure, compliant storage systems
  • Access Control: Restrict export capabilities to authorized users only

Operational Efficiency

  • Clean Destinations: Use clean destination folders when possible
  • Version Specificity: Specify exact versions for reproducible exports
  • Automation Integration: Integrate with CI/CD pipelines for consistent exports
  • Error Handling: Implement proper error handling in automated exports

Performance Optimization

  • Network Efficiency: Consider package size for network-constrained environments
  • Parallel Processing: Use multiple export operations for bulk operations
  • Caching Strategy: Implement local caching for frequently exported packages
  • Monitoring: Monitor export performance through audit reports

Troubleshooting

Common Issues

Destination Directory Conflicts 

# Error: Directory not empty
# Solution: Use --force parameter
ipm export --package publisher/package --destination ./existing-dir --force

Authentication Failures 

# Error: Authentication required
# Solution: Use proper authentication
ipm export --package publisher/package --destination ./export --non-interactive --client-secrets YOUR_SECRET

Network Connectivity Issues 

# Error: Download failed
# Solution: Check network connectivity and retry
ipm export --package publisher/package --destination ./export --summary-file ./audit/retry-export.json

Audit Report Analysis

Review audit reports to identify and resolve issues:

# Check export status
jq '.summary.status' ./audit/export-report.json

# Review any errors
jq '.errors[]' ./audit/export-report.json

# Verify integrity checks
jq '.verification' ./audit/export-report.json