devr

README

devr

A zero-config dev runner for Go projects

Build, run, watch, test – all from one command.
With a built-in TUI log viewer that has vim keybindings, log level filtering, and JSON pretty-printing.

Why devr?

Most Go dev workflows look like this: go run ., manually restart on every change, no log filtering or search. devr replaces all of that with a single command.

• One command to run – devr app run builds, starts, and opens a log viewer
• Auto-restart on changes – devr app watch rebuilds on every .go file save
• TUI log viewer – search, filter by level, JSON preview, vim navigation
• Pretty test output – dots, compact, or verbose – with failure summaries
• Zero config – works out of the box, optional .devr.yaml for customization

Install

go install github.com/pabiadzinski/devr/cmd/devr@latest

Get started

devr init myapp && cd myapp
devr app run

That's it. Your app is running and you're in the log viewer.

Usage

Run & Watch

devr app run              # build, start, open log viewer
devr app run --race=false # disable race detector (enabled by default)
devr app run --no-env     # skip loading .env file
devr app run --env-file .env.local
devr app watch            # same, but auto-restart on .go changes
devr app watch --debounce 1s
devr app stop             # send SIGTERM to the background process
devr app attach           # reattach to a running process
devr app logs             # view logs from last run
devr app ps               # list all managed processes

CLI flags override .devr.yaml values. Race detector is enabled by default.

Test

devr test run             # run tests with compact output
devr test run -f dots     # minimal dot output
devr test run -f verbose  # full verbose
devr test run -r TestFoo  # run specific tests
devr test bench           # run benchmarks
devr test cover           # coverage report, opens in browser
devr test cover -p custom.out

Scaffold

devr init myapp           # creates go.mod, main.go, .gitignore

Log Viewer

The built-in log viewer gives you a full-screen TUI with real-time tailing:

Key	Action
j/k, arrows	Navigate
Ctrl+D/U	Half page scroll
Ctrl+F/B	Full page scroll
H/M/L	Top / middle / bottom of screen
g / G	Jump to top / bottom
/	Filter lines (search + hide non-matching)
s	Search with highlight (no filtering)
n / N	Next / prev search match
1 2 3 4	Filter: error, warn, info, debug
0	Clear filter
w	Toggle line wrap (on by default)
Alt+Enter	Insert marker line
Tab	JSON pretty-print panel
Enter	Insert blank line
y	Copy line to clipboard
q	Detach (process keeps running)
Ctrl+C x2	Stop process & exit

Shell Completions

command devr completion fish | source   # fish (add to ~/.config/fish/config.fish)
eval "$(devr completion bash)"  # bash (add to ~/.bashrc)
eval "$(devr completion zsh)"   # zsh  (add to ~/.zshrc)

Configuration

Drop a .devr.yaml in your project root to customize behavior. All fields are optional:

build:
  cmd_pattern: "cmd/*/main.go"
  race: true              # enabled by default, use --race=false to disable
  flags: ["-trimpath"]    # extra go build flags

run:
  env_file: ".env"        # or .env.local, etc. (defaults to .env)
  no_env: false           # skip loading env file

watch:
  extensions: [".go"]
  exclude: ["vendor", "node_modules"]
  debounce: 500ms

logs:
  format: auto            # auto, json, or text
  level_field: level      # JSON field or key=value field for level
  level_values:
    error: ["error", "err", "fatal"]
    warn: ["warn", "warning"]
    info: ["info"]
    debug: ["debug", "trace"]
  highlight_fields: ["msg"]

test:
  cover_profile: "coverage.out"

notify: true  # macOS desktop notifications on build/crash failures

By default, devr uses logs.format: auto: it first tries JSON logs, then falls back to plain text / key=value parsing. This works out of the box for logs like {"level":"info","msg":"ready"}, INFO server started, or lvl=warning msg="slow query" if you set level_field: lvl.

Without a config file, devr uses sensible defaults – it just works.

License

MIT

Documentation

Index

• Variables
• func Dbg(msg string, args ...any)
• func Error(msg string, args ...any)
• func Info(msg string, args ...any)
• func Notify(_, _ string)
• func Register(c *CLI, a *App)
• func RunLogView(opts LogViewOptions) error
• func Warn(msg string, args ...any)
• func Watch(ctx context.Context, dir string, opts WatchOptions, onChange func()) error
• type App
  • func NewApp(name, workDir string) *App
  • func (a *App) BinFile() string
  • func (a *App) Build(pkg string) error
  • func (a *App) BuildAndStart(pkg string) (int, <-chan error, error)
  • func (a *App) FindPkg(pkg string) (string, error)
  • func (a *App) Kill()
  • func (a *App) LogFile() string
  • func (a *App) PidFile() string
  • func (a *App) PidGlob() string
  • func (a *App) ReadPid() (int, error)
  • func (a *App) Start() (int, <-chan error, error)
  • func (a *App) Stop() error
• type CLI
  • func (cli *CLI) Add(cmds ...Command)
  • func (cli *CLI) Run(args []string) error
