EasyP Configuration Reference

EasyP can be configured through CLI flags, environment variables, and configuration files. This guide covers all configuration options available in EasyP.

CLI Flags

Global Flags

Available for all commands:

Flag	Short	Environment	Description	Default
`--cfg`	`-c`	`EASYP_CFG`	Configuration file path	`easyp.yaml`
`--config`		`EASYP_CFG`	Alias for `--cfg`	`easyp.yaml`
`--debug`	`-d`	`EASYP_DEBUG`	Enable debug mode	`false`
`--format`	`-f`	`EASYP_FORMAT`	Output format for commands that support multiple formats (`text`/`json`)	command-specific default

Examples:

# Use custom config file
easyp --cfg production.easyp.yaml lint

# Enable debug logging
easyp --debug lint

# Short form
easyp -c custom.yaml -d lint

Command-Specific Flags

Lint command:

easyp lint [flags]

Flag	Short	Environment	Description	Default
`--path`	`-p`		Directory path to lint	`.`
`--root`	`-r`		Base directory for file search	Current working directory
`--format`	`-f`	`EASYP_FORMAT`	Uses global format flag (`text`/`json`)	Inherits global default

Examples:

# Lint specific directory
easyp lint --path proto/

# Lint from subdirectory with proper import resolution
easyp lint --root src/IPC/Contracts --path .

# JSON output format
easyp --format json lint   # global flag

# Combined flags
easyp -f json lint -p proto/

Generate command:

easyp generate [flags]

Flag	Short	Environment	Description	Default
`--path`	`-p`	`EASYP_ROOT_GENERATE_PATH`	Directory path with proto files to generate	`.`
`--root`	`-r`		Base directory for file search	Current working directory

Examples:

# Generate from specific path
easyp generate --path api/

# Generate from subdirectory with proper import resolution
easyp generate --root src/IPC/Contracts --path .

# Using environment variable
EASYP_ROOT_GENERATE_PATH=proto/ easyp generate

Breaking command:

easyp breaking [flags]

Flag	Short	Environment	Description	Default
`--against`			Git ref to compare against	`master`
`--path`	`-p`		Directory path to check	`.`
`--format`	`-f`	`EASYP_FORMAT`	Uses global format flag (`text`/`json`)	Inherits global default

Examples:

# Check against main branch
easyp breaking --against main

# Check specific directory against develop branch
easyp breaking --against develop --path proto/

# JSON output
easyp --format json breaking --against main   # global flag

Init command:

easyp init [flags]

Flag	Short	Environment	Description	Default
`--dir`	`-d`	`EASYP_INIT_DIR`	Directory to initialize	`.`

Examples:

# Initialize current directory
easyp init

# Initialize specific directory
easyp init --dir proto-project/

easyp init is interactive:

If buf.yml/buf.yaml exists in the target directory root, it asks whether to migrate from Buf.
If easyp.yaml already exists, it asks for overwrite confirmation.

Validate-config command:

easyp validate-config [flags]

Flag	Short	Environment	Description	Default
`--config`	`-c`	`EASYP_CFG`	Configuration file path	`easyp.yaml`
`--format` (global)	`-f`	`EASYP_FORMAT`	Output format for commands that support multiple formats (`json` or `text`)	command-specific (`json` for `validate-config`)

Examples:

# Validate default config with JSON output (exit 0 when no errors)
easyp validate-config

# Validate a different file with text output (global --format)
easyp --format text validate-config --config example.easyp.yaml

Package management commands:

`easyp mod download`

Downloads dependencies based on lock file priority:

If easyp.lock exists - downloads exact versions from lock file
If easyp.lock is missing - downloads versions from easyp.yaml and creates easyp.lock

# Download exact versions (recommended for production)
easyp mod download

`easyp mod update`

Always downloads dependencies from easyp.yaml, ignoring existing lock file:

Ignores easyp.lock completely
Downloads versions from easyp.yaml
Creates/updates easyp.lock with new versions

# Update dependencies and lock file
easyp mod update

`easyp mod vendor`

Copies proto files from dependencies to local vendor/ directory (similar to go mod vendor).

# Create local vendor directory with dependencies
easyp mod vendor

No additional flags. Uses global --cfg flag for configuration.

Environment Variables

EasyP supports environment variables for configuration:

