0
# Command Execution
1

2
Complete command execution functionality for sending commands to i3/sway and handling responses. Supports all i3/sway commands with detailed response handling and error reporting.
3

4
## Capabilities
5

6
### Basic Command Execution
7

8
```python { .api }
9
def command(self, payload: str) -> List[CommandReply]:
10
    """
11
    Execute i3/sway commands and get detailed response.
12
    
13
    Parameters:
14
    - payload: str, command string to execute (can contain multiple commands separated by semicolons)
15
    
16
    Returns:
17
    List[CommandReply]: response for each command executed
18
    """
19
```
20

21
### Tick Commands
22

23
```python { .api }
24
def send_tick(self, payload: str = "") -> TickReply:
25
    """
26
    Send a tick event with optional payload data.
27
    
28
    Parameters:
29
    - payload: str, optional data to include with the tick event
30
    
31
    Returns:
32
    TickReply: confirmation of tick event processing
33
    """
34
```
35

36
### Command Reply Structure
37

38
```python { .api }
39
class CommandReply:
40
    """Response from command execution."""
41
    success: bool  # Whether the command executed successfully
42
    error: str  # Error message if command failed (None if successful)
43
    ipc_data: dict  # Raw IPC response data
44
```
45

46
### Tick Reply Structure
47

48
```python { .api }
49
class TickReply:
50
    """Response from tick event transmission."""
51
    success: bool  # Whether tick was processed successfully
52
    ipc_data: dict  # Raw IPC response data
53
```
54

55
### Container Command Methods
56

57
```python { .api }
58
# Available on Con objects for targeted command execution
59
def command(self, command: str) -> List[CommandReply]:
60
    """
61
    Execute command on this specific container.
62
    
63
    Parameters:
64
    - command: str, command to execute (container will be implicitly focused first)
65
    
66
    Returns:
67
    List[CommandReply]: command execution results
68
    """
69

70
def command_children(self, command: str) -> List[CommandReply]:
71
    """
72
    Execute command on all direct child containers.
73
    
74
    Parameters:  
75
    - command: str, command to execute on each child container
76
    
77
    Returns:
78
    List[CommandReply]: execution results for each child
79
    """
80
```
81

82
### Command Categories and Examples
83

84
```python
85
# Window management commands
86
i3.command('focus left')
87
i3.command('focus right') 
88
i3.command('focus up')
89
i3.command('focus down')
90
i3.command('focus parent')
91
i3.command('focus child')
92

93
# Window movement
94
i3.command('move left')
95
i3.command('move right')
96
i3.command('move up') 
97
i3.command('move down')
98
i3.command('move container to workspace 2')
99
i3.command('move workspace to output HDMI-A-1')
100

101
# Layout commands
102
i3.command('split horizontal')
103
i3.command('split vertical')
104
i3.command('layout stacking')
105
i3.command('layout tabbed')
106
i3.command('layout toggle split')
107

108
# Window state
109
i3.command('fullscreen toggle')
110
i3.command('floating toggle')
111
i3.command('sticky toggle')
112

113
# Workspace commands
114
i3.command('workspace 1')
115
i3.command('workspace next')
116
i3.command('workspace prev')
117
i3.command('workspace back_and_forth')
118
i3.command('rename workspace to "new-name"')
119

120
# Application launching
121
i3.command('exec firefox')
122
i3.command('exec --no-startup-id notify-send "Hello"')
123

124
# Container operations
125
i3.command('kill')
126
i3.command('mark mymark')
127
i3.command('unmark mymark')
128
i3.command('[title="Firefox"] focus')
129

130
# i3 control
131
i3.command('reload')
132
i3.command('restart')
133
i3.command('exit')
134

135
# Multiple commands
136
result = i3.command('workspace 2; exec firefox; split horizontal')
137
for i, reply in enumerate(result):
138
    print(f"Command {i+1}: {'success' if reply.success else f'error: {reply.error}'}")
139
```
140

141
### Error Handling
142

143
```python
144
# Check command execution results
145
result = i3.command('invalid_command')
146
reply = result[0]
147

148
if reply.success:
149
    print("Command executed successfully")
150
else:
151
    print(f"Command failed: {reply.error}")
152

153
# Handle multiple command results
154
results = i3.command('workspace 1; split horizontal; exec nonexistent-app')
155
for i, reply in enumerate(results):
156
    if not reply.success:
157
        print(f"Command {i+1} failed: {reply.error}")
158

159
# Container-specific command execution with error handling
160
focused = i3.get_tree().find_focused()
161
if focused:
162
    results = focused.command('layout tabbed')
163
    if results[0].success:
164
        print(f"Changed layout for container {focused.id}")
165
    else:
166
        print(f"Failed to change layout: {results[0].error}")
167
```
168

169
### Tick Event Usage
170

171
```python
172
# Send tick with payload for coordination
173
tick_result = i3.send_tick("script-completed")
174
if tick_result.success:
175
    print("Tick sent successfully")
176

177
# Subscribe to tick events to receive the tick
178
def on_tick(i3, event):
179
    print(f"Received tick: {event.payload}")
180
    if event.payload == "script-completed":
181
        print("Script coordination completed")
182

183
i3.on(Event.TICK, on_tick)
184

185
# Send tick from another process/script
186
i3.send_tick("processing-started")
187
# ... do work ...
188
i3.send_tick("processing-finished")
189
```