• type Command
• type Config
  • func DefaultConfig() Config
  • func LoadConfig(dir string) Config
  • func (cfg *Config) BuildCLIFlags() []Flag
  • func (cfg *Config) RunCLIFlags() []Flag
  • func (cfg *Config) TestCLIFlags() []Flag
• type ConfigBuild
  • func (b ConfigBuild) GoFlags() []string
  • func (b ConfigBuild) Label() string
• type ConfigLogLevels
• type ConfigLogs
• type ConfigRun
• type ConfigTest
• type ConfigWatch
• type Flag
• type LogViewOptions
• type WatchOptions

Variables

var (
	LogDebug bool
)

Functions

func Dbg

func Dbg(msg string, args ...any)

func Error

func Error(msg string, args ...any)

func Info

func Info(msg string, args ...any)

func Notify

func Notify(_, _ string)

func Register

func Register(c *CLI, a *App)

func RunLogView

func RunLogView(opts LogViewOptions) error

func Warn

func Warn(msg string, args ...any)

func Watch

func Watch(ctx context.Context, dir string, opts WatchOptions, onChange func()) error

Types

type App

type App struct {
	Name    string
	Project string
	WorkDir string
	Cfg     Config
	// contains filtered or unexported fields
}

func NewApp

func NewApp(name, workDir string) *App

func (*App) BinFile

func (a *App) BinFile() string

func (*App) Build

func (a *App) Build(pkg string) error

func (*App) BuildAndStart

func (a *App) BuildAndStart(pkg string) (int, <-chan error, error)

func (*App) FindPkg

func (a *App) FindPkg(pkg string) (string, error)

func (*App) Kill

func (a *App) Kill()

func (*App) LogFile

func (a *App) LogFile() string

func (*App) PidFile

func (a *App) PidFile() string

func (*App) PidGlob

func (a *App) PidGlob() string

func (*App) ReadPid

func (a *App) ReadPid() (int, error)

func (*App) Start

func (a *App) Start() (int, <-chan error, error)

func (*App) Stop

func (a *App) Stop() error

type CLI

type CLI struct {
	Name    string
	Version string
	Flags   []Flag
	Setup   func() error
	// contains filtered or unexported fields
}

func (*CLI) Add

func (cli *CLI) Add(cmds ...Command)

func (*CLI) Run

func (cli *CLI) Run(args []string) error

type Command

type Command struct {
	Name  string
	Usage string
	Args  string
	Run   func(ctx context.Context, args []string) error
	Flags []Flag
	Sub   []Command
}

type Config

type Config struct {
	Build  ConfigBuild `yaml:"build"`
	Run    ConfigRun   `yaml:"run"`
	Watch  ConfigWatch `yaml:"watch"`
	Test   ConfigTest  `yaml:"test"`
	Logs   ConfigLogs  `yaml:"logs"`
	Notify bool        `yaml:"notify"`
}

func DefaultConfig

func DefaultConfig() Config

func LoadConfig

func LoadConfig(dir string) Config

func (*Config) BuildCLIFlags

func (cfg *Config) BuildCLIFlags() []Flag

func (*Config) RunCLIFlags

func (cfg *Config) RunCLIFlags() []Flag

func (*Config) TestCLIFlags

func (cfg *Config) TestCLIFlags() []Flag

type ConfigBuild

type ConfigBuild struct {
	CmdPattern string   `yaml:"cmd_pattern"`
	Flags      []string `yaml:"flags"`
	Race       bool     `yaml:"race"`
}

func (ConfigBuild) GoFlags

func (b ConfigBuild) GoFlags() []string

func (ConfigBuild) Label

func (b ConfigBuild) Label() string

type ConfigLogLevels

type ConfigLogLevels struct {
	Error []string `yaml:"error"`
	Warn  []string `yaml:"warn"`
	Info  []string `yaml:"info"`
	Debug []string `yaml:"debug"`
}

type ConfigLogs

type ConfigLogs struct {
	Format          string          `yaml:"format"`
	LevelField      string          `yaml:"level_field"`
	LevelValues     ConfigLogLevels `yaml:"level_values"`
	HighlightFields []string        `yaml:"highlight_fields"`
}

type ConfigRun

type ConfigRun struct {
	EnvFile string `yaml:"env_file"`
	NoEnv   bool   `yaml:"no_env"`
}

type ConfigTest

type ConfigTest struct {
	CoverProfile string `yaml:"cover_profile"`
}

type ConfigWatch

type ConfigWatch struct {
	Dirs       []string      `yaml:"dirs"`
	Extensions []string      `yaml:"extensions"`
	Exclude    []string      `yaml:"exclude"`
	Debounce   time.Duration `yaml:"debounce"`
}

type Flag

type Flag struct {
	Name    string
	Short   string
	Usage   string
	Default string
	Value   *string
	Bool    *bool
}

type LogViewOptions

type LogViewOptions struct {
	LogPath         string
	PID             int
	OnStop          func()
	OnReady         func(send func(tea.Msg))
	Title           string
	Logs            ConfigLogs
	HighlightFields []string
	ExitCh          <-chan error
}

type WatchOptions

type WatchOptions struct {
	Dirs       []string
	Extensions []string
	Exclude    []string
	Debounce   time.Duration
}