Configuration

pantry can be configured using a configuration file or through command-line options. This guide explains all available configuration options and how to use them.

Configuration File

pantry looks for configuration in these locations (in order of precedence):

1. pantry.config.ts or pantry.config.js in the current directory
2. _/.pantryrc or /.config/pantry/config.json in your home directory

Example configuration file (pantry.config.ts):

import type { PantryConfig } from 'ts-pantry'
import os from 'node:os'
import path from 'node:path'

const config: PantryConfig = {
  // Enable verbose logging (default: false)
  verbose: true,

  // Path where binaries should be installed
  // (default: /usr/local if writable, ~/.local otherwise)
  installationPath: '/usr/local',

  // Password for sudo operations, loaded from .env SUDO_PASSWORD (default: '')
  sudoPassword: '',

  // Whether to enable dev-aware installations (default: true)
  devAware: true,

  // Max installation retries on failure (default: 3)
  maxRetries: 3,

  // Timeout for pkgx operations in milliseconds (default: 60000)
  timeout: 60000,

  // Whether to symlink versions (default: true)
  symlinkVersions: true,

  // Whether to force reinstall if already installed (default: false)
  forceReinstall: false,

  // Update behavior configuration
  // Whether to check for updates on package operations (default: true)
  checkUpdates: true,

  // Whether to prompt before updating packages (default: true)
  promptBeforeUpdate: true,

  // Default path for shims (default: ~/.local/bin)
  shimPath: path.join(os.homedir(), '.local', 'bin'),

  // Whether to automatically add shim path to the system PATH (default: true)
  autoAddToPath: true,

  // Shell Environment Message Configuration
  // Whether to show shell environment activation messages (default: true)
  showShellMessages: true,

  // Custom message to show when environment is activated
  // Use {path} placeholder to include the project path (default: "✅ Environment activated for {path}")
  shellActivationMessage: '✅ Environment activated for {path}',

  // Custom message to show when environment is deactivated (default: "Environment deactivated")
  shellDeactivationMessage: 'Environment deactivated',

  // Service Management Configuration
  services: {
    // Enable service management functionality (default: true)
    enabled: true,

    // Default services data directory (default: ~/.local/share/pantry/services)
    dataDir: path.join(os.homedir(), '.local', 'share', 'pantry', 'services'),

    // Default services log directory (default: ~/.local/share/pantry/logs)
    logDir: path.join(os.homedir(), '.local', 'share', 'pantry', 'logs'),

    // Default services configuration directory (default: ~/.local/share/pantry/services/config)
    configDir: path.join(os.homedir(), '.local', 'share', 'pantry', 'services', 'config'),

    // Auto-restart failed services (default: true)
    autoRestart: true,

    // Service startup timeout in seconds (default: 30)
    startupTimeout: 30,

    // Service shutdown timeout in seconds (default: 10)
    shutdownTimeout: 10,

    // Database configuration for services
    database: {
      // Default database username (default: 'root')
      username: 'root',

      // Default database password (default: 'password')
      password: 'password',

      // Database authentication method for local connections (default: 'trust')
      authMethod: 'trust', // 'trust' | 'md5' | 'scram-sha-256'
    },
  },
}

export default config

JavaScript format (.pantryrc):

{
  "verbose": true,
  "installationPath": "/usr/local",
  "sudoPassword": "",
  "devAware": true,
  "maxRetries": 3,
  "timeout": 60000,
  "symlinkVersions": true,
  "forceReinstall": false,
  "checkUpdates": true,
  "promptBeforeUpdate": true,
  "shimPath": "~/.local/bin",
  "autoAddToPath": true,
  "showShellMessages": true,
  "shellActivationMessage": "✅ Environment activated for {path}",
  "shellDeactivationMessage": "Environment deactivated",
  "services": {
    "enabled": true,
    "dataDir": "~/.local/share/pantry/services",
    "logDir": "~/.local/share/pantry/logs",
    "configDir": "~/.local/share/pantry/services/config",
    "autoRestart": true,
    "startupTimeout": 30,
    "shutdownTimeout": 10,
    "database": {
      "username": "root",
      "password": "password",
      "authMethod": "trust"
    }
  }
}