Variable	Description	Default
`EASYP_CFG`	Path to configuration file	`easyp.yaml`
`EASYP_DEBUG`	Enable debug logging	`false`
`EASYPPATH`	Cache and modules storage directory	`$HOME/.easyp`
`EASYP_FORMAT`	Output format for supported commands (`text`/`json`). If not set, each command uses its own default.	command-specific default
`EASYP_ROOT_GENERATE_PATH`	Root path for generate command	`.`
`EASYP_INIT_DIR`	Directory for init command	`.`

Examples:

# Custom cache directory
export EASYPPATH=/tmp/easyp-cache
easyp mod download

# Debug mode via environment
export EASYP_DEBUG=true
easyp lint

# Custom config file
export EASYP_CFG=config/easyp.yaml
easyp generate

The easyp.yaml file is the main configuration file for EasyP, defining how your proto files are linted, generated, and managed. This file is typically placed at the root of your project alongside your proto files.

File Structure Overview

.
├── easyp.yaml
├── easyp.lock
├── proto/
│   ├── user/
│   │   └── user.proto
│   └── order/
│       └── order.proto
└── vendor/

Configuration Format

EasyP supports both YAML and JSON configuration formats:

YAML Format (Recommended)

lint:
  use:
    - BASIC
    - COMMENT_SERVICE
deps:
  - github.com/googleapis/googleapis@v1.0.0
generate:
  inputs:
    - directory: "proto"
  plugins:
    - name: go
      out: .
      opts:
        paths: source_relative
breaking:
  ignore:
    - proto/experimental/
  against_git_ref: main

JSON Format

{
  "lint": {
    "use": ["BASIC", "COMMENT_SERVICE"]
  },
  "deps": [
    "github.com/googleapis/googleapis@v1.0.0"
  ],
  "generate": {
    "inputs": [
      {"directory": "proto"}
    ],
    "plugins": [
      {
        "name": "go",
        "out": ".",
        "opts": {
          "paths": "source_relative"
        }
      }
    ]
  },
  "breaking": {
    "ignore": ["proto/experimental/"],
    "against_git_ref": "main"
  }
}

Environment Variables in Configuration

EasyP supports environment variable expansion directly in the easyp.yaml configuration file. This allows you to use environment variables for dynamic configuration values.

Example with all supported features:

deps:
  # Basic expansion: ${VAR} - expands to the value of VAR
  - ${GOOGLEAPIS_REPO}@${GOOGLEAPIS_VERSION}
  
  # Default value: ${VAR:-default} - uses default if VAR is unset or empty
  - ${GNOSTIC_REPO:-github.com/google/gnostic}@${GNOSTIC_VERSION:-v0.7.0}

generate:
  inputs:
    # Default value if INPUT_DIR is not set
    - directory: ${INPUT_DIR:-proto}
  plugins:
    - name: go
      # Basic expansion
      out: ${OUTPUT_DIR}
      opts:
        # Default value
        module: ${MODULE_NAME:-github.com/example/project}
        timeout: ${TIMEOUT:-30}
        
        # Escaping: $$ becomes literal $, $${VAR} becomes literal ${VAR}
        path: "${BASE_DIR}/$${TEMP}/file"     # Result: "/tmp/${TEMP}/file" (if BASE_DIR=/tmp)
        literal: "$$"                         # Result: "$"

Supported syntax:

${VAR} - expands to the value of VAR
${VAR:-default} - uses default if VAR is unset or empty
${VAR:=default} - uses default if VAR is unset or empty
${VAR-default} - uses default if VAR is unset (empty string is kept)
$${VAR} or $$VAR - escapes to literal ${VAR} or $VAR
$$ - escapes to literal $

Note: Environment variables are expanded before YAML parsing, so any ${STRING} pattern will be processed. Use $$ to escape dollar signs when you need literal values.

Configuration Fields

`version`

Optional (legacy compatibility). This field is accepted for backward compatibility and can be omitted in new configs.

Type: string Default: omitted Recommendation: if you keep it, use v1alpha

# Optional compatibility field (can be omitted)
version: v1alpha

The runtime behavior does not depend on this field.

`lint`

Optional. Configures proto file linting rules and behavior.

Type: object Default: Empty (no linting rules applied)

lint:
  use:
    - BASIC
    - COMMENT_SERVICE
  enum_zero_value_suffix: "UNSPECIFIED"
  service_suffix: "Service"
  ignore:
    - vendor/
    - proto/legacy/
  except:
    - COMMENT_FIELD
  allow_comment_ignores: true
  ignore_only:
    COMMENT_SERVICE:
      - proto/experimental/

`lint.use`

Optional. Specifies which linter rules or rule categories to apply.

Type: []string Default: [] (no rules)

