0
# Core Application Framework
1

2
The foundation of Cyclopts CLI applications, providing the App class for command registration, argument parsing, and execution flow control.
3

4
## Capabilities
5

6
### App Class
7

8
The main application class that manages command registration, parsing, and execution.
9

10
```python { .api }
11
class App:
12
    def __init__(
13
        self,
14
        name: str | tuple[str, ...] | None = None,
15
        help: str | None = None,
16
        *,
17
        usage: str | None = None,
18
        alias: str | tuple[str, ...] | None = None,
19
        default_command: Callable[..., Any] | None = None,
20
        default_parameter: Parameter | None = None,
21
        config: Iterable[ConfigProtocol] | None = None,
22
        version: str | Callable[[], str] | None = None,
23
        version_flags: Iterable[str] = ("--version",),
24
        show: bool = True,
25
        console: Console | None = None,
26
        help_flags: Iterable[str] = ("--help", "-h"),
27
        help_format: Literal["markdown", "md", "plaintext", "restructuredtext", "rst", "rich"] | None = None,
28
        help_on_error: bool | None = None,
29
        version_format: Literal["markdown", "md", "plaintext", "restructuredtext", "rst", "rich"] | None = None,
30
        group: Group | str | tuple[Group | str, ...] | None = None,
31
        group_arguments: Group | str | None = None,
32
        group_parameters: Group | str | None = None,
33
        group_commands: Group | str | None = None,
34
        validator: list[Callable[..., Any]] | None = None,
35
        name_transform: Callable[[str], str] | None = None,
36
        sort_key: Callable[[str], Any] | None = None,
37
        end_of_options_delimiter: str | None = None,
38
        suppress_keyboard_interrupt: bool = True
39
    ):
40
        """
41
        Create a new Cyclopts application.
42
        
43
        Parameters
44
        ----------
45
        name
46
            Application name. If None, derived from calling module
47
        help
48
            Help text for the application
49
        usage
50
            Custom usage string override
51
        alias
52
            Alternative names for the application
53
        default_command
54
            Function to run when no command is specified
55
        default_parameter
56
            Default parameter configuration for all commands
57
        config
58
            Configuration loaders for file-based config
59
        version
60
            Version string or callable that returns version
61
        version_flags
62
            Flag options that trigger version display
63
        show
64
            Whether to show this app in parent help displays
65
        console
66
            Rich console for output formatting
67
        help_flags
68
            Flag options that trigger help display
69
        help_format
70
            Output format for help text (markdown, plaintext, rich, etc.)
71
        help_on_error
72
            Whether to show help on parsing errors
73
        version_format
74
            Output format for version text
75
        group
76
            Groups to organize this app within parent app
77
        group_arguments
78
            Default group for positional arguments
79
        group_parameters
80
            Default group for keyword parameters
81
        group_commands
82
            Default group for subcommands
83
        validator
84
            List of validator functions for the app
85
        name_transform
86
            Function to transform Python names to CLI names
87
        sort_key
88
            Function for sorting commands in help
89
        end_of_options_delimiter
90
            String that marks end of options (default: "--")
91
        suppress_keyboard_interrupt
92
            Whether to suppress KeyboardInterrupt exceptions
93
        """
94
```
95

96
### Command Registration
97

98
Register functions as commands and default handlers.
99

100
```python { .api }
101
def command(
102
    self,
103
    func: Callable = None,
104
    *,
105
    name: str | tuple[str, ...] | None = None
106
) -> Callable:
107
    """
108
    Register a function as a command.
109
    
110
    Parameters
111
    ----------
112
    func
113
        Function to register as command
114
    name
115
        Command name. If None, derived from function name
116
        
117
    Returns
118
    -------
119
    Callable
120
        The decorated function
121
    """
122

123
def default(self, func: Callable = None) -> Callable:
124
    """
125
    Register a function as the default command.
126
    
127
    Parameters
128
    ----------
129
    func
130
        Function to register as default command
131
        
132
    Returns
133
    -------
134
    Callable
135
        The decorated function
136
    """
137
```
138

139
### Parsing and Execution
140

141
Parse command-line arguments and execute commands.
142