Database Configuration

pantry provides configurable database credentials for all database services. This allows you to customize authentication while maintaining secure defaults.

Configuration Options

Database credentials can be configured through environment variables or configuration files:

Environment Variables

# Database username (default: 'root')
export pantry_DB_USERNAME="myuser"

# Database password (default: 'password')
export pantry_DB_PASSWORD="mypassword"

# Database authentication method (default: 'trust')
export pantry_DB_AUTH_METHOD="md5"  # 'trust' | 'md5' | 'scram-sha-256'

Configuration File

// pantry.config.ts
const config: PantryConfig = {
  services: {
    database: {
      username: 'myuser',
      password: 'mypassword',
      authMethod: 'md5'  // 'trust' | 'md5' | 'scram-sha-256'
    }
  }
}

Supported Services

These database configurations apply to:

• PostgreSQL - Uses all three options (username, password, authMethod)
• MySQL - Uses username and password
• Other databases - Future database services will adopt these standards

Authentication Methods (PostgreSQL)

Template Variables

Services use these configurable template variables:

• {dbUsername} - Resolves to configured username
• {dbPassword} - Resolves to configured password
• {authMethod} - Resolves to configured auth method
• {projectDatabase} - Resolves to project name

Examples

Development Setup (Default)

# Uses: username=root, password=password, authMethod=trust
pantry start postgres

Custom Development Setup

export pantry_DB_USERNAME="dev_user"
export pantry_DB_PASSWORD="dev_password"
pantry start postgres

Production-like Setup

export pantry_DB_AUTH_METHOD="md5"
export pantry_DB_PASSWORD="secure_password123"
pantry start postgres

Security Considerations

1. Development: Default trust auth is suitable for local development
2. Production: Use md5 or scram-sha-256 with strong passwords
3. Environment Variables: Store sensitive credentials in .env files
4. Version Control: Never commit passwords in configuration files

Dependency File Configuration

pantry supports flexible dependency configuration with global installation options:

Basic Dependency Format

# dependencies.yaml
dependencies:

  - node@22
  - python@3.12

env:
  NODE_ENV: development

Global Installation Configuration

Control whether packages are installed globally or locally with the global flag:

Individual Package Global Flags

# dependencies.yaml
dependencies:
  node@22:
    version: 22.1.0
    global: true # Install to /usr/local
  python@3.12:
    version: 3.12.1
    global: false # Install to project directory
# String format defaults to local installation

  - typescript@5.0

Top-Level Global Flag

Apply global installation to all dependencies:

# dependencies.yaml
global: true # All packages install globally unless overridden
dependencies:

  - node@22
  - python@3.12
  - bun@1.2.3

  typescript@5.0:
    version: 5.0.4
    global: false # Override: install locally for this project

Global Flag Precedence

The precedence order for global installation flags:

1. Individual package global flag (highest priority)
2. Top-level global flag
3. Default behavior (project-local installation)

# Example showing precedence
global: true # Top-level: install globally
dependencies:

  - node@22 # Uses top-level: global=true
  - python@3.12 # Uses top-level: global=true

  bun@1.2.3:
    version: 1.2.3
    global: false # Override: local installation
  typescript@5.0:
    version: 5.0.4 # Uses top-level: global=true

Installation Behavior

• Global packages (global: true): Installed to /usr/local (or user-configured global path)
• Local packages (global: false or default): Installed to project-specific directories
• Mixed installations: You can have both global and local packages in the same project

Global Dependencies and Cleanup

When using the pantry clean command, you can preserve global dependencies to avoid accidentally removing essential system tools:

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

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

Global dependency detection:

• Any dependency file (deps.yaml, dependencies.yaml, etc.) with global: true

Example global dependency file (~/.dotfiles/deps.yaml):

