Basic Usage

Service Management

pantry provides comprehensive service management for development services like databases, web servers, and infrastructure tools. See the Service Management documentation for complete details.

Quick Service Examples

# Start a database
pantry start postgres

# Start a service group (all databases)
pantry start db

# Check service status
pantry status postgres

# View service logs
pantry logs postgres --follow

# List all services
pantry services

# Stop services
pantry stop postgres redis

Available Services

pantry includes 68 pre-configured services:

Databases (22): PostgreSQL, MySQL, MariaDB, MongoDB, Redis, Valkey, KeyDB, DragonflyDB, Elasticsearch, OpenSearch, InfluxDB, CockroachDB, Neo4j, ClickHouse, Memcached, CouchDB, Cassandra, SurrealDB, Typesense, FerretDB, TiDB, ScyllaDB

Web Servers (3): Nginx, Caddy, Apache httpd

Search (3): Meilisearch, Apache Solr, Apache Zookeeper

Message Queues (6): Kafka, RabbitMQ, Apache Pulsar, NATS, Mosquitto, Redpanda

Monitoring (6): Prometheus, Grafana, Jaeger, Loki, Alertmanager, VictoriaMetrics

Proxy & Load Balancers (4): Traefik, HAProxy, Varnish, Envoy

Infrastructure (7): Vault, Consul, Nomad, etcd, MinIO, SonarQube, Temporal

Dev & CI/CD (6): Jenkins, LocalStack, Verdaccio, Gitea, Mailpit, Ollama

API & Backend (2): Hasura, Keycloak

Application Servers (2): PHP-FPM, PocketBase

DNS & Network (3): dnsmasq, CoreDNS, Unbound

Tunnels & Secrets (2): Cloudflared, Doppler

Other: Syncthing, Tor

Each service includes:

• Per-service health checks for readiness detection
• Log viewing (pantry logs )
• Cross-platform support (macOS/Linux)
• Service groups for batch operations (db, monitoring, queue, web)
• Custom service definitions in deps.yaml

Environment Management

pantry provides comprehensive tools for managing development environments with human-readable identifiers.

Listing Environments

View all your development environments:

# List all environments in a table format
pantry env:list

# Show detailed information including hashes
pantry env:list --verbose

# Output as JSON for scripting
pantry env:list --format json

# Simple format for quick overview
pantry env:list --format simple

Example Output:

📦 Development Environments:

│ Project         │ Packages │ Binaries │ Size     │ Created      │
├───────────────────────────────────────────────────────────────┤
│ final-project   │ 2        │ 2        │ 5.0M     │ 5/30/2025    │
│ working-test    │ 3        │ 20       │ 324M     │ 5/30/2025    │
│ dummy           │ 1        │ 1        │ 1.1M     │ 5/30/2025    │
└───────────────────────────────────────────────────────────────┘

Total: 3 environment(s)

Inspecting Environments

Get detailed information about a specific environment:

# Basic inspection
pantry env:inspect working-test_208a31ec

# Detailed inspection with directory structure
pantry env:inspect final-project_7db6cf06 --verbose

# Show binary stub contents
pantry env:inspect dummy_6d7cf1d6 --show-stubs

Cleaning Up Environments

Automatically clean up unused or failed environments:

# Preview what would be cleaned
pantry env:clean --dry-run

# Clean environments older than 30 days (default)
pantry env:clean

# Clean environments older than 7 days
pantry env:clean --older-than 7

# Force cleanup without confirmation
pantry env:clean --force

# Verbose cleanup with details
pantry env:clean --verbose

Removing Specific Environments

Remove individual environments by their hash:

# Remove with confirmation
pantry env:remove dummy_6d7cf1d6

# Force removal without confirmation
pantry env:remove minimal_3a5dc15d --force

# Verbose removal showing details
pantry env:remove working-test_208a31ec --verbose

Environment Hash Format

pantry uses human-readable hash identifiers for environments:

Format: {project-name}_{8-char-hex-hash}

Examples:

• final-project_7db6cf06 - Environment for "final-project"
• working-test_208a31ec - Environment for "working-test"
• my-app_1a2b3c4d - Environment for "my-app"

Updating Dependencies

Updating Dependencies

To update dependencies in your project, edit your dependency file (e.g. deps.yaml / dependencies.yaml) and then reactivate the environment:

# Edit your dependency file
# Change: node@22 -> node@23 (or bun.sh: 1.2.19 -> 1.2.20)

# Reactivate the environment (new env_dir is selected automatically)
cd .. && cd my-project

# Optional: inspect selection decisions
export PANTRY_VERBOSE=true
cd my-project
# 🔍 Env target: env_dir=… dep_file=… dep_hash=…
# 🔍 Cache check: dep=… dep_mtime=… cache_mtime=… fp_match=yes|no

Bootstrap Setup

For first-time setup or fresh installations, use the bootstrap command:

Quick Setup

Get everything you need with one command:

