0
# Application Management
1
2
The Application class serves as the main container and coordinator for CLI commands. It handles command registration, routing, argument parsing, execution flow, and provides the foundation for building complete CLI applications.
3
4
## Capabilities
5
6
### Application Creation and Configuration
7
8
Create and configure the main application container that will manage your CLI commands.
9
10
```python { .api }
11
class Application:
12
def __init__(self, name: str = "console", version: str = "") -> None:
13
"""
14
Create a new CLI application.
15
16
Args:
17
name (str): Application name, defaults to "console"
18
version (str): Application version string, defaults to empty
19
"""
20
```
21
22
### Command Registration and Management
23
24
Register commands with the application and manage the command registry.
25
26
```python { .api }
27
def add(self, command: Command) -> Command | None:
28
"""
29
Add a command to the application.
30
31
Args:
32
command (Command): The command instance to add
33
34
Returns:
35
Command | None: The added command or None if already exists
36
"""
37
38
def get(self, name: str) -> Command:
39
"""
40
Get a registered command by name.
41
42
Args:
43
name (str): Command name to retrieve
44
45
Returns:
46
Command: The command instance
47
48
Raises:
49
CleoCommandNotFoundError: If command not found
50
"""
51
52
def has(self, name: str) -> bool:
53
"""
54
Check if a command is registered.
55
56
Args:
57
name (str): Command name to check
58
59
Returns:
60
bool: True if command exists
61
"""
62
63
def find(self, name: str) -> Command:
64
"""
65
Find a command by name or abbreviation.
66
67
Args:
68
name (str): Command name or abbreviation
69
70
Returns:
71
Command: The matching command
72
73
Raises:
74
CleoCommandNotFoundError: If no matching command found
75
"""
76
77
def all(self, namespace: str | None = None) -> dict[str, Command]:
78
"""
79
Get all registered commands, optionally filtered by namespace.
80
81
Args:
82
namespace (str | None): Optional namespace to filter by
83
84
Returns:
85
dict[str, Command]: Dictionary of command name to Command instances
86
"""
87
```
88
89
### Application Execution
90
91
Execute the application with input arguments and manage the execution lifecycle.
92
93
```python { .api }
94
def run(self, input: Input | None = None, output: Output | None = None, error_output: Output | None = None) -> int:
95
"""
96
Run the application with provided input and output streams.
97
98
Args:
99
input (Input | None): Input stream, defaults to ArgvInput
100
output (Output | None): Output stream, defaults to StreamOutput
101
error_output (Output | None): Error output stream, defaults to StreamOutput
102
103
Returns:
104
int: Exit code (0 for success, non-zero for errors)
105
"""
106
107
def create_io(self, input: Input | None = None, output: Output | None = None, error_output: Output | None = None) -> IO:
108
"""
109
Create an IO instance for the application.
110
111
Args:
112
input (Input | None): Input stream
113
output (Output | None): Output stream
114
error_output (Output | None): Error output stream
115
116
Returns:
117
IO: Configured IO instance
118
"""
119
```
120
121
### Application Properties and Configuration
122
123
Access and configure application properties and metadata.
124
125
```python { .api }
126
@property
127
def name(self) -> str:
128
"""Get the application name."""
129
130
def set_name(self, name: str) -> None:
131
"""Set the application name."""
132
133
@property
134
def version(self) -> str:
135
"""Get the application version."""
136
137
def set_version(self, version: str) -> None:
138
"""Set the application version."""
139
140
@property
141
def display_name(self) -> str:
142
"""Get the application display name (name + version)."""
143
144
@property
145
def long_version(self) -> str:
146
"""Get the long version string with name and version."""
147
148
@property
149
def help(self) -> str:
150
"""Get the application help text."""
151
152
def set_help(self, help: str) -> None:
153
"""Set the application help text."""
154
155
@property
156
def definition(self) -> Definition:
157
"""Get the global input definition."""
158
159
@property
160
def default_commands(self) -> list[Command]:
161
"""Get the default commands (help, list, completions)."""
162
163
@property
164
def ui(self) -> UI:
165
"""Get the UI component manager."""
166
167
@property
168
def event_dispatcher(self) -> EventDispatcher | None:
169
"""Get the event dispatcher if configured."""
170
171
def set_event_dispatcher(self, dispatcher: EventDispatcher) -> None:
172
"""Set the event dispatcher for extensibility."""
173
```
174
175
## Usage Examples
176
177
### Basic Application Setup
178
179
```python
180
from cleo.application import Application
181
from cleo.commands.command import Command
182
183
class MyCommand(Command):
184
name = "hello"
185
description = "Say hello"
186
187
def handle(self):
188
self.line("Hello, World!")
189
190
# Create and configure application
191
app = Application("MyApp", "1.0.0")
192
app.add(MyCommand())
193
194
# Run the application
195
if __name__ == "__main__":
196
app.run()
197
```
198
199
### Application with Multiple Commands
200
201
```python
202
app = Application("toolkit", "2.1.0")
203
204
# Add multiple commands
205
app.add(ProcessCommand())
206
app.add(AnalyzeCommand())
207
app.add(ReportCommand())
208
209
# Check if command exists
210
if app.has("process"):
211
command = app.get("process")
212
213
# Get all commands
214
all_commands = app.all()
215
data_commands = app.all("data") # Commands in 'data' namespace
216
```
217
218
### Custom Application Configuration
219
220
```python
221
app = Application()
222
app.set_name("custom-tool")
223
app.set_version("3.2.1")
224
app.set_help("Custom CLI tool for data processing")
225
226
# Set up event handling for extensibility
227
from cleo.events.event_dispatcher import EventDispatcher
228
dispatcher = EventDispatcher()
229
app.set_event_dispatcher(dispatcher)
230
```