Available categories:

MINIMAL - Essential package consistency checks
BASIC - Naming conventions and common patterns
DEFAULT - Additional recommended rules
COMMENTS - Comment requirements
UNARY_RPC - Streaming RPC restrictions

Individual rules: Any specific rule name (e.g., ENUM_PASCAL_CASE, FIELD_LOWER_SNAKE_CASE)

lint:
  use:
    - MINIMAL           # Use all minimal rules
    - BASIC             # Use all basic rules
    - COMMENT_SERVICE   # Require service comments
    - ENUM_PASCAL_CASE  # Specific rule

Rule Categories:

MINIMAL:

DIRECTORY_SAME_PACKAGE
PACKAGE_DEFINED
PACKAGE_DIRECTORY_MATCH
PACKAGE_SAME_DIRECTORY

BASIC:

ENUM_FIRST_VALUE_ZERO
ENUM_NO_ALLOW_ALIAS
ENUM_PASCAL_CASE
ENUM_VALUE_UPPER_SNAKE_CASE
FIELD_LOWER_SNAKE_CASE
IMPORT_NO_PUBLIC
IMPORT_NO_WEAK
IMPORT_USED
MESSAGE_PASCAL_CASE
ONEOF_LOWER_SNAKE_CASE
PACKAGE_LOWER_SNAKE_CASE
PACKAGE_SAME_CSHARP_NAMESPACE
PACKAGE_SAME_GO_PACKAGE
PACKAGE_SAME_JAVA_MULTIPLE_FILES
PACKAGE_SAME_JAVA_PACKAGE
PACKAGE_SAME_PHP_NAMESPACE
PACKAGE_SAME_RUBY_PACKAGE
PACKAGE_SAME_SWIFT_PREFIX
RPC_PASCAL_CASE
SERVICE_PASCAL_CASE

DEFAULT:

ENUM_VALUE_PREFIX
ENUM_ZERO_VALUE_SUFFIX
FILE_LOWER_SNAKE_CASE
RPC_REQUEST_RESPONSE_UNIQUE
RPC_REQUEST_STANDARD_NAME
RPC_RESPONSE_STANDARD_NAME
PACKAGE_VERSION_SUFFIX
SERVICE_SUFFIX

COMMENTS:

COMMENT_ENUM
COMMENT_ENUM_VALUE
COMMENT_FIELD
COMMENT_MESSAGE
COMMENT_ONEOF
COMMENT_RPC
COMMENT_SERVICE

UNARY_RPC:

RPC_NO_CLIENT_STREAMING
RPC_NO_SERVER_STREAMING

`lint.enum_zero_value_suffix`

Optional. Specifies the required suffix for enum zero values.

Type: string Default: "" (no suffix required) Common values: "UNSPECIFIED", "UNKNOWN", "DEFAULT"

lint:
  enum_zero_value_suffix: "UNSPECIFIED"

This enforces enum zero values like:

enum Status {
  STATUS_UNSPECIFIED = 0;  // Required suffix
  STATUS_ACTIVE = 1;
  STATUS_INACTIVE = 2;
}

`lint.service_suffix`

Optional. Specifies the required suffix for service names.

Type: string Default: "" (no suffix required) Common values: "Service", "API", "Svc"

lint:
  service_suffix: "Service"

This enforces service names like:

service UserService {    // Required "Service" suffix
  rpc GetUser(...) returns (...);
}

`lint.ignore`

Optional. Directories or files to exclude from all linting rules.

Type: []string Default: []

lint:
  ignore:
    - vendor/
    - proto/legacy/
    - testdata/
    - "**/*_test.proto"

Paths are relative to the easyp.yaml file location. Supports glob patterns.

`lint.except`

Optional. Disables specific rules globally across the entire project.

Type: []string Default: []

lint:
  except:
    - COMMENT_FIELD
    - COMMENT_MESSAGE
    - SERVICE_SUFFIX

`lint.allow_comment_ignores`

Optional. Enables inline comment-based rule ignoring within proto files.

Type: boolean Default: false

lint:
  allow_comment_ignores: true

When enabled, allows comments like:

// buf:lint:ignore COMMENT_SERVICE
service LegacyAPI {
  // nolint:COMMENT_RPC
  rpc GetData(...) returns (...);
}

`lint.ignore_only`

Optional. Disables specific rules only for certain files or directories.

Type: map[string][]string Default: {}

lint:
  ignore_only:
    COMMENT_SERVICE:
      - proto/legacy/
      - vendor/
    SERVICE_SUFFIX:
      - proto/external/

