kratos run

Run your Kratos project locally for development

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

Error: The cmd directory cannot be found

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

No prompt appears with multiple services

If you have multiple services but want to run a specific one without the prompt:

kratos run cmd/specific-service

Arguments not being passed correctly

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.

Related Commands

• kratos new - Create a new project to run
• Build your project: go build -o ./bin/ ./...