Skip to main content
The kratos run command runs your Kratos project locally using go run, automatically detecting your application’s entry point.

​
Usage

kratos run [directory] [flags] [-- program-args]

​
Description

This command provides a convenient way to run your Kratos service during development. It automatically:
  • Searches for the cmd/ directory in your project
  • Detects available entry points
  • Prompts you to select one if multiple are found
  • Executes go run with the appropriate directory

​
Arguments

  • directory (optional) - Specific directory containing the main package to run. If not provided, the command searches for cmd/ directories automatically.
  • program-args (optional) - Arguments to pass to your program. Separate these from command flags using --.

​
Flags

​
-w, --work
string
Target working directory for the running application. This changes the working directory before executing the program.
kratos run -w /path/to/workdir

​
Auto-detection

When you run kratos run without arguments, the command:
  1. Searches for directories under cmd/ in your project
  2. If one entry point is found, runs it automatically
  3. If multiple entry points exist, presents an interactive selection menu
  4. Searches up to 5 parent directories to find go.mod and cmd/

​
Examples

​
Basic Usage

Run the project from the project root: 
kratos run
If your project has a single service in cmd/myservice/, it runs automatically.

​
Multiple Services

For a project with multiple services: 
project/
├── cmd/
│   ├── api-server/
│   ├── worker/
│   └── admin/

kratos run
You’ll see an interactive prompt: 
? Which directory do you want to run?
  ❯ cmd/api-server
    cmd/worker
    cmd/admin

​
Specify Directory

Run a specific service directly: 
kratos run cmd/api-server

​
Pass Arguments to Program

Pass configuration or other arguments to your application: 
kratos run -- -conf ./configs
With specific directory: 
kratos run cmd/myservice -- -conf ./configs/dev.yaml

​
Change Working Directory

Run the service with a different working directory: 
kratos run -w /opt/myapp/data

​
Combined Flags and Arguments

kratos run cmd/api-server -w /var/app -- -conf ./configs/prod.yaml -debug

​
How It Works

The kratos run command essentially executes: 
go run <detected-directory> [program-args]
For example, if it detects cmd/myservice, it runs: 
go run cmd/myservice
With arguments: 
go run cmd/myservice -conf ./configs

​
Project Structure

The command works with standard Kratos project structure: 
myproject/
├── api/
├── cmd/
│   └── myproject/     # Main application
│       └── main.go
├── configs/
├── internal/
└── go.mod

​
Common Use Cases

​
Development Workflow

# Run with development config
kratos run -- -conf ./configs/dev.yaml

​
Debug Mode

# Run with debug flags
kratos run -- -conf ./configs -debug

​
Multiple Configuration Files

kratos run -- -conf ./configs/app.yaml -conf ./configs/db.yaml

​
Run from Subdirectory

The command searches parent directories for cmd/, so you can run it from anywhere in your project: 
cd internal/service
kratos run  # Still finds and runs cmd/myproject

​
Troubleshooting

The command searches up to 5 levels for a cmd/ directory. Ensure:
  • You’re within your project directory
  • Your project has a cmd/ directory
  • Your cmd/ directory contains subdirectories with main packages
If you have multiple services but want to run a specific one without the prompt:
kratos run cmd/specific-service
Always use -- to separate command flags from program arguments:
kratos run -- -conf ./configs  # Correct
kratos run -conf ./configs      # Wrong: -conf treated as kratos flag
The kratos run command is intended for development use. For production deployments, build your application binary and run it directly.
  • kratos new - Create a new project to run
  • Build your project: go build -o ./bin/ ./...

Build docs developers (and LLMs) love

Get started for freeTalk to us