Key: Rule name or category Value: Array of file paths or directories

`deps`

Optional. Lists external proto dependencies to download and manage.

Type: []string
Default: []

Dependency Format

Dependencies follow the format: $GIT_LINK@$VERSION

Components:

$GIT_LINK - Git repository URL (GitHub, GitLab, etc.)
$VERSION - Git tag or full commit hash (optional)

Format variations:

owner/repo - Latest commit from default branch
owner/repo@v1.0.0 - Specific git tag
owner/repo@47b927cbb41c4fdea1292baf - Full commit hash
github.com/owner/repo@version - Full URL with version
gitlab.com/group/repo@tag - GitLab repository

deps:
  # Latest commit from default branch
  - googleapis/googleapis
  
  # Specific tag (recommended for production)
  - googleapis/googleapis@v1.0.0
  
  # Full commit hash (most precise)
  - googleapis/googleapis@47b927cbb41c4fdea1292bafadb8976f
  
  # Different Git hosting
  - gitlab.com/acme/proto@v2.1.0

Note: If @$VERSION is omitted, EasyP downloads the latest commit from the repository's default branch.

`generate`

Optional. Configures code generation from proto files.

Type: object Default: {}

generate:
  inputs:
    - directory: "proto"
    - git_repo:
        url: "github.com/acme/common@v1.0.0"
        sub_directory: "proto"
  plugins:
    - name: go
      out: .
      opts:
        paths: source_relative
    - name: go-grpc
      out: .
      opts:
        paths: source_relative
        require_unimplemented_servers: false

`generate.inputs`

Required when generate is set. Specifies sources of proto files for generation.

Type: []object (minimum 1 item) Default: not set

generate:
  inputs:
    # Local directory
    - directory: "proto"

    # Local directory with advanced options
    - directory:
        path: "api/proto"
        root: "."

    # Remote git repository
    - git_repo:
        url: "github.com/acme/common@v1.0.0"
        sub_directory: "proto"
        root: "."

Directory input fields:

directory (string or object) - Local directory path
directory.path (string) - Directory path
directory.root (string) - Root path for import resolution (default: ".")

Git repository input fields:

git_repo.url (string) - Repository URL with optional version
git_repo.sub_directory (string) - Subdirectory within the repository
git_repo.root (string) - Root path used for import resolution

`generate.plugins`

Required when generate is set. Configures protoc plugins for code generation.

Type: []object (minimum 1 item) Default: not set

generate:
  plugins:
    # Local plugin
    - name: go
      out: .
      opts:
        paths: source_relative

    # Remote plugin
    - remote: "buf.build/bufbuild/protovalidate-go:v0.4.0"
      out: gen/go
      opts:
        paths: source_relative

    # Plugin with import dependencies
    - name: grpc-gateway
      out: .
      with_imports: true
      opts:
        paths: source_relative

Plugin fields:

name (string, optional) - Plugin name (omit protoc-gen- prefix)
remote (string, optional) - Remote plugin URL for execution
path (string, optional) - Path to plugin executable file
command ([]string, optional) - Command to execute plugin
out (string, optional) - Output directory for generated files; defaults to the resolved generate root
opts (map[string](string | number | boolean | array<string | number | boolean>), optional) - Plugin-specific options; each key can be a single scalar value or an array of scalar values
with_imports (boolean, optional) - Include imported dependencies

Plugin source is one-of: exactly one of name, remote, path, or command must be set.

Common plugin options:

# Go plugin options
opts:
  paths: source_relative              # Generate files relative to input
  module: github.com/acme/api        # Go module path

# gRPC Gateway options
opts:
  paths: source_relative
  grpc_api_configuration: api.yaml   # gRPC API configuration

# OpenAPI v2 options
opts:
  simple_operation_ids: true         # Use simple operation IDs
  generate_unbound_methods: false    # Skip unbound methods

# ts-proto options with repeated key values
opts:
  env: node
  outputServices:
    - grpc-js
    - generic-definitions

When an opts value is a list, EasyP serializes it as repeated plugin params, e.g. outputServices=grpc-js,outputServices=generic-definitions.

`breaking`

Optional. Configures backward compatibility checking.

Type: object Default: {}

breaking:
  ignore:
    - proto/experimental/
    - proto/internal/
  against_git_ref: main

`breaking.ignore`

Optional. Directories or files to exclude from breaking change detection.

Type: []string Default: []

