vandor vpkg

Install, remove, search, and manage VPKG packages. VPKG is Vandor's package system for adding infrastructure components -- HTTP servers, databases, caching, messaging, observability, and more -- to your project.

Synopsis

vandor vpkg <command> [args...] [flags]

Commands

add           Install a package from a source
remove        Remove an installed package
list          List installed packages
search        Search the package registry
sync          Re-apply all installed packages
info          Show detailed package information
exec          Execute a package action
exec-alias    Execute an aliased package action
doctor        Check project health and package integrity
registry      Manage package registries

vandor vpkg add

Install a VPKG package into your project.

Usage

vandor vpkg add <source> [flags]

Source Formats

You can install packages from three kinds of sources:

Official registry packages:

# Latest version
vandor vpkg add @official/http-humachi

# Specific version
vandor vpkg add @official/http-humachi@1.2.3

Git repositories:

vandor vpkg add git@github.com:someone/vandor-pkg-grpc.git
vandor vpkg add https://github.com/someone/vandor-pkg-grpc.git

Local paths (great for development):

vandor vpkg add ./my-local-package
vandor vpkg add /absolute/path/to/package

Flags

--plan                     Show what would be installed without actually installing
--yes                      Auto-confirm the installation plan
--allow-target <glob>      Allow the package to write to paths matching this glob

Examples

# Install the official HTTP package
vandor vpkg add @official/http-humachi

# Preview what an install would do
vandor vpkg add @official/entgo --plan

# Install and skip confirmation
vandor vpkg add @official/redis-cache --yes

# Allow a package to write to a custom location
vandor vpkg add @official/atlas --allow-target "database/**"

# Install from a git repo
vandor vpkg add git@github.com:myorg/custom-auth-pkg.git

# Install from local filesystem
vandor vpkg add ./packages/my-custom-pkg

Installation Flow

When you run vpkg add, here is what happens:

1. Fetch package metadata from the source
2. Resolve dependencies and check compatibility
3. Show the installation plan (files to be created/modified)
4. Ask for confirmation (unless --yes is passed)
5. Copy package files into your project
6. Update vandor-config.yaml
7. Run go mod tidy (unless --tidy never)

The --plan flag is your friend. Before installing a package for the first time, run with --plan to see exactly what files it will create and where they will go. This is especially useful for understanding how a package integrates with your project structure.

vandor vpkg remove

Remove an installed package from your project.

Usage

vandor vpkg remove <package> [flags]

Flags

--force       Remove even if other packages depend on this one

Examples

# Remove a package
vandor vpkg remove @official/redis-cache

# Force removal despite dependencies
vandor vpkg remove @official/entgo --force

What Gets Removed

Package files that were installed by vpkg add
The entry from vandor-config.yaml
Go dependencies are cleaned up via go mod tidy

Manual cleanup may be needed. If you have written code that imports or uses the package, you will need to remove those references yourself. The remove command only cleans up the package's own files.

vandor vpkg list

List packages currently installed in your project.

Usage

vandor vpkg list

Example Output

Installed packages:

  @official/http-humachi     v1.2.0   HTTP server with Chi + Huma
  @official/entgo            v1.1.0   Ent.go ORM with code generation
  @official/atlas            v1.0.0   Atlas database migrations
  @official/redis-cache      v1.0.0   Redis caching layer

Total: 4 packages

vandor vpkg search

Search the package registry for available packages.

Usage

vandor vpkg search [query] [flags]

Flags

--tier string       Filter by package tier (official, community, etc.)
--limit int         Maximum number of results (default: 20)
--offset int        Skip the first N results (for pagination)

Examples

# Search for all available packages
vandor vpkg search

# Search for HTTP-related packages
vandor vpkg search http

# Search for official packages only
vandor vpkg search --tier official

# Search for caching solutions
vandor vpkg search cache --tier official

# Paginate through results
vandor vpkg search --limit 10 --offset 10

Example Output

Search results for "http":

  @official/http-humachi   v1.2.0   HTTP server with Chi router and Huma v2    [official]
  @community/http-gin      v0.1.0   HTTP server with Gin framework             [community]
  @community/http-echo     v0.1.0   HTTP server with Echo framework            [community]

3 results found. Use 'vandor vpkg info <package>' for details.

vandor vpkg sync

Re-apply all installed packages. This is useful if package files were accidentally modified or deleted, or after upgrading Vandor itself.

Usage

vandor vpkg sync

This reads vandor-config.yaml, and for each listed package, re-applies its files to ensure they match the expected state.

Example

# After upgrading Vandor or if files got corrupted
vandor vpkg sync

vandor vpkg info

Show detailed information about a package.

Usage

vandor vpkg info <package>

Examples

vandor vpkg info @official/http-humachi

