0
# Program Management
1

2
Core program lifecycle management for Bubble Tea applications, including initialization, execution, configuration options, and terminal state control.
3

4
## Capabilities
5

6
### Program Creation
7

8
Creates a new Program instance with a model and optional configuration.
9

10
```go { .api }
11
/**
12
 * Creates a new Bubble Tea program with the given model and options
13
 * @param model - Initial model implementing the Model interface
14
 * @param opts - Variable number of ProgramOption functions
15
 * @returns New Program instance ready to run
16
 */
17
func NewProgram(model Model, opts ...ProgramOption) *Program
18

19
type Program struct {
20
    // Internal fields (not directly accessible)
21
}
22
```
23

24
**Usage Example:**
25

26
```go
27
type myModel struct {
28
    counter int
29
}
30

31
func (m myModel) Init() tea.Cmd { return nil }
32
func (m myModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) { return m, nil }
33
func (m myModel) View() string { return "Hello World" }
34

35
// Basic program creation
36
p := tea.NewProgram(myModel{})
37

38
// With options
39
p := tea.NewProgram(myModel{},
40
    tea.WithAltScreen(),
41
    tea.WithMouseCellMotion(),
42
)
43
```
44

45
### Program Execution
46

47
Runs the program's main event loop, blocking until termination.
48

49
```go { .api }
50
/**
51
 * Runs the program's event loop and blocks until termination
52
 * @returns Final model state and any error that occurred
53
 */
54
func (p *Program) Run() (Model, error)
55

56
/**
57
 * Deprecated: Use Run() instead.
58
 * Initializes program and returns final model state
59
 * @returns Final model state and any error that occurred
60
 */
61
func (p *Program) StartReturningModel() (Model, error)
62

63
/**
64
 * Deprecated: Use Run() instead.
65
 * Initializes program, discards final model state
66
 * @returns Any error that occurred during execution
67
 */
68
func (p *Program) Start() error
69
```
70

71
**Usage Example:**
72

73
```go
74
p := tea.NewProgram(model{})
75
finalModel, err := p.Run()
76
if err != nil {
77
    fmt.Printf("Program error: %v\n", err)
78
}
79
```
80

81
### Message Injection
82

83
Sends messages to the running program from external goroutines or systems.
84

85
```go { .api }
86
/**
87
 * Sends a message to the program's update function
88
 * Safe to call from any goroutine, non-blocking if program hasn't started
89
 * No-op if program has already terminated
90
 * @param msg - Message to send to the update function
91
 */
92
func (p *Program) Send(msg Msg)
93
```
94

95
**Usage Example:**
96

97
```go
98
type tickMsg time.Time
99

100
// From another goroutine
101
go func() {
102
    ticker := time.NewTicker(time.Second)
103
    for {
104
        select {
105
        case t := <-ticker.C:
106
            p.Send(tickMsg(t))
107
        }
108
    }
109
}()
110
```
111

112
### Program Termination
113

114
Methods for stopping the program execution.
115

116
```go { .api }
117
/**
118
 * Gracefully quit the program, equivalent to sending QuitMsg
119
 * Safe to call from any goroutine
120
 */
121
func (p *Program) Quit()
122

123
/**
124
 * Immediately kill the program and restore terminal state
125
 * Skips final render, returns ErrProgramKilled
126
 */
127
func (p *Program) Kill()
128

129
/**
130
 * Blocks until the program has finished shutting down
131
 * Useful for coordinating with other goroutines
132
 */
133
func (p *Program) Wait()
134
```
135

136
### Terminal State Management
137

138
Control terminal state for integrating with external processes.
139

140
```go { .api }
141
/**
142
 * Restores original terminal state and cancels input reader
143
 * Use with RestoreTerminal to temporarily release control
144
 * @returns Error if restoration fails
145
 */
146
func (p *Program) ReleaseTerminal() error
147

148
/**
149
 * Reinitializes program after ReleaseTerminal
150
 * Restores terminal state and repaints screen
151
 * @returns Error if restoration fails
152
 */
153
func (p *Program) RestoreTerminal() error
154
```
155

156
**Usage Example:**
157

158
```go
159
// Temporarily release terminal for external command
160
p.ReleaseTerminal()
161
cmd := exec.Command("vim", "file.txt")
162
cmd.Run()
163
p.RestoreTerminal()
164
```
165

166
### Output Methods
167

168
Print output above the program interface.
169

170
```go { .api }
171
/**
172
 * Prints above the program interface (unmanaged output)
173
 * Output persists across renders, no effect if altscreen is active
174
 * @param args - Values to print, similar to fmt.Print
175
 */
176
func (p *Program) Println(args ...interface{})
177

178
/**
179
 * Printf-style printing above the program interface
180
 * Message printed on its own line, no effect if altscreen is active
181
 * @param template - Format string
182
 * @param args - Values for format string
183
 */
184
func (p *Program) Printf(template string, args ...interface{})
185
```
186

187
## Program Configuration Options
188

189
Program options customize behavior during initialization.
190

191
### Context and Lifecycle Options
192