143
```python { .api }
144
def parse_args(self, tokens: list[str] | None = None) -> Any:
145
    """
146
    Parse command-line arguments and return the result.
147
    
148
    Parameters
149
    ----------
150
    tokens
151
        Command-line tokens to parse. If None, uses sys.argv
152
        
153
    Returns
154
    -------
155
    Any
156
        Result of executing the matched command
157
    """
158

159
def parse_known_args(self, tokens: list[str] | None = None) -> tuple[Any, list[str]]:
160
    """
161
    Parse known arguments, returning result and remaining tokens.
162
    
163
    Parameters
164
    ----------
165
    tokens
166
        Command-line tokens to parse. If None, uses sys.argv
167
        
168
    Returns
169
    -------
170
    tuple[Any, list[str]]
171
        Result of command execution and list of unknown tokens
172
    """
173

174
def __call__(self, tokens: list[str] | None = None) -> Any:
175
    """
176
    Execute the application with command-line arguments.
177
    
178
    Parameters
179
    ----------
180
    tokens
181
        Command-line tokens to parse. If None, uses sys.argv
182
        
183
    Returns
184
    -------
185
    Any
186
        Result of executing the matched command
187
    """
188
```
189

190
### Application Properties and Methods
191

192
Additional App methods for help, version, and configuration.
193

194
```python { .api }
195
@property
196
def name(self) -> tuple[str, ...]:
197
    """Get the application name as a tuple."""
198

199
@property  
200
def help(self) -> str | None:
201
    """Get the application help text."""
202

203
@property
204
def version(self) -> str | Callable[[], str] | None:
205
    """Get the application version."""
206

207
def help_print(self, tokens: list[str] | None = None) -> None:
208
    """
209
    Print help information for the application or specific command.
210
    
211
    Parameters
212
    ----------
213
    tokens
214
        Command tokens to show help for
215
    """
216

217
def version_print(self) -> None:
218
    """Print the application version."""
219

220
def interactive_shell(self) -> None:
221
    """Start an interactive shell for the application."""
222

223
def update(self, other: App) -> None:
224
    """
225
    Update this app with configuration from another app.
226
    
227
    Parameters
228
    ----------
229
    other
230
        App to copy configuration from
231
    """
232
```
233

234
### High-Level Run Function
235

236
Convenience function for simple CLI applications.
237

238
```python { .api }
239
def run(
240
    func: Callable,
241
    *,
242
    name: str | tuple[str, ...] | None = None,
243
    help: str | None = None,
244
    version: str | Callable[[], str] | None = None,
245
    help_flags: Iterable[str] = ("--help", "-h"),
246
    version_flags: Iterable[str] = ("--version", "-V"),
247
    config: Iterable[ConfigProtocol] | None = None,
248
    console: Console | None = None,
249
    **kwargs
250
) -> Any:
251
    """
252
    Run a single function as a CLI application.
253
    
254
    Parameters
255
    ----------
256
    func
257
        Function to run as CLI command
258
    name
259
        Application name
260
    help
261
        Help text for the application
262
    version
263
        Version string or callable
264
    help_flags
265
        Flag options that trigger help display
266
    version_flags
267
        Flag options that trigger version display
268
    config
269
        Configuration loaders
270
    console
271
        Rich console for output
272
        
273
    Returns
274
    -------
275
    Any
276
        Result of function execution
277
    """
278
```
279

280
## Usage Examples
281

282
### Basic App with Multiple Commands
283

284
```python
285
from cyclopts import App
286

287
app = App(name="myapp", version="1.0.0")
288

289
@app.command
290
def hello(name: str):
291
    print(f"Hello {name}!")
292

293
@app.command  
294
def goodbye(name: str):
295
    print(f"Goodbye {name}!")
296

297
@app.default
298
def main():
299
    print("Available commands: hello, goodbye")
300

301
if __name__ == "__main__":
302
    app()
303
```
304

305
### App with Custom Configuration
306

307
```python
308
from cyclopts import App, Group
309
from cyclopts.config import Json
310

311
app = App(
312
    name="myapp",
313
    help="My CLI application", 
314
    group_commands=Group("Commands", "Available commands:"),
315
    config=[Json("config.json")],
316
    version="2.1.0"
317
)
318

319
@app.command
320
def process(input_file: str, verbose: bool = False):
321
    """Process an input file."""
322
    if verbose:
323
        print(f"Processing {input_file}")
324
    # Process file...
325

326
if __name__ == "__main__":
327
    app()
328
```