Quick Start Guide
Get started with params-proto v3 in 10 minutes!
Or with uv:
Using with Claude Code
params-proto includes a plugin that helps Claude write better configs and CLIs. Install it:
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:
That's it! No argparse boilerplate. Just type hints and inline comments.
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:
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:
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:
Notice how parameters are organized into groups! Run it:
Run it:
With custom arguments:
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.
Inline comments become help text: Write comments after parameters.
Override anywhere: CLI, direct assignment, context managers, config files.
What's Next?
Now that you've mastered the basics, dive deeper:
Decorators-@proto.cli,@proto.prefix,@protoin detailFunctions- Function-based CLIs and advanced patternsClasses- Class-based configuration strategies- Types - Union types, Literals, Enums, and validation
Prefixes- Composing configs from multiple namespacesOverrides- CLI, programmatic, YAML, and moreSubcommands- Multi-command CLIs (design doc)
Or jump straight to Examples for real-world patterns!