vandor new
Create a new Vandor project
vandor new
Create a new Vandor project with a clean, minimal structure ready for you to build on.
Synopsis
vandor new <name> --module <module> [flags]Description
The new command scaffolds a brand new Vandor project. It creates the directory structure, sets up go.mod with your module path, generates configuration files, and optionally runs go mod tidy to fetch dependencies.
This command is non-interactive by default. You provide the project name as a positional argument and the Go module path via --module. If you prefer a guided experience, add -it for interactive mode.
In Vandor v0.4, there are no wizards, presets, or template selections. Every project starts with the same clean base -- just a logger and configuration. You build up from there using vandor add and vandor vpkg.
Flags
Required
<name> Project name (positional argument)
--module string Go module path (e.g., github.com/myorg/my-project)Optional
--tidy auto|always|never When to run go mod tidy (default: auto)
--output text|json Output format (default: text)
--interactive, -it Enable interactive mode with prompts
--yes Auto-confirm all prompts
--no-input Fail if any required value is missingThe --tidy Flag
The --tidy flag controls when go mod tidy runs after project creation:
- auto (default): Runs
go mod tidyonly when it seems necessary (e.g., dependencies were added). - always: Always runs
go mod tidy, regardless of whether it appears needed. - never: Skips
go mod tidyentirely. Useful if you want to handle dependency management yourself or are in a CI environment with cached modules.
Examples
Basic project creation
The most common usage -- provide a name and module path:
vandor new my-api --module github.com/myorg/my-apiThis creates a my-api/ directory in your current working directory with the full project scaffold.
Interactive mode
If you are not sure what to provide, use interactive mode and the CLI will prompt you:
vandor new my-api -itThe CLI will ask for any missing required values like the module path.
Skip go mod tidy
For faster creation in CI or when you want manual control:
vandor new my-api --module github.com/myorg/my-api --tidy neverJSON output
Useful for scripting and automation:
vandor new my-api --module github.com/myorg/my-api --output jsonSpecifying output directory
The project is always created as a subdirectory with the name you provide. Run the command from wherever you want the project to live:
cd ~/projects
vandor new order-service --module github.com/myorg/order-service
# Creates ~/projects/order-service/What Gets Created
After running vandor new, you get a clean project structure:
my-api/
cmd/
app/
main.go Application entry point (app runner)
worker/
main.go Worker entry point (worker runner)
internal/
context/ Bounded contexts (empty, add with vandor add context)
core/
contexts_gen.go Aggregate context wiring (generated)
modules_gen.go Aggregate module wiring (generated)
pkg/
logger/ Structured logging
config/ Configuration loading
config/
base.yaml Base configuration
runner/
app.yaml App runner config
worker.yaml Worker runner config
vandor-config.yaml Vandor project configuration
go.mod Go module file
go.sum
.gitignoreThe base project includes only a logger and configuration. There is no HTTP server, no database, no cache -- nothing beyond the bare essentials. You add infrastructure through VPKG packages (vandor vpkg add @official/http-humachi, etc.), which keeps your project lean and gives you full control over what goes in.
Project Configuration
After creation, vandor-config.yaml looks like this:
project:
name: my-api
module: github.com/myorg/my-api
vpkg:
installed: []What to Do Next
Once your project is created, you will typically:
# Navigate into the project
cd my-api
# Add your first bounded context
vandor add context order
# Add a domain to that context
vandor add domain order Order
# Add a use case
vandor add usecase order CreateOrder
# Install an HTTP server package
vandor vpkg add @official/http-humachi
# Start developing with hot reload
vandor dev:appTroubleshooting
"module flag is required"
You must provide --module unless you are in interactive mode:
# This will fail:
vandor new my-api
# This works:
vandor new my-api --module github.com/myorg/my-api
# Or use interactive mode:
vandor new my-api -itDirectory already exists
If a directory with the same name already exists, vandor new will refuse to overwrite it:
Error: directory "my-api" already existsChoose a different name or remove the existing directory first.
Go not installed
Vandor requires Go to be installed and available in your PATH:
# Check Go installation
go versionRelated Commands
- vandor add - Add contexts, domains, and other components
- vandor vpkg - Install infrastructure packages
- vandor sync - Regenerate wiring code
- vandor dev:app - Start developing with hot reload