Example Output

Package: @official/http-humachi
Version: 1.2.0
Tier:    official
Source:  https://registry.vandor.dev/official/http-humachi

Description:
  Production-ready HTTP server built on Chi router and Huma v2 framework.
  Includes OpenAPI 3.1 documentation, automatic request validation,
  middleware support, and graceful shutdown.

Features:
  - RESTful API support with automatic OpenAPI docs
  - Chi router with full middleware chain
  - Request/response validation via Huma
  - Graceful shutdown handling
  - Health check endpoints

Actions:
  - add:handler       Add a new HTTP handler
  - add:middleware     Add a new middleware

Configuration (config/base.yaml):
  http:
    port: 8080
    host: localhost
    read_timeout: 30s
    write_timeout: 30s

Install:
  vandor vpkg add @official/http-humachi

vandor vpkg exec

Execute a package action. Many VPKG packages expose actions -- for example, the HTTP package lets you add handlers, and the Ent.go package lets you generate schemas.

Usage

vandor vpkg exec <package> <action> [args...]

Examples

# Add an HTTP handler via the http-humachi package
vandor vpkg exec @official/http-humachi add:handler

# Generate an Ent.go schema
vandor vpkg exec @official/entgo generate

# Run Atlas migrations
vandor vpkg exec @official/atlas migrate

# Run a custom action with arguments
vandor vpkg exec @official/asynq add:task --name SendEmail

Use vpkg info to discover actions. Each package lists its available actions in the info output. Run vandor vpkg info <package> to see what actions a package provides.

vandor vpkg exec-alias

Execute a package action using a short alias. Packages can register aliases for commonly used actions so you do not have to type the full package name every time.

Usage

vandor vpkg exec-alias <alias> [args...]

Examples

# If @official/http-humachi registers "add:handler" as an alias
vandor vpkg exec-alias add:handler

# If @official/entgo registers "entgen" as an alias
vandor vpkg exec-alias entgen

# If @official/atlas registers "migrate" as an alias
vandor vpkg exec-alias migrate up

Aliases are defined by packages and listed when you run vandor vpkg info <package>.

vandor vpkg doctor

Check the health of your VPKG packages and project configuration. Doctor scans for common issues like missing files, version mismatches, and broken dependencies.

Usage

vandor vpkg doctor [flags]

Flags

--fix       Attempt to automatically fix detected issues

Examples

# Check for issues
vandor vpkg doctor

# Check and auto-fix
vandor vpkg doctor --fix

Example Output

VPKG Doctor Report

  [OK]   @official/http-humachi v1.2.0 - all files present
  [OK]   @official/entgo v1.1.0 - all files present
  [WARN] @official/atlas v1.0.0 - missing config entry in base.yaml
  [ERR]  @official/redis-cache v1.0.0 - package files modified

Issues found: 2

Run 'vandor vpkg doctor --fix' to attempt auto-repair.

vandor vpkg registry

Manage package registries. By default, Vandor uses the official registry, but you can add custom registries for internal or community packages.

Usage

vandor vpkg registry <command>

Subcommands

add       Add a new registry
list      List configured registries
remove    Remove a registry

Examples

# List configured registries
vandor vpkg registry list

# Add a custom registry
vandor vpkg registry add --name internal --url https://vpkg.mycompany.com

# Remove a custom registry
vandor vpkg registry remove internal

Example Output

Configured registries:

  official    https://registry.vandor.dev     [default]
  internal    https://vpkg.mycompany.com

Official Packages (v0.4)

Vandor v0.4 ships with 8 official packages:

Package	Description
`@official/http-humachi`	HTTP server with Chi router and Huma v2
`@official/entgo`	Ent.go ORM with code generation
`@official/atlas`	Atlas database schema migrations
`@official/redis-cache`	Redis caching layer
`@official/asynq`	Asynq background task queue
`@official/runner-go-cron`	Go-cron based job scheduler
`@official/storage-s3`	S3-compatible object storage
`@official/observability`	OpenTelemetry observability stack

Install any of them with:

vandor vpkg add @official/<package-name>

Troubleshooting

Package not found

Error: package "@official/grpc" not found in any configured registry

Check the package name with vandor vpkg search or verify your registry configuration with vandor vpkg registry list.

Installation failed

Error: failed to download package

Check your internet connection and try again. For local packages, verify the path exists.

Dependency conflict

Error: @official/atlas requires @official/entgo

Install the required dependency first, or install both at once:

vandor vpkg add @official/entgo
vandor vpkg add @official/atlas

Files were modified

If vpkg doctor reports modified files, you can restore them:

vandor vpkg sync

vandor add - Add domain layer components
vandor sync - Regenerate wiring code
vandor run / dev - Run your application

vandor vpkg

On this page