Quick Start Guide

Get started with params-proto v3 in 10 minutes!

bash

pip install params-proto==3.3.0

Or with uv:

bash

uv add params-proto==3.3.0

Using with Claude Code

params-proto includes a plugin that helps Claude write better configs and CLIs. Install it:

bash

/plugin marketplace add geyang/params-proto
/plugin install params-proto@params-proto

The plugin provides a skill that automatically activates when you're working with params-proto code.

Your First Proto Function CLI

Let's start with a simple train function---Just add @proto.cli and params-proto handles the rest.

Create train.py:

python

from params_proto import proto


@proto.cli
def train(
  lr: float = 0.001,  # Learning rate
  batch_size: int = 32,  # Training batch size
  epochs: int = 100,  # Number of training epochs
):
  """Train a neural network on CIFAR-10."""
  print(f"Training: {epochs} epochs, lr={lr}, batch_size={batch_size}")


if __name__ == "__main__":
  train()

That's it! No argparse boilerplate. Just type hints and inline comments.

Training: 100 epochs, lr=0.001, batch_size=32

Overview: Three Decorators

params-proto v3 provides three decorators in two categories:

Config Decorators (define parameter schemas)

Decorator	Scope	Use Case
`@proto`	Multiple instances	Library code, reusable components
`@proto.prefix`	Singleton (global)	Namespaced config groups (`Model.lr`, `Training.epochs`)

App Decorator (creates CLI entry point)

Decorator	Use Case
`@proto.cli`	Script entry points—wraps a function or class to parse CLI args

Typical pattern: Define configs with @proto/@proto.prefix, then create an entry point with @proto.cli.

Run it:

bash

$ python train.py --help

usage: train.py [-h] [--lr FLOAT] [--batch-size INT] [--epochs INT]

Train a neural network on CIFAR-10.

options:
  -h, --help           show this help message and exit
  --lr FLOAT           Learning rate (default: 0.001)
  --batch-size INT     Training batch size (default: 32)
  --epochs INT         Number of training epochs (default: 100)

bash

$ python train.py

Training for 100 epochs
  Learning rate: 0.001
  Batch size: 32

bash

$ python train.py --lr 0.01 --batch-size 64

Training for 100 epochs
  Learning rate: 0.01
  Batch size: 64

Python Namespaces as Config Singletons

As your config grows, classes provide better organization. Use @proto to turn a class into a configuration.

Create config.py:

python

from params_proto import proto


@proto
class Params:
    """Training configuration."""

    # Model settings
    model: str = "resnet50"  # Model architecture
    pretrained: bool = True  # Use pretrained weights

    # Training settings
    lr: float = 0.001  # Learning rate
    batch_size: int = 32  # Batch size
    epochs: int = 100  # Number of epochs

    # Data settings
    data_dir: str = "./data"  # Data directory
    num_workers: int = 4  # Number of data loading workers


# Access as class attributes
print(f"Training {Params.model} with lr={Params.lr}")

# Or create an instance
config = Params()
print(f"Batch size: {config.batch_size}")

Key difference: Classes use attributes (Params.lr), functions use parameters (train(lr=0.001)).

Composing Configurations from Multiple Locations

For larger projects, split configuration into logical groups using @proto.prefix. This creates namespaced parameters like --model.name and --training.lr.

Create train_rl.py:

python

from params_proto import proto


@proto.prefix
class Model:
  """Model configuration."""
  name: str = "resnet50"  # Architecture name
  pretrained: bool = True  # Use pretrained weights
  dropout: float = 0.5  # Dropout rate


@proto.prefix
class Data:
  """Data configuration."""
  dataset: str = "cifar10"  # Dataset name
  data_dir: str = "./data"  # Data directory
  num_workers: int = 4  # Data loading workers


@proto.prefix
class Training:
  """Training hyperparameters."""
  lr: float = 0.001  # Learning rate
  batch_size: int = 32  # Batch size
  epochs: int = 100  # Number of epochs


@proto.cli
def main(
  seed: int = 42,  # Random seed
  device: str = "cuda",  # Device to use (cuda/cpu)
):
  """Train a model on a dataset."""
  print(f"Training {Model.name} on {Data.dataset}")
  print(f"  LR: {Training.lr}, Batch size: {Training.batch_size}")
  print(f"  Device: {device}, Seed: {seed}")


if __name__ == "__main__":
  main()

Notice how parameters are organized into groups! Run it:

usage: train_rl.py [-h] [--seed INT] [--device STR] [OPTIONS]

Train a model on a dataset.

options:
  -h, --help                   show this help message and exit
  --seed INT                   Random seed (default: 42)
  --device STR                 Device to use (cuda/cpu) (default: cuda)

Model options:
  Model configuration.

  --model.name STR             Architecture name (default: resnet50)
  --model.pretrained           Use pretrained weights (default: True)
  --model.dropout FLOAT        Dropout rate (default: 0.5)

Data options:
  Data configuration.

  --data.dataset STR           Dataset name (default: cifar10)
  --data.data-dir STR          Data directory (default: ./data)
  --data.num-workers INT       Data loading workers (default: 4)

Training options:
  Training hyperparameters.

  --training.lr FLOAT          Learning rate (default: 0.001)
  --training.batch-size INT    Batch size (default: 32)
  --training.epochs INT        Number of epochs (default: 100)

Run it:

Training resnet50 on cifar10
  LR: 0.001, Batch size: 32
  Device: cuda, Seed: 42

With custom arguments:

Training vit on cifar10
  LR: 0.0001, Batch size: 32
  Device: cuda, Seed: 123

Prefixes create organization: Each @proto.prefix class becomes a group in the help text and uses dotted notation on the CLI.

Summary: Three Patterns

You've learned three core patterns in 10 minutes:

Pattern	Decorator	Use Case	Access Pattern
Functions	`@proto.cli`	Simple CLIs, scripts	Function parameters
Classes	`@proto`	Organized configs	Class attributes
Prefixes	`@proto.prefix`	Multi-namespace configs	Namespaced (e.g., `Model.name`)

Quick Tips

Type hints are required: params-proto uses type hints for parsing and validation.

python

lr: float = 0.001  # ✅ Required
lr = 0.001  # ❌ Won't work

Inline comments become help text: Write comments after parameters.

python

lr: float = 0.001  # Learning rate  ← This appears in --help

Override anywhere: CLI, direct assignment, context managers, config files.

python

# CLI
$ python
train.py - -lr
0.01

# Direct assignment
Training.lr = 0.01

# Context manager
with proto.bind(lr=0.01):
  train()

What's Next?

Now that you've mastered the basics, dive deeper:

Decorators - @proto.cli, @proto.prefix, @proto in detail
Functions - Function-based CLIs and advanced patterns
Classes - Class-based configuration strategies
Types - Union types, Literals, Enums, and validation
Prefixes - Composing configs from multiple namespaces
Overrides - CLI, programmatic, YAML, and more
Subcommands - Multi-command CLIs (design doc)

Or jump straight to Examples for real-world patterns!