0
# CLI Usage
1

2
Command-line interface providing task execution, help system, shell completion, and comprehensive argument handling for interactive and scripted usage.
3

4
## Capabilities
5

6
### Main CLI Entry Point
7

8
The primary command-line interface accessed through the `poe` command after installation.
9

10
```python { .api }
11
def main() -> None:
12
    """
13
    Main CLI entry point function.
14
    
15
    Processes sys.argv arguments and executes poethepoet application.
16
    Handles builtin completion tasks and regular task execution.
17
    Exits with appropriate status code.
18
    """
19
```
20

21
### Command Syntax
22

23
```bash
24
poe [global_options] [task_name] [task_arguments]
25
```
26

27
### Global Options
28

29
```python { .api }
30
# Global CLI arguments available for all commands
31

32
# Help and Information
33
-h, --help [TASK]     # Show help for command or specific task
34
--version             # Show version information
35

36
# Verbosity Control  
37
-v, --verbose         # Increase output (repeatable: -v, -vv, -vvv)
38
-q, --quiet           # Decrease output (repeatable: -q, -qq, -qqq)
39

40
# Execution Control
41
-d, --dry-run         # Print the task contents but don't actually run it
42
-C, --directory PATH  # Specify where to find the pyproject.toml
43

44
# Environment Control
45
-e, --executor EXECUTOR  # Override executor type (poetry, uv, simple, virtualenv)
46

47
# Output Control
48
--ansi               # Force enable ANSI colors
49
--no-ansi            # Force disable ANSI colors
50
```
51

52
### Task Execution
53

54
#### Basic Task Execution
55

56
```bash
57
# Run a task defined in pyproject.toml
58
poe test
59

60
# Run with arguments passed to the task
61
poe serve --port 8080
62

63
# Run with verbose output
64
poe -v build
65

66
# Dry run to see what would be executed
67
poe -d deploy
68
```
69

70
#### Advanced Execution
71

72
```bash
73
# Change directory before running
74
poe -C /path/to/project test
75

76
# Override executor
77
poe -e simple test
78

79
# Multiple verbosity levels
80
poe -vv debug_task    # Very verbose
81
poe -q background_job # Quiet mode
82

83
# Disable colors for scripting
84
poe --no-ansi test | tee output.log
85
```
86

87
### Help System
88

89
#### General Help
90

91
```bash
92
# Show available tasks and general help
93
poe
94

95
# Show help for specific task
96
poe -h test
97
poe --help serve
98

99
# Show version information
100
poe --version
101
```
102

103
#### Task Information Display
104

105
When running `poe` without arguments, displays:
106
- Available tasks with descriptions
107
- Global options
108
- Configuration file location
109
- Environment information
110

111
### Shell Completion
112

113
Poethepoet provides shell completion for task names and global options.
114

115
```python { .api }
116
# Builtin completion functions (internal use)
117
def _run_builtin_task(
118
    task_name: str, 
119
    second_arg: str = "", 
120
    third_arg: str = ""
121
) -> bool:
122
    """
123
    Run builtin completion tasks.
124
    
125
    Args:
126
        task_name: Completion task name (_list_tasks, _zsh_completion, etc.)
127
        second_arg: Config path or alias name
128
        third_arg: Additional config path for bash completion
129
        
130
    Returns:
131
        True if task was handled
132
    """
133

134
def _list_tasks(target_path: Optional[str] = None) -> None:
135
    """
136
    List available tasks for shell completion.
137
    
138
    Args:
139
        target_path: Path to search for configuration
140
    """
141
```
142

143
#### Bash Completion Setup
144

145
```bash
146
# Generate bash completion script
147
poe _bash_completion poe
148

149
# Install completion (add to ~/.bashrc)
150
eval "$(poe _bash_completion poe)"
151
```
152

153
#### Zsh Completion Setup
154

155
```bash
156
# Generate zsh completion script  
157
poe _zsh_completion poe
158

159
# Install completion (add to ~/.zshrc)
160
eval "$(poe _zsh_completion poe)"
161
```
162

163
#### Fish Completion Setup
164

165
```bash
166
# Generate fish completion script
167
poe _fish_completion poe > ~/.config/fish/completions/poe.fish
168
```
169

170
### Environment Integration
171

172
#### Poetry Integration
173

174
When used in a Poetry project, poethepoet automatically:
175
- Detects Poetry virtual environment
176
- Uses Poetry's dependency isolation
177
- Inherits Poetry configuration
178

179
```bash
180
# In a Poetry project
181
poe test  # Runs in Poetry's virtual environment
182
```
183

184
#### UV Integration
185

186
When used in a UV project, poethepoet automatically:
187
- Detects UV virtual environment
188
- Uses UV's environment management
189
- Inherits UV configuration
190

191
```bash
192
# In a UV project  
193
poe build  # Runs in UV's virtual environment
194
```
195

196
### Error Handling
197

198
The CLI provides detailed error messages for common issues:
199

200
```python { .api }
201
# Exit codes returned by CLI
202
0   # Success
203
1   # Error (configuration, task not found, execution failure, etc.)
204
```
205

206
Common error scenarios:
207
- Task not found: Clear message with available tasks
208
- Configuration errors: Specific line/file information
209
- Execution failures: Command and exit code details
210
- Dependency cycles: Dependency chain visualization
211

212
### Configuration File Discovery
213

214
The CLI searches for configuration files in this order:
215

216
1. `pyproject.toml` (with `[tool.poe.tasks]` section)
217
2. `poe_tasks.toml`
218
3. `poe_tasks.yaml` 
219
4. `poe_tasks.json`
220

221
```bash
222
# Override config file location
223
poe -C /custom/path task_name
224

225
# Works with different config formats
226
poe -C ./config test  # Searches for any supported format
227
```
228

229
## Usage Examples
230

231
### Basic Task Management
232

233
```bash
234
# List all available tasks
235
poe
236

237
# Run specific tasks
238
poe test
239
poe lint  
240
poe build
241

242
# Task with arguments
243
poe serve --host 0.0.0.0 --port 3000
244
```
245

246
### Development Workflow
247

248
```bash
249
# Verbose development run
250
poe -v test
251

252
# Quick syntax check (dry run)
253
poe -d build
254

255
# Clean build with executor override
256
poe -e simple clean build
257

258
# Background deployment (quiet)
259
poe -q deploy
260
```
261

262
### Debugging and Development
263

264
```bash
265
# Maximum verbosity for debugging
266
poe -vvv problematic_task
267

268
# Dry run to understand execution
269
poe -d complex_sequence
270

271
# Change directory for debugging
272
poe -C /tmp/debug_env test
273
```
274

275
### Integration with CI/CD
276

277
```bash
278
# Disable colors for log parsing
279
poe --no-ansi test | tee test-results.log
280

281
# Quiet mode for automated systems
282
poe -q build deploy
283

284
# Specific directory execution
285
poe -C "${WORKSPACE}" test
286
```