breaking:
  ignore:
    - proto/experimental/
    - proto/alpha/
    - testdata/

`breaking.against_git_ref`

Optional. Git reference (branch, tag, or commit) to compare against for breaking changes.

Type: string Default: "" (falls back to CLI --against default: master)

breaking:
  against_git_ref: main

Can be overridden by the --against CLI flag.

Configuration Examples

Minimal Configuration

lint:
  use:
    - MINIMAL

Development Configuration

lint:
  use:
    - BASIC
    - COMMENT_SERVICE
    - COMMENT_RPC
  allow_comment_ignores: true
  ignore:
    - vendor/
    - testdata/
deps:
  - github.com/googleapis/googleapis@v1.0.0
generate:
  inputs:
    - directory: "proto"
  plugins:
    - name: go
      out: .
      opts:
        paths: source_relative
    - name: go-grpc
      out: .
      opts:
        paths: source_relative

Production Configuration

lint:
  use:
    - MINIMAL
    - BASIC
    - DEFAULT
    - COMMENTS
  enum_zero_value_suffix: "UNSPECIFIED"
  service_suffix: "Service"
  ignore:
    - vendor/
  except: []
  allow_comment_ignores: false
deps:
  - github.com/googleapis/googleapis@v1.56.0
  - github.com/grpc-ecosystem/grpc-gateway@v2.18.0
generate:
  inputs:
    - directory: "proto"
  plugins:
    - name: go
      out: gen/go
      opts:
        paths: source_relative
        module: github.com/acme/api/gen/go
    - name: go-grpc
      out: gen/go
      opts:
        paths: source_relative
        require_unimplemented_servers: false
    - name: grpc-gateway
      out: gen/go
      opts:
        paths: source_relative
    - name: openapiv2
      out: gen/openapi
      opts:
        simple_operation_ids: true
breaking:
  ignore:
    - proto/experimental/
  against_git_ref: main

Multi-Service Configuration

lint:
  use:
    - BASIC
    - COMMENT_SERVICE
    - COMMENT_RPC
  service_suffix: "Service"
  ignore_only:
    COMMENT_FIELD:
      - proto/internal/
    SERVICE_SUFFIX:
      - proto/legacy/
deps:
  - github.com/googleapis/googleapis@v1.0.0
  - github.com/acme/common-proto@v2.1.0
generate:
  inputs:
    - directory: "proto/public"
    - directory: "proto/internal"
    - git_repo:
        url: "github.com/acme/shared-proto@v1.0.0"
        sub_directory: "proto"
  plugins:
    - name: go
      out: gen/go
      opts:
        paths: source_relative
    - name: go-grpc
      out: gen/go
      opts:
        paths: source_relative
    - name: grpc-gateway
      out: gen/go
      opts:
        paths: source_relative
    - remote: "buf.build/bufbuild/protovalidate-go:v0.4.0"
      out: gen/go
      opts:
        paths: source_relative
breaking:
  ignore:
    - proto/internal/
    - proto/experimental/
  against_git_ref: develop

Configuration Validation

EasyP validates configuration files on startup and provides helpful error messages:

# Invalid rule name
Error: invalid rule: INVALID_RULE_NAME

# Missing required field in generate section
Error: required field "plugins" is missing (path: generate.plugins)

# Invalid dependency format
Error: invalid dependency format: invalid-repo-url

Use easyp --debug for detailed validation information.

Migration from Buf

EasyP is fully compatible with Buf configurations. To migrate:

Place buf.yaml or buf.yml in the project root
Run easyp init and confirm migration when prompted
Update deps format if using BSR modules
Review migrated lint/breaking settings and adjust as needed

Most Buf configurations work without changes in EasyP.

EasyP Configuration Reference

CLI Flags

Global Flags

Command-Specific Flags

`easyp mod download`

`easyp mod update`

`easyp mod vendor`

Environment Variables

Configuration File

File Structure Overview

Configuration Format

YAML Format (Recommended)

JSON Format

Environment Variables in Configuration

Configuration Fields

`version`

`lint`

`lint.use`

`lint.enum_zero_value_suffix`

`lint.service_suffix`

`lint.ignore`

`lint.except`

`lint.allow_comment_ignores`

`lint.ignore_only`

`deps`

Dependency Format

`generate`

`generate.inputs`

`generate.plugins`

`breaking`

`breaking.ignore`

`breaking.against_git_ref`

Configuration Examples

Minimal Configuration

Development Configuration

Production Configuration

Multi-Service Configuration

Configuration Validation

Migration from Buf

On this page