global: true
dependencies:
  bun.sh: ^1.2.16
  gnu.org/bash: ^5.2.37
  gnu.org/grep: ^3.12.0
  starship.rs: ^1.23.0
  cli.github.com: ^2.73.0

This ensures that essential tools like shells, package managers, and system utilities are preserved during cleanup operations, preventing system breakage.

Service Management in dependencies.yaml

Define services that should automatically start for your project:

# deps.yaml
dependencies:
  bun: ^1.2.19
  node: ^22.17.0
  php: ^8.4.11
  composer: ^2.8.10
  postgres: ^17.2.0
  redis: ^8.0.4

services:
  enabled: true
  autoStart:

    - postgres
    - redis

Behavior:

• enabled: toggles service management for the project.
• autoStart: array of service names (or group names) to start automatically on environment activation. Each service's health check is polled after startup to ensure readiness.
• Service names must match those in the Supported Services list (e.g. postgres, redis, nginx). Group names (db, monitoring, queue, web) are also accepted.

Custom Services

Define project-specific services in the custom: section:

services:
  enabled: true
  autoStart:

    - postgres
    - my-worker

  custom:
    my-worker:
      command: "node worker.js"
      port: 3001
      healthCheck: "curl -sf http://localhost:3001/health"
      workingDirectory: "."

Custom service fields:

Custom services in autoStart are started and health-checked just like built-in services.

Service Groups

Define named groups of services to start/stop together:

services:
  enabled: true
  autoStart:

    - backend

  groups:
    backend:

      - postgres
      - redis
      - my-worker

    frontend:

      - nginx

Four built-in groups are available without configuration: db, monitoring, queue, web. See Service Groups for details.

Inference shorthand

You can enable a shorthand for framework-based projects (e.g., Laravel) to infer services automatically:

# deps.yaml
dependencies:
  php: ^8.4.11
  postgres: ^17.2.0
  redis: ^8.0.4

services:
  infer: true

When enabled and a Laravel app is detected (artisan present), pantry will read .env and infer services:

• DB_CONNECTION=pgsql → postgres
• DB_CONNECTION=mysql|mariadb → mysql
• CACHEDRIVER=redis or CACHESTORE=redis → redis
• CACHEDRIVER=memcached or CACHESTORE=memcached → memcached

Environment toggles:

• pantryFRAMEWORKSENABLED (default: true)
• pantrySERVICESINFER (default: true)
• pantryLARAVELENABLED (default: true)

Configuration Options

General Options

Installation Behavior

Authentication & Security

Shell Environment Messages

Path Management

Service Management

Post-Setup Commands

Configure commands to run after the environment is prepared (independent of services):

// pantry.config.ts
import type { PantryConfig } from 'ts-pantry'

const config: PantryConfig = {
  postSetup: {
    enabled: true,
    commands: [
      {
        name: 'migrate',
        command: 'php artisan migrate',
        description: 'Run database migrations',
        condition: 'hasUnrunMigrations',
        runInBackground: false,
        required: false,
      },
    ],
  },
}

export default config

Lifecycle Hooks (preSetup, preActivation, postActivation)

In addition to postSetup, pantry provides three more lifecycle hooks for fine-grained control:

• preSetup: runs before any installation/services start
• preActivation: runs after installs/services, just before activation
• postActivation: runs immediately after activation completes

You can configure them in pantry.config.ts or inline in your dependency file (e.g., deps.yaml).

Config file example:

// pantry.config.ts
import type { PantryConfig } from 'ts-pantry'

const config: PantryConfig = {
  preSetup: {
    enabled: true,
    commands: [
      { command: "bash -lc 'echo preSetup'" },
    ],
  },
  preActivation: {
    enabled: true,
    commands: [
      { command: "bash -lc 'echo preActivation'" },
    ],
  },
  postActivation: {
    enabled: true,
    commands: [
      { command: "bash -lc 'echo postActivation'" },
    ],
  },
}

export default config

