New - 💧 Mizu

The mizu new command creates a new Mizu project by generating files from a template. Think of templates as starter kits - each one sets up a complete project structure so you can start coding right away instead of creating files manually.

Basic Usage

mizu new [path] --template <template-name>

Arguments:

[path] - Where to create the project (optional, defaults to current directory)
--template - Which template to use (required)

Quick Examples

# Create a minimal project in current directory
mizu new . --template minimal

# Create an API project in a new folder
mizu new myapi --template api

# Create a web app with a custom module name
mizu new webapp --template web --module github.com/myname/webapp

# Preview what will be created (without creating anything)
mizu new myapp --template api --dry-run

Understanding the Command

When you run mizu new myapp --template api, here’s what happens:

Creates the directory - A new folder called myapp is created
Generates files - Template files are copied with your project name filled in
Sets up Go module - The go.mod file is created with the correct module path
Reports success - Shows you what was created

Example output:

Created myapp from template api
  5 directories, 12 files

Next steps:
  cd myapp
  go mod tidy
  mizu dev

Available Templates

To see all available templates:

mizu new --list

Output:

Template    Purpose
api         JSON API service with a recommended layout
contract    Transport-neutral service contract with REST, JSON-RPC, and OpenAPI
live        Real-time interactive app with live views and instant updates
minimal     Smallest runnable Mizu project
sync        Offline-first app with sync, live updates, and reactive state
web         Full-stack web app with views, components, and static assets

Flags Reference

Required Flags

Flag	Short	Description
`--template <name>`	`-t`	The template to use

Optional Flags

Flag	Description	Default
`--list`	List available templates	-
`--dry-run`	Show what would be created without creating anything	-
`--force`	Overwrite existing files	-
`--name <value>`	Project name	Derived from path
`--module <value>`	Go module path	`example.com/<name>`
`--license <value>`	License identifier	`MIT`
`--var key=value`	Custom template variable (repeatable)	-

Detailed Flag Explanations

—template, -t (Required)

Specifies which template to use. This is the only required flag.

# Using long form
mizu new myapp --template api

# Using short form
mizu new myapp -t api

If you forget to specify a template:

error: template is required
Run 'mizu new --list' to see available templates.

—list

Lists all available templates without creating a project.

mizu new --list

This is helpful when you forget the template names.

—dry-run

Shows exactly what files would be created without actually creating them. This is useful for:

Previewing the project structure
Checking for conflicts before overwriting
Understanding what a template includes

mizu new myapp --template api --dry-run

Output:

Plan for template: api
Target: /Users/you/projects/myapp

Operations:
  mkdir  cmd
  mkdir  cmd/api
  mkdir  app
  mkdir  app/api
  mkdir  feature
  mkdir  feature/hello
  write  go.mod
  write  main.go
  write  cmd/api/main.go
  write  app/api/app.go
  write  app/api/config.go
  write  app/api/routes.go
  write  feature/hello/http.go
  ...

—force

Overwrites existing files without asking. Use this carefully!

# This will overwrite any existing files
mizu new myapp --template api --force

Without --force, if files already exist:

error: files already exist:
  go.mod
  main.go
Use --force to overwrite.

—name

Sets the project name explicitly. By default, the name is derived from the path.

# Name will be "myapp"
mizu new myapp --template api

# Override the name
mizu new myapp --template api --name my-cool-app

The name is used in:

Package names
Log messages
Config files

—module

Sets the Go module path. This is important for imports within your project.

# Default: example.com/myapp
mizu new myapp --template api

# Custom module path
mizu new myapp --template api --module github.com/myname/myapp

What is a module path? A Go module path is a unique identifier for your project. It’s used when:

Other packages import your code
You run go get to download your project
Go resolves dependencies

Common patterns:

github.com/username/project - For GitHub projects
example.com/project - For local development
company.com/team/project - For internal projects

—license

Sets the license identifier. Default is MIT.

mizu new myapp --template api --license Apache-2.0

This affects the LICENSE file content in templates that include one.

—var (Custom Variables)

Pass custom variables to templates. This flag can be used multiple times.

mizu new myapp --template api --var port=3000 --var db=postgres

Custom variables are available in templates as .Vars.key. Template authors can document which variables their templates support.

Working with Paths

Current Directory

Create files in the current directory:

# Using "."
mizu new . --template minimal

# Or omit the path entirely (same effect)
cd myproject
mizu new --template minimal

