0
# Command Line Interface
1

2
The primary interface for taskipy, providing both command-line execution and programmatic API access for running tasks.
3

4
## Capabilities
5

6
### Main Entry Point
7

8
The main CLI entry point that processes command line arguments and exits with appropriate status codes.
9

10
```python { .api }
11
def main():
12
    """
13
    Main CLI entry point for taskipy.
14
    
15
    Reads sys.argv[1:] and calls run() with the arguments,
16
    then exits with the returned status code.
17
    """
18
```
19

20
### Programmatic Task Execution
21

22
Programmatic API for running taskipy without using the command line interface directly.
23

24
```python { .api }
25
def run(args: List[str], cwd: Union[str, Path, None] = None) -> int:
26
    """
27
    Run the taskipy CLI programmatically.
28

29
    Args:
30
        args: The arguments passed to the taskipy CLI
31
        cwd: The working directory to run the task in. If not
32
            provided, defaults to the current working directory
33

34
    Returns:
35
        0 on success; > 0 for an error
36
    """
37
```
38

39
## Usage Examples
40

41
### Command Line Usage
42

43
```bash
44
# Run a task
45
task test
46

47
# Run a task with arguments
48
task test --verbose --failfast
49

50
# List available tasks
51
task --list
52
task -l
53

54
# Get help
55
task --help
56
```
57

58
### Programmatic Usage
59

60
```python
61
from taskipy.cli import run
62
from pathlib import Path
63

64
# Basic programmatic execution
65
exit_code = run(['test'])
66

67
# Run with specific working directory
68
exit_code = run(['test'], cwd='/path/to/project')
69

70
# Run with arguments
71
exit_code = run(['test', '--verbose', '--failfast'])
72

73
# List tasks programmatically
74
exit_code = run(['--list'])
75

76
# Handle exit codes
77
if exit_code == 0:
78
    print("Task completed successfully")
79
elif exit_code == 127:
80
    print("Task not found or invalid usage")
81
else:
82
    print(f"Task failed with exit code {exit_code}")
83
```
84

85
### Integration Examples
86

87
```python
88
import subprocess
89
from taskipy.cli import run
90

91
# Integration with subprocess for complex workflows
92
def run_task_with_timeout(task_name, timeout=60):
93
    """Run a task with a timeout using subprocess."""
94
    try:
95
        result = subprocess.run(
96
            ['task', task_name],
97
            timeout=timeout,
98
            capture_output=True,
99
            text=True
100
        )
101
        return result.returncode, result.stdout, result.stderr
102
    except subprocess.TimeoutExpired:
103
        return 1, "", "Task timed out"
104

105
# Integration with CI/CD systems
106
def ci_task_runner(tasks):
107
    """Run multiple tasks in CI/CD pipeline."""
108
    for task in tasks:
109
        print(f"Running task: {task}")
110
        exit_code = run([task])
111
        if exit_code != 0:
112
            print(f"Task {task} failed with exit code {exit_code}")
113
            return exit_code
114
    return 0
115
```
116

117
## Command Line Arguments
118

119
The CLI supports the following arguments:
120

121
- **`name`** (positional, optional): Name of the task to run
122
- **`args`** (remainder): Arguments to pass to the task
123
- **`--list` / `-l`**: Show list of available tasks
124
- **`--help` / `-h`**: Show help message
125

126
## Exit Codes
127

128
- **0**: Success
129
- **1**: General error (TaskipyError)
130
- **127**: Task not found or invalid usage (TaskNotFoundError, InvalidUsageError)
131

132
## Error Handling
133

134
The CLI handles exceptions gracefully and returns appropriate exit codes:
135

136
```python
137
# TaskipyError exceptions are caught and their exit_code is returned
138
try:
139
    runner = TaskRunner(cwd)
140
    return runner.run(task_name, args)
141
except TaskipyError as e:
142
    print(e)
143
    return e.exit_code
144
except Exception as e:
145
    print(e)
146
    return 1
147
```
148

149
## Integration with Poetry
150

151
When using Poetry, tasks are typically run with:
152

153
```bash
154
poetry run task test
155
```
156

157
This ensures the task runs within the Poetry virtual environment with all dependencies available.
158

159
## Standalone Usage
160

161
Taskipy can also be used without Poetry in projects that have a valid `pyproject.toml`:
162

163
```bash
164
# Install globally or in virtual environment
165
pip install taskipy
166

167
# Run tasks directly
168
task test
169
```