Dependency file example (inline hooks):

# deps.yaml
preSetup:
  enabled: true
  commands:

    - { command: "bash -lc 'echo preSetup'" }

postSetup:
  enabled: true
  commands:

    - { command: "bash -lc 'echo postSetup'" }

preActivation:
  enabled: true
  commands:

    - { command: "bash -lc 'echo preActivation'" }

postActivation:
  enabled: true
  commands:

    - { command: "bash -lc 'echo postActivation'" }

Notes:

• Inline hooks in deps.yaml run alongside config hooks of the same phase.
• preSetup runs before dependency installation and service auto-start.
• preActivation runs after installation/services and before printing the activation message.
• postActivation runs after the final activation message.

Environment Variables

You can also configure pantry using environment variables:

Example:

PANTRY_VERBOSE=true pantry_INSTALL_PATH=~/apps pantry install node@22

## Environment Activation Model

When you cd into a project directory that contains a dependency file (e.g. `deps.yaml`, `dependencies.yaml`, `pkgx.yml`, `pantry.yml`, `package.json`, `pyproject.toml`), pantry computes:

- A project hash based on the physical path
- A dependency fingerprint based on the content of the dependency file (md5)

The target environment directory is derived as:

~/.local/share/pantry/envs/-dhash>

This guarantees that editing dependency versions switches to a distinct environment on the next `cd`, ensuring the correct tools are active immediately.

To inspect selection and cache behavior, enable verbose logging:

```bash

export PANTRY_VERBOSE=true # or set in .env
cd my-project

# 🔍 Env target: env_dir=… dep_file=… dep_hash=…

# 🔍 Cache check: dep=… dep_mtime=… cache_mtime=… fp_match=yes|no

# 🔁 Cache invalid: dependency newer than cache

# 🔁 Cache invalid: fingerprint mismatch

# Environment variable

export pantry_SHOW_ENV_MESSAGES=false

# Or in configuration file

{
  "showShellMessages": false
}

# Environment variable with path placeholder

export pantry_SHELL_ACTIVATION_MESSAGE="🚀 Project environment loaded: {path}"

# Or in configuration file

{
  "shellActivationMessage": "🚀 Project environment loaded: {path}"
}

# Environment variable

export pantry_SHELL_DEACTIVATION_MESSAGE="🔒 Project environment closed"

# Or in configuration file

{
  "shellDeactivationMessage": "🔒 Project environment closed"
}

{
  "showShellMessages": true,
  "shellActivationMessage": "🔧 Development environment ready for {path}",
  "shellDeactivationMessage": "👋 Development environment closed"
}

{
  "showShellMessages": true,
  "shellActivationMessage": "📁 Switched to project: {path}",
  "shellDeactivationMessage": "🏠 Returned to global environment"
}

{
  "showShellMessages": true,
  "shellActivationMessage": "[ENV] {path}",
  "shellDeactivationMessage": "[ENV] deactivated"
}

# Override installation path

pantry install --path ~/custom-path node@22

# Force reinstallation

pantry shim --force node

# Disable auto PATH modification

pantry bootstrap --no-auto-path

# Install specific Bun version

pantry bun --version 1.0.0

# Bootstrap with custom options

pantry bootstrap --skip-bun --verbose

# Remove packages with dry-run preview

pantry remove python --dry-run

# Complete removal without confirmation

pantry uninstall --force

# Update packages with options

pantry update --dry-run
pantry upgrade bun --latest

# Generate environment script with options

pantry dev:dump --verbose --dryrun

# Quiet installation

pantry install --quiet node@22

import type { PantryConfig, pantryOptions } from 'ts-pantry'

// Full configuration
const config: PantryConfig = {
  verbose: true,
  installationPath: '/usr/local',
  // ... all other required properties
}

// Partial configuration (useful for runtime overrides)
const options: pantryOptions = {
  verbose: true,
  force: true,
}

# Check your current configuration

pantry --verbose install --dry-run node

# This will show the resolved configuration values