0
# Cyclopts
1
2
Cyclopts is a modern, intuitive command-line interface (CLI) framework for Python that provides an efficient developer experience through advanced type hinting support, automatic help generation from docstrings, and extensible customization options. The library enables developers to quickly create CLI applications using a terse, intuitive syntax that fully supports all builtin Python types and user-specified types including Pydantic models, dataclasses, and Attrs.
3
4
## Package Information
5
6
- **Package Name**: cyclopts
7
- **Language**: Python
8
- **Installation**: `pip install cyclopts`
9
- **Minimum Python Version**: 3.9
10
- **Documentation**: https://cyclopts.readthedocs.io
11
12
## Core Imports
13
14
```python
15
import cyclopts
16
```
17
18
Common patterns for building CLI applications:
19
20
```python
21
from cyclopts import App, run
22
from cyclopts import Parameter, Argument
23
```
24
25
For configuration and advanced features:
26
27
```python
28
from cyclopts import config, types, validators
29
from cyclopts import Group, Token
30
```
31
32
## Basic Usage
33
34
```python
35
from cyclopts import run
36
37
def hello(name: str, count: int = 1):
38
"""Say hello to someone.
39
40
Parameters
41
----------
42
name
43
The name to greet
44
count
45
Number of times to greet
46
"""
47
for _ in range(count):
48
print(f"Hello {name}!")
49
50
if __name__ == "__main__":
51
run(hello)
52
```
53
54
```python
55
from cyclopts import App
56
57
app = App()
58
59
@app.command
60
def add(x: int, y: int):
61
"""Add two numbers."""
62
print(x + y)
63
64
@app.default
65
def main():
66
"""Main command when no subcommand specified."""
67
print("Use 'add' command to add numbers")
68
69
if __name__ == "__main__":
70
app()
71
```
72
73
## Architecture
74
75
Cyclopts follows a modular architecture centered around these key components:
76
77
- **App**: The main application class that manages commands, parsing, and execution
78
- **Arguments & Parameters**: Configuration objects that define how command-line inputs are handled
79
- **Tokens**: Immutable representations of user input that track source and parsing context
80
- **Groups**: Organizational structures for commands and parameters in help display
81
- **Converters & Validators**: Extensible type conversion and validation system
82
- **Configuration System**: File-based configuration loading from JSON, TOML, YAML, and environment variables
83
84
This design provides maximum flexibility while maintaining an intuitive API that leverages Python's type system for automatic CLI generation.
85
86
## Capabilities
87
88
### Core Application Framework
89
90
The foundation of Cyclopts CLI applications, providing the App class for command registration, argument parsing, and execution flow control.
91
92
```python { .api }
93
class App:
94
def __init__(self, **kwargs): ...
95
def command(self, func: Callable = None, *, name: str = None) -> Callable: ...
96
def default(self, func: Callable = None) -> Callable: ...
97
def parse_args(self, tokens: list[str] = None) -> Any: ...
98
def __call__(self, tokens: list[str] = None) -> Any: ...
99
100
def run(func: Callable, **kwargs) -> Any: ...
101
```
102
103
[Core Application Framework](./core-app.md)
104
105
### Argument and Parameter Configuration
106
107
Fine-grained control over command-line argument behavior, validation, and presentation through Argument, Parameter, and related configuration classes.
108
109
```python { .api }
110
class Argument:
111
def __init__(self, **kwargs): ...
112
113
class ArgumentCollection(list):
114
def __init__(self, *args): ...
115
116
class Parameter:
117
def __init__(self, **kwargs): ...
118
```
119
120
[Arguments and Parameters](./arguments-parameters.md)
121
122
### Type System and Validation
123
124
Comprehensive type conversion system with pre-built validated types and custom validation support for robust CLI input handling.
125
126
```python { .api }
127
def convert(type_, tokens: list[Token]) -> Any: ...
128
129
# Pre-built validated types from cyclopts.types
130
PositiveInt = Annotated[int, ...]
131
ExistingFile = Annotated[Path, ...]
132
Email = Annotated[str, ...]
133
```
134
135
[Type System and Validation](./types-validation.md)
136
137
### Configuration and File Loading
138
139
File-based configuration loading system supporting JSON, TOML, YAML formats and environment variable integration.
140
141
```python { .api }
142
from cyclopts.config import Json, Toml, Yaml, Env
143
144
class Json:
145
def __init__(self, file: Path): ...
146
147
class Toml:
148
def __init__(self, file: Path): ...
149
```
150
151
[Configuration System](./configuration.md)
152
153
### Advanced Features
154
155
Extended functionality including interactive editing, token manipulation, custom dispatching, and help system customization.
156
157
```python { .api }
158
def edit(text: str = "", **kwargs) -> str: ...
159
def env_var_split(value: str, type_: type) -> list[str]: ...
160
161
class Token:
162
keyword: str
163
value: str
164
source: str
165
```
166
167
[Advanced Features](./advanced-features.md)
168
169
### Exception Handling
170
171
Comprehensive exception hierarchy for precise error handling and debugging in CLI applications.
172
173
```python { .api }
174
class CycloptsError(Exception): ...
175
class ValidationError(CycloptsError): ...
176
class MissingArgumentError(CycloptsError): ...
177
```
178
179
[Exception Handling](./exceptions.md)