New Directory

Create a new directory for the project:

mizu new myapp --template api

Nested Path

Create a project in a nested path:

mizu new projects/backend/api --template api

All necessary parent directories are created automatically.

Absolute Path

You can also use absolute paths:

mizu new /Users/me/projects/myapp --template api

JSON Output

For scripting and automation, use --json:

mizu new myapp --template api --json

Output:

{
  "template": "api",
  "path": "/Users/you/projects/myapp",
  "operations": [
    {"type": "mkdir", "path": "cmd"},
    {"type": "mkdir", "path": "cmd/api"},
    {"type": "write", "path": "go.mod", "size": 156},
    {"type": "write", "path": "cmd/api/main.go", "size": 423}
  ],
  "summary": {
    "directories": 5,
    "files": 12
  }
}

JSON with Dry Run

Combine --json with --dry-run to get a machine-readable plan:

mizu new myapp --template api --dry-run --json

JSON Error Output

Errors are also returned as JSON:

{
  "error": "unknown_template",
  "message": "unknown template: badname"
}

Common Workflows

Start a New Project

The most common workflow:

# 1. Create the project
mizu new myapp --template api

# 2. Enter the project directory
cd myapp

# 3. Download dependencies
go mod tidy

# 4. Start development
mizu dev

Preview Before Creating

If you’re unsure what a template contains:

# See what will be created
mizu new myapp --template api --dry-run

# If it looks good, create it
mizu new myapp --template api

Start Fresh

If you want to reset a project to the template defaults:

# This overwrites all files
mizu new . --template api --force

Using --force will overwrite your existing code! Make sure you have a backup or have committed your changes to git first.

Scripted Project Creation

For automation (CI/CD, scripts):

#!/bin/bash
mizu new myapp --template api --module "github.com/company/myapp" --json > result.json

if [ $? -eq 0 ]; then
  echo "Project created successfully"
  cd myapp && go mod tidy
else
  echo "Failed to create project"
  cat result.json
  exit 1
fi

Template Variables

Templates have access to these built-in variables:

Variable	Description	Example
`Name`	Project name	`myapp`
`Module`	Go module path	`github.com/me/myapp`
`License`	License identifier	`MIT`
`Year`	Current year	`2024`

Plus any custom variables you pass with --var.

Error Messages

Unknown Template

error: unknown template "badname"
Run 'mizu new --list' to see available templates.

Fix: Use mizu new --list to see valid template names.

Files Already Exist

error: files already exist:
  go.mod
  main.go
Use --force to overwrite.

Fix: Either use --force to overwrite, or choose a different path.

Invalid Path

error: path "/root/project" is not writable

Fix: Choose a path where you have write permissions.

Exit Codes

Code	Meaning
0	Success
1	Error (template error, file system error)
2	Usage error (missing flags, invalid arguments)

Next Steps

After creating a project:

Run Your Project

Start the development server

Explore Templates

Learn what each template includes

Getting Started

Commands

Templates Overview

Minimal Template

API Template

Contract Template

Web Template

Live Template

Sync Template

Reference

​Basic Usage

​Quick Examples

​Understanding the Command

​Available Templates

​Flags Reference

​Required Flags

​Optional Flags

​Detailed Flag Explanations

​—template, -t (Required)

​—list

​—dry-run

​—force

​—name

​—module

​—license

​—var (Custom Variables)

​Working with Paths

​Current Directory

​New Directory

​Nested Path

​Absolute Path

​JSON Output

​JSON with Dry Run

​JSON Error Output

​Common Workflows

​Start a New Project

​Preview Before Creating

​Start Fresh

​Scripted Project Creation

​Template Variables

​Error Messages

​Unknown Template

​Files Already Exist

​Invalid Path

​Exit Codes

​Next Steps

Run Your Project

Explore Templates

Basic Usage

Quick Examples

Understanding the Command

Available Templates

Flags Reference

Required Flags

Optional Flags

Detailed Flag Explanations

—template, -t (Required)

—list

—dry-run

—force

—name

—module

—license

—var (Custom Variables)

Working with Paths

Current Directory

New Directory

Nested Path

Absolute Path

JSON Output

JSON with Dry Run

JSON Error Output

Common Workflows

Start a New Project

Preview Before Creating

Start Fresh

Scripted Project Creation

Template Variables

Error Messages

Unknown Template

Files Already Exist

Invalid Path

Exit Codes

Next Steps