193
```go { .api }
194
/**
195
 * Sets context for program execution, enables external cancellation
196
 * Program exits with ErrProgramKilled when context is cancelled
197
 */
198
func WithContext(ctx context.Context) ProgramOption
199

200
/**
201
 * Disables the built-in signal handler for SIGINT/SIGTERM
202
 * Useful when you want to handle signals yourself
203
 */
204
func WithoutSignalHandler() ProgramOption
205

206
/**
207
 * Disables panic catching and recovery
208
 * Warning: Terminal may be left in unusable state after panic
209
 */
210
func WithoutCatchPanics() ProgramOption
211

212
/**
213
 * Ignores OS signals (mainly useful for testing)
214
 * Prevents automatic handling of SIGINT/SIGTERM
215
 */
216
func WithoutSignals() ProgramOption
217
```
218

219
### Input/Output Options
220

221
```go { .api }
222
/**
223
 * Sets custom output writer, defaults to os.Stdout
224
 * @param output - Writer for program output
225
 */
226
func WithOutput(output io.Writer) ProgramOption
227

228
/**
229
 * Sets custom input reader, defaults to os.Stdin
230
 * Pass nil to disable input entirely
231
 * @param input - Reader for program input
232
 */
233
func WithInput(input io.Reader) ProgramOption
234

235
/**
236
 * Opens a new TTY for input instead of using stdin
237
 * Useful when stdin is redirected or piped
238
 */
239
func WithInputTTY() ProgramOption
240

241
/**
242
 * Sets environment variables for the program
243
 * Useful for remote sessions (SSH) to pass environment
244
 * @param env - Environment variables slice
245
 */
246
func WithEnvironment(env []string) ProgramOption
247
```
248

249
### Display Options
250

251
```go { .api }
252
/**
253
 * Starts program in alternate screen buffer (full window mode)
254
 * Screen automatically restored when program exits
255
 */
256
func WithAltScreen() ProgramOption
257

258
/**
259
 * Disables the renderer for non-TUI mode
260
 * Output behaves like regular command-line tool
261
 */
262
func WithoutRenderer() ProgramOption
263

264
/**
265
 * Sets custom FPS for renderer (default 60, max 120)
266
 * @param fps - Target frames per second
267
 */
268
func WithFPS(fps int) ProgramOption
269

270
/**
271
 * Deprecated: Removes redundant ANSI sequences for smaller output
272
 * This incurs a noticeable performance hit and will be optimized automatically in future releases
273
 */
274
func WithANSICompressor() ProgramOption
275
```
276

277
### Mouse and Input Options
278

279
```go { .api }
280
/**
281
 * Enables mouse in "cell motion" mode
282
 * Captures clicks, releases, wheel, and drag events
283
 */
284
func WithMouseCellMotion() ProgramOption
285

286
/**
287
 * Enables mouse in "all motion" mode
288
 * Captures all mouse events including hover (not all terminals support)
289
 */
290
func WithMouseAllMotion() ProgramOption
291

292
/**
293
 * Disables bracketed paste mode
294
 * Bracketed paste is enabled by default
295
 */
296
func WithoutBracketedPaste() ProgramOption
297

298
/**
299
 * Enables focus/blur event reporting
300
 * Sends FocusMsg/BlurMsg when terminal gains/loses focus
301
 */
302
func WithReportFocus() ProgramOption
303
```
304

305
### Advanced Options
306

307
```go { .api }
308
/**
309
 * Sets an event filter function to pre-process messages
310
 * Filter can modify, replace, or drop messages before Update
311
 * @param filter - Function that processes messages
312
 */
313
func WithFilter(filter func(Model, Msg) Msg) ProgramOption
314
```
315

316
**Filter Usage Example:**
317

318
```go
319
func preventQuit(m tea.Model, msg tea.Msg) tea.Msg {
320
    // Prevent quitting if there are unsaved changes
321
    if _, ok := msg.(tea.QuitMsg); ok {
322
        model := m.(myModel)
323
        if model.hasUnsavedChanges {
324
            return nil // Drop the quit message
325
        }
326
    }
327
    return msg
328
}
329

330
p := tea.NewProgram(model{}, tea.WithFilter(preventQuit))
331
```
332

333
## Control Messages
334

335
Built-in messages for program control.
336

337
```go { .api }
338
// Control message types
339
type QuitMsg struct{}
340
type SuspendMsg struct{}
341
type ResumeMsg struct{}
342
type InterruptMsg struct{}
343

344
// Control message constructors
345
func Quit() Msg
346
func Suspend() Msg
347
func Interrupt() Msg
348
```
349

350
**Usage in Update function:**
351

352
```go
353
func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
354
    switch msg := msg.(type) {
355
    case tea.KeyMsg:
356
        if msg.String() == "ctrl+c" {
357
            return m, tea.Quit()
358
        }
359
    case tea.QuitMsg:
360
        // Program is quitting
361
        return m, nil
362
    case tea.SuspendMsg:
363
        // Program was suspended (Ctrl+Z)
364
        return m, nil
365
    case tea.ResumeMsg:
366
        // Program was resumed
367
        return m, nil
368
    }
369
    return m, nil
370
}
371
```