# Install all essential tools (defaults to /usr/local if writable, ~/.local otherwise)
pantry bootstrap

# Verbose bootstrap showing all operations
pantry bootstrap --verbose

# Force reinstall everything
pantry bootstrap --force

Customized Bootstrap

Control what gets installed:

# Skip specific components
pantry bootstrap --skip-shell-integration

# Custom installation path (override default /usr/local)
pantry bootstrap --path ~/.local

# Disable automatic PATH modification
pantry bootstrap --no-auto-path

Cache Management

pantry caches downloaded packages to improve performance. Use these commands to manage cache storage:

View Cache Statistics

Check cache size and usage information:

# Show cache statistics
pantry cache:stats

# Example output
# 📊 Cache Statistics
#
# 📦 Cached Packages: 5
# 💾 Total Size: 142.3 MB
# 📅 Oldest Access: 12/15/2024
# 📅 Newest Access: 12/28/2024

Clean Old Cache Entries

Remove old cached packages based on age or size:

# Clean packages older than 30 days (default)
pantry cache:clean

# Clean packages older than 7 days
pantry cache:clean --max-age 7

# Clean if cache exceeds 2GB
pantry cache:clean --max-size 2

# Preview what would be cleaned
pantry cache:clean --dry-run

# Clean with custom criteria
pantry cache:clean --max-age 14 --max-size 1

Clear All Cache

Remove all cached packages and downloads:

# Preview what would be cleared
pantry cache:clear --dry-run

# Clear cache with confirmation
pantry cache:clear

# Clear cache without confirmation
pantry cache:clear --force

# Clear with verbose output
pantry cache:clear --verbose --force

Note: You can also use cache:clean as an alias for cache:clear.

Complete System Cleanup

Remove all pantry-installed packages, environments, and optionally cache:

# Preview complete cleanup
pantry clean --dry-run

# Complete cleanup (removes everything)
pantry clean --force

# Clean packages but keep cache for faster reinstalls
pantry clean --keep-cache --force

# Clean but preserve global dependencies
pantry clean --keep-global --force

# Clean with verbose output
pantry clean --verbose --force

# Combine options for selective cleanup
pantry clean --keep-global --keep-cache --force

The clean command removes:

• All installed packages and their metadata
• Project-specific environments
• Cache directory (unless --keep-cache is used)
• Binary stubs and symlinks

Preserving Global Dependencies

Use the --keep-global option to preserve essential global dependencies defined in your global deps.yaml files:

# Safe cleanup that preserves global tools
pantry clean --keep-global --force

# Preview what would be preserved
pantry clean --keep-global --dry-run

Global dependency detection: pantry automatically detects any dependency file (deps.yaml, dependencies.yaml, etc.) with global: true

Global dependency formats:

# Top-level global flag (all dependencies are global)
global: true
dependencies:
  bun.sh: ^1.2.16
  gnu.org/bash: ^5.2.37
  starship.rs: ^1.23.0

# Individual package global flags
dependencies:
  bun.sh:
    version: ^1.2.16
    global: true
  python.org:
    version: ^3.11.0
    global: false  # Will be removed during cleanup

This prevents accidental removal of essential system tools like shells, package managers, and other critical utilities that you rely on globally.

Complete System Cleanup

For complete removal of pantry and all installed packages:

# Remove everything with confirmation
pantry uninstall

# Preview what would be removed
pantry uninstall --dry-run

# Remove everything without prompts
pantry uninstall --force

# Remove only packages but keep shell integration
pantry uninstall --keep-packages

The uninstall command removes:

• All installed packages and their files
• Installation directories (bin/, sbin/, pkgs/)
• Shell integration from .zshrc, .bashrc, etc.
• Shim directories
• Project-specific environment directories
• Provides guidance for manual PATH cleanup

Creating Shims

Shims are lightweight executable scripts that point to the actual binaries. They allow you to run commands without having to modify your PATH for each package:

# Create shims for a package
pantry shim node

# Create shims with a custom path
pantry shim --path ~/bin typescript

# Create shims without auto-adding to PATH
pantry shim node --no-auto-path

Bootstrap Setup

Bootstrap your development environment with everything you need:

# Bootstrap essential tools and environment
pantry bootstrap

# Force reinstall components
pantry bootstrap --force

# Install to specific path
pantry bootstrap --path ~/bin

Installing Bun

pantry provides a dedicated command for installing Bun directly from GitHub releases:

# Install latest Bun version
pantry bun

# Install specific version
pantry bun --version 1.0.0

# Specify installation path
pantry bun --path ~/bin

The bun command automatically detects your platform, downloads the appropriate binary, and adds it to your PATH.

Installing Zsh

pantry provides a dedicated command for installing the Zsh shell:

# Install zsh
pantry zsh

# Force reinstall
pantry zsh --force

# Specify installation path
pantry zsh --path ~/bin

After installation, pantry provides instructions for making zsh your default shell:

