Skip to main content
The kratos new command creates a new Kratos service project by cloning a template repository and configuring it with your project name.

​
Usage

kratos new [project-name] [flags]

​
Description

This command scaffolds a new microservice project using a predefined template. It supports both the standard service template and admin template, or you can specify a custom repository. The command will:
  • Clone the template repository
  • Rename the project to your specified name
  • Update the directory structure
  • Set up the initial project configuration

​
Arguments

  • project-name (optional) - The name of the project to create. If not provided, you’ll be prompted to enter it interactively.

​
Flags

​
-r, --repo
string
Custom repository URL to use as a template. Overrides the default template selection.
kratos new myapp -r https://github.com/myorg/my-template.git
​
-b, --branch
string
Specific branch of the repository to use. Defaults to the repository’s default branch.
kratos new myapp -b develop
​
-t, --timeout
string
default:"60s"
Timeout duration for the project creation operation.
kratos new myapp -t 120s
​
--nomod
boolean
default:"false"
Retain go.mod from parent directory. Use this when creating a project within an existing Go module.
kratos new myapp --nomod

​
Available Templates

When you don’t specify a custom repository, Kratos offers two built-in templates:

Service Template

Repository: https://github.com/go-kratos/kratos-layout.gitStandard microservice template with HTTP and gRPC support

Admin Template

Repository: https://github.com/go-kratos/kratos-admin.gitAdmin service template with additional administrative features

​
Examples

​
Basic Usage

Create a new service with the default template: 
kratos new helloworld
This will prompt you to select between the service and admin templates.

​
Create with Custom Name

kratos new my-awesome-service

​
Use Custom Repository

kratos new myapp --repo https://github.com/myorg/custom-template.git

​
Specify Branch

kratos new myapp --repo https://github.com/go-kratos/kratos-layout.git --branch v2.5.0

​
Create Within Existing Module

kratos new myapp --nomod

​
Create with Absolute or Home Path

kratos new ~/projects/myapp
kratos new /opt/services/myapp

​
What Gets Created

After running kratos new, you’ll have a project structure like: 
myapp/
├── api/              # API proto files
├── cmd/
│   └── myapp/       # Main application entry point
├── configs/          # Configuration files
├── internal/         # Private application code
│   ├── biz/         # Business logic
│   ├── conf/        # Configuration struct
│   ├── data/        # Data access layer
│   ├── server/      # HTTP and gRPC server setup
│   └── service/     # Service implementations
├── third_party/      # Third-party proto files
├── go.mod
├── go.sum
├── Makefile
└── README.md

​
Next Steps

After creating your project:
1

Navigate to project

cd myapp
2

Generate code from proto files

go generate ./...
3

Build the application

go build -o ./bin/ ./...
4

Run the service

./bin/myapp -conf ./configs
Or use the kratos CLI:
kratos run
If the project directory already exists, you’ll be prompted to confirm whether you want to override it.

Build docs developers (and LLMs) love

Get started for freeTalk to us