# Make zsh your default shell
chsh -s /path/to/installed/zsh

Commit Publishing

Publish packages directly from git commits without version bumps. This is pantry's built-in alternative to pkg-pr-new, enabling continuous releases tied to commits.

Publishing from a Commit

# Publish all packages matching a glob pattern
pantry publish:commit './packages/_'

# Publish a single package directory
pantry publish:commit ./my-package

# Preview what would be published
pantry publish:commit './packages/_' --dry-run

# Use a custom registry
pantry publish:commit './packages/_' --registry https://registry.example.com

# Compact output (useful in CI)
pantry publish:commit './packages/_' --compact

How It Works

1. pantry reads the current git commit SHA
2. Resolves glob patterns to find package directories
3. Reads each package.json, skipping private packages
4. Creates tarballs and uploads them to the Pantry registry
5. Stores metadata in DynamoDB for lookup by commit or package name
6. Prints install URLs for each published package

Install URLs

Each published package gets an install URL tied to the commit SHA:

# Install a commit package
npm install https://registry.pantry.dev/commits/abc1234/@scope/my-package/tarball

CI/CD Usage

Replace pkg-pr-new in your GitHub Actions:

# Before

- run: bunx pkg-pr-new publish './packages/_'

# After

- run: pantry publish:commit './packages/_'

Options

Checking for Updates

Keep your packages up-to-date:

# Check for outdated packages
pantry outdated

# Update all packages to latest versions
pantry update

# Update specific packages
pantry update node python

Listing Installed Packages

View what packages are currently installed:

# List all installed packages
pantry list

Common Options

Most commands support these options:

Package Management Best Practices

Understanding Installation Philosophy

pantry follows a clean package management approach (similar to pkgm):

• Never uses Homebrew directories (/opt/homebrew)
• Prefers ~/.local for user-specific installations (safest approach)
• Falls back to /usr/local for system-wide installations when explicitly requested
• Maintains clean separation from other package managers

Using Environment Isolation

pantry automatically provides environment isolation for each project:

# Each project gets its own environment
cd project-a/    # → Uses node@20, python@3.11
cd ../project-b/ # → Uses node@22, python@3.12

Choosing Between Remove and Uninstall

• Use remove when you want to uninstall specific packages while keeping your pantry setup
• Use uninstall when you want to completely remove pantry and start fresh

Using Dry-Run Mode

Always preview major changes before executing them:

# Preview package removal
pantry remove python --dry-run

# Preview complete system cleanup
pantry uninstall --dry-run

# Preview environment setup
pantry dev:dump --dryrun

Version Management

Remove specific versions while keeping others:

# List installed packages to see versions
pantry list

# Remove only a specific version
pantry remove node@20

# Keep node@22 installed

Using PATH Integration

By default, pantry automatically adds shim directories to your PATH. You can disable this behavior:

pantry shim node --no-auto-path

Working with Dependencies

Dependency File Formats

pantry supports multiple dependency file formats:

# dependencies.yaml
dependencies:

  - node@22
  - python@3.12

env:
  NODE_ENV: development
  API_URL: https://api.example.com

Environment Variables

Set project-specific environment variables:

dependencies:

  - node@22

env:
  NODE_ENV: production
  DATABASE_URL: postgresql://localhost/myapp
  API_KEY: your-api-key-here

Complex Dependencies

Handle complex package specifications:

dependencies:

  - gnu.org/wget@^1.21
  - curl.se@~8.0
  - python.org@>=3.11

env:
  PATH_EXTENSION: /custom/bin
  PYTHON_PATH: /opt/custom/python

Getting Help

For detailed information about any command:

pantry help
pantry <command> --help

Troubleshooting

Environment Not Activating

If automatic environment activation isn't working:

1. Ensure shell integration is set up:

`bash

echo 'eval "$(pantry dev:shellcode)"' >> ~/.zshrc

source ~/.zshrc

`

1. Check for dependency files in your project directory
2. Verify the dependency file syntax is correct

Package Installation Failures

If packages fail to install:

1. Check your internet connection
2. Verify the package name and version exist
3. Try with verbose output: pantry install --verbose package-name
4. Check if you have write permissions to the installation directory

Permission Issues

If you encounter permission errors:

1. pantry will automatically prompt for sudo when installing to /usr/local
2. Install to user directory: --path ~/.local
3. Check directory permissions

Shell Integration Issues

If shell integration isn't working:

1. Verify your shell is supported (bash or zsh)
2. Check that the shell integration code was added correctly
3. Reload your shell configuration
4. Try generating new shell code: pantry dev:shellcode
5. Check if shell messages are disabled: echo $pantrySHOWENV_MESSAGES

Shell Message Issues

If you're not seeing environment messages:

1. Check if messages are disabled:

`bash

echo $pantrySHOWENV_MESSAGES

`

1. Re-enable messages:

`bash

export pantrySHOWENV_MESSAGES=true

`

1. Check your configuration file for showShellMessages: false