Bubble Tea

https://pkg.go.dev/github.com/charmbracelet/bubbletea
Admin
Bubble Tea is a Go framework for building elegant terminal user interfaces with a Model-View-Update...
Tokens:33,315
Snippets:368
Trust Score:10
Update:1 week ago
Show doc for...
Tokens:
Raw
### Example using WithAltScreen

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Shows how to start a program with the alternate screen buffer and handle errors.

```go
p := tea.NewProgram(Model{}, tea.WithAltScreen())
if _, err := p.Run(); err != nil {
    fmt.Println("Error running program:", err)
    os.Exit(1)
}
```

--------------------------------

### Batch usage example

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Example of using Batch in an Init method to return multiple commands.

```go
    func (m model) Init() Cmd {
	       return tea.Batch(someCommand, someOtherCommand)
    }
```

--------------------------------

### func (p *Program) Start() error (deprecated)

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Start starts the program. Deprecated.

```APIDOC
## func (p *Program) Start (deprecated)

### Description
Start starts the program. Deprecated.

### Signature
`func (p *Program) Start() error`

### Parameters
- **p** (*Program) - The Program.

### Returns
- error - An error if any.
```

--------------------------------

### Key.String method declaration and example

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Declares the String method on Key and shows an example of its usage with KeyEnter, printing 'enter'.

```go
func (k Key) String() (str string)
```

```go
k := Key{Type: KeyEnter}
fmt.Println(k)
// Output: enter
```

--------------------------------

### Example usage of ProgramOption

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Shows how to pass options to NewProgram.

```go
p := NewProgram(model, WithInput(someInput), WithOutput(someOutput))
```

--------------------------------

### Every usage example

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Example of using Every to produce a command that sends a TickMsg with the time of the tick.

```go
type TickMsg time.Time

cmd := Every(time.Second, func(t time.Time) Msg {
   return TickMsg(t)
})
```

--------------------------------

### LogToFile usage example

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Example of using LogToFile to create a log file and defer closing it. If an error occurs, it prints a fatal message and exits.

```go
  f, err := LogToFile("debug.log", "debug")
  if err != nil {
		fmt.Println("fatal:", err)
		os.Exit(1)
  }
  defer f.Close()
```

--------------------------------

### Example using WithEnvironment

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Shows how to pass environment variables from an SSH session to the program.

```go
var sess ssh.Session // ssh.Session is a type from the github.com/charmbracelet/ssh package
pty, _, _ := sess.Pty()
environ := append(sess.Environ(), "TERM="+pty.Term)
p := tea.NewProgram(model, tea.WithEnvironment(environ)
```

--------------------------------

### ExecProcess usage example

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Example of using ExecProcess to run the vim editor and receive a message with any error that occurred.

```go
type VimFinishedMsg struct { err error }

c := exec.Command("vim", "file.txt")

cmd := ExecProcess(c, func(err error) Msg {
    return VimFinishedMsg{err: err}
})
```

--------------------------------

### KeyType usage example

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Shows how to use KeyType with KeyRunes and Alt, printing the runes and the string representation 'alt+a'.

```go
k := Key{Type: KeyRunes, Runes: []rune{'a'}, Alt: true}
if k.Type == KeyRunes {

    fmt.Println(k.Runes)
    // Output: a

    fmt.Println(k.String())
    // Output: alt+a

}
```

--------------------------------

### SetWindowTitle function signature and example

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Signature and usage example for SetWindowTitle, which sets the terminal title.

```go
func SetWindowTitle(title string) Cmd
```

```go
func (m model) Init() Cmd {
    // Set title.
    return tea.SetWindowTitle("My App")
}
```

--------------------------------

### Start method signature

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Deprecated method that initializes the program and runs its event loops, blocking until terminated. Use Program.Run instead.

```go
func (p *Program) Start() error
```

--------------------------------

### Example using WithFilter

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Shows how to prevent program shutdown when there are unsaved changes.

```go
func filter(m tea.Model, msg tea.Msg) tea.Msg {
	if _, ok := msg.(tea.QuitMsg); !ok {
		return msg
	}

	model := m.(myModel)
	if model.hasChanges {
		return nil
	}

	return msg
}

p := tea.NewProgram(Model{}, tea.WithFilter(filter));

if _,err := p.Run(); err != nil {
	fmt.Println("Error running program:", err)
	os.Exit(1)
}
```

--------------------------------

### Sequentially function signature and example

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Signature and usage example for Sequentially, which executes commands sequentially and returns the first non-nil message. Deprecated.

```go
func Sequentially(cmds ...Cmd) Cmd
```

```go
func saveStateCmd() Msg {
   if err := save(); err != nil {
       return errMsg{err}
   }
   return nil
}

cmd := Sequentially(saveStateCmd, Quit)
```

--------------------------------

### func WithAltScreen

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Starts the program with the alternate screen buffer enabled (i.e. the program starts in full window mode). The altscreen will be automatically exited when the program quits.

```APIDOC
## func WithAltScreen

### Description
WithAltScreen starts the program with the alternate screen buffer enabled (i.e. the program starts in full window mode). Note that the altscreen will be automatically exited when the program quits.

### Signature
func WithAltScreen() ProgramOption

### Example
```go
p := tea.NewProgram(Model{}, tea.WithAltScreen())
if _, err := p.Run(); err != nil {
    fmt.Println("Error running program:", err)
    os.Exit(1)
}
```
```

--------------------------------

### Tick function signature and basic example

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Signature and basic usage example for Tick, which produces a command at an interval independent of the system clock.

```go
func Tick(d time.Duration, fn func(time.Time) Msg) Cmd
```

```go
type TickMsg time.Time

cmd := Tick(time.Second, func(t time.Time) Msg {
   return TickMsg(t)
})
```

--------------------------------

### WithAltScreen function signature

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Starts the program with the alternate screen buffer enabled.

```go
func WithAltScreen() ProgramOption
```

--------------------------------

### Every recurring tick example

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Example showing how to use Every to send a message every second by returning another Every command after receiving the tick message.

```go
type TickMsg time.Time

// Send a message every second.
func tickEvery() Cmd {
    return Every(time.Second, func(t time.Time) Msg {
        return TickMsg(t)
    })
}

func (m model) Init() Cmd {
    // Start ticking.
    return tickEvery()
}

func (m model) Update(msg Msg) (Model, Cmd) {
    switch msg.(type) {
    case TickMsg:
        // Return your Every command again to loop.
        return m, tickEvery()
    }
    return m, nil
}
```

--------------------------------

### func (*Program) Start (deprecated)

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Initializes the program and runs its event loops, blocking until terminated. Deprecated: please use Program.Run instead.

```APIDOC
## func (*Program) Start (deprecated)

### Description
Start initializes the program and runs its event loops, blocking until it gets terminated by either Program.Quit, Program.Kill, or its signal handler. Deprecated: please use Program.Run instead.

### Method
Start

### Signature
func (p *Program) Start() error

### Returns
- **error** - An error if the program fails to start or run.
```

--------------------------------

### func (p *Program) StartReturningModel() (Model, error) (deprecated)

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

StartReturningModel starts the program and returns the model. Deprecated.

```APIDOC
## func (p *Program) StartReturningModel (deprecated)

### Description
StartReturningModel starts the program and returns the model. Deprecated.

### Signature
`func (p *Program) StartReturningModel() (Model, error)`

### Parameters
- **p** (*Program) - The Program.

### Returns
- (Model, error) - The model and an error if any.
```

--------------------------------

### func WindowSize() Cmd

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

WindowSize is a command that queries the terminal for its current size and delivers the results to Update via a WindowSizeMsg. It is automatically invoked at program start and on window dimension changes, so explicit invocation is often unnecessary.

```APIDOC
## func WindowSize() Cmd

### Description
WindowSize is a command that queries the terminal for its current size. It delivers the results to Update via a WindowSizeMsg. Keep in mind that WindowSizeMsgs will automatically be delivered to Update when the Program starts and when the window dimensions change so in many cases you will not need to explicitly invoke this command.

### Signature
```go
func WindowSize() Cmd
```

### Returns
- **Cmd** - A command that queries the terminal size and sends a WindowSizeMsg.
```

--------------------------------

### WithInput usage example

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Creates a new program with input disabled by passing nil to WithInput.

```go
p := NewProgram(model, WithInput(nil))
```

--------------------------------

### Tick recurring example

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Shows how to use Tick to send messages repeatedly by returning another Tick command after receiving a tick message.

```go
type TickMsg time.Time

func doTick() Cmd {
    return Tick(time.Second, func(t time.Time) Msg {
        return TickMsg(t)
    })
}

func (m model) Init() Cmd {
    // Start ticking.
    return doTick()
}

func (m model) Update(msg Msg) (Model, Cmd) {
    switch msg.(type) {
    case TickMsg:
        // Return your Tick command again to loop.
        return m, doTick()
    }
    return m, nil
}
```

--------------------------------

### WithoutBracketedPaste

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Starts the program with bracketed paste disabled.

```APIDOC
## WithoutBracketedPaste

### Description
Starts the program with bracketed paste disabled.

### Function Signature
func WithoutBracketedPaste() ProgramOption
```

--------------------------------

### func (p *Program) Run() (returnModel Model, returnErr error)

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Run initializes the program and runs its event loops, blocking until it gets terminated by either Program.Quit, Program.Kill, or its signal handler. Returns the final model.

```APIDOC
## func (p *Program) Run() (returnModel Model, returnErr error)

### Description
Run initializes the program and runs its event loops, blocking until it gets terminated by either Program.Quit, Program.Kill, or its signal handler. Returns the final model.

### Signature
```go
func (p *Program) Run() (returnModel Model, returnErr error)
```
```

--------------------------------

### WindowSize function declaration

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Declares the WindowSize function that returns a Cmd to query the terminal size. It delivers results via WindowSizeMsg, which is also sent automatically at program start and on window changes.

```go
func WindowSize() Cmd
```

--------------------------------

### Implement the Init method

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Returns nil as the initial command, indicating no I/O is needed at startup.

```go
func (m model) Init() tea.Cmd {
    // Just return `nil`, which means "no I/O right now, please."
    return nil
}

```

--------------------------------

### StartReturningModel method signature

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Deprecated method that initializes the program and runs its event loops, returning the final model. Use Program.Run instead.

```go
func (p *Program) StartReturningModel() (Model, error)
```

--------------------------------

### Initialize the model with a grocery list

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Returns the initial model with a grocery list and an empty selection map. The map is used like a mathematical set.

```go
func initialModel() model {
	return model{
		// Our to-do list is a grocery list
		choices:  []string{"Buy carrots", "Buy celery", "Buy kohlrabi"},

		// A map which indicates which choices are selected. We're using
		// the  map like a mathematical set. The keys refer to the indexes
		// of the `choices` slice, above.
		selected: make(map[int]struct{}),
	}
}

```

--------------------------------

### func WindowSize() Cmd

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

WindowSize returns a command that requests the current window size.

```APIDOC
## func WindowSize

### Description
WindowSize returns a command that requests the current window size.

### Signature
`func WindowSize() Cmd`

### Returns
- Cmd - A command that requests the window size.
```

--------------------------------

### ErrProgramKilled variable declaration

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Declares the ErrProgramKilled variable, which is returned by Program.Run when the program gets killed.

```go
var ErrProgramKilled = errors.New("program was killed")
```

--------------------------------

### func (*Program) StartReturningModel (deprecated)

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Initializes the program and runs its event loops, blocking until terminated. Returns the final model. Deprecated: please use Program.Run instead.

```APIDOC
## func (*Program) StartReturningModel (deprecated)

### Description
StartReturningModel initializes the program and runs its event loops, blocking until it gets terminated by either Program.Quit, Program.Kill, or its signal handler. Returns the final model. Deprecated: please use Program.Run instead.

### Method
StartReturningModel

### Signature
func (p *Program) StartReturningModel() (Model, error)

### Returns
- **Model** - The final model after the program terminates.
- **error** - An error if the program fails to start or run.
```

--------------------------------

### Main function running the program

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

The main function creates a new Bubble Tea program with the initial model and runs it. If an error occurs, it prints an error message and exits with status 1.

```go
func main() {
    p := tea.NewProgram(initialModel())
    if _, err := p.Run(); err != nil {
        fmt.Printf("Alas, there's been an error: %v", err)
        os.Exit(1)
    }
}

```

--------------------------------

### KeyMsg keypress handling patterns

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Shows two patterns for checking keypresses: switching on the string representation and switching on the key type. The first is shorter, the second is more foolproof.

```go
// Switch on the string representation of the key (shorter)
switch msg := msg.(type) {
case KeyMsg:
    switch msg.String() {
    case "enter":
        fmt.Println("you pressed enter!")
    case "a":
        fmt.Println("you pressed a!")
    }
}

// Switch on the key type (more foolproof)
switch msg := msg.(type) {
case KeyMsg:
    switch msg.Type {
    case KeyEnter:
        fmt.Println("you pressed enter!")
    case KeyRunes:
        switch string(msg.Runes) {
        case "a":
            fmt.Println("you pressed a!")
        }
    }
}
```

--------------------------------

### func (*Program) Send

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Sends a message to the main update function, allowing messages to be injected from outside the program. It blocks if the program hasn't started and is a no-op if the program has terminated.

```APIDOC
## func (*Program) Send

### Description
Sends a message to the main update function, effectively allowing messages to be injected from outside the program for interoperability purposes. If the program hasn't started yet this will be a blocking operation. If the program has already been terminated this will be a no-op, so it's safe to send messages after the program has exited.

### Method
Send

### Signature
func (p *Program) Send(msg Msg)

### Parameters
- **msg** (Msg) - Required - The message to send to the program.
```

--------------------------------

### ExecProcess with nil error

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Shows how to use ExecProcess without handling errors by passing nil as the error handler.

```go
cmd := ExecProcess(exec.Command("vim", "file.txt"), nil)
```

--------------------------------

### type KeyType int

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

KeyType indicates the key pressed, such as KeyEnter or KeyBreak or KeyCtrlC. All other keys will be type KeyRunes. To get the rune value, check the Rune method on a Key struct, or use the Key.String() method.

```APIDOC
## type KeyType int

### Description
KeyType indicates the key pressed, such as KeyEnter or KeyBreak or KeyCtrlC. All other keys will be type KeyRunes. To get the rune value, check the Rune method on a Key struct, or use the Key.String() method.

### Definition
```go
type KeyType int
```

### Constants
```go
const (
	KeyNull      KeyType = keyNUL
	KeyBreak     KeyType = keyETX
	KeyEnter     KeyType = keyCR
	KeyBackspace KeyType = keyDEL
	KeyTab       KeyType = keyHT
	KeyEsc       KeyType = keyESC
	KeyEscape    KeyType = keyESC
)
```

### Usage Example
```go
k := Key{Type: KeyRunes, Runes: []rune{'a'}, Alt: true}
if k.Type == KeyRunes {
    fmt.Println(k.Runes)
    // Output: a

    fmt.Println(k.String())
    // Output: alt+a
}
```
```

--------------------------------

### Package and imports for Bubble Tea shopping list

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Defines the main package and imports the Bubble Tea library as 'tea'. Includes comments about unused imports and running 'go mod tidy'.

```go
package main

// These imports will be used later on the tutorial. If you save the file
// now, Go might complain they are unused, but that's fine.
// You may also need to run `go mod tidy` to download bubbletea and its
// dependencies.
import (
    "fmt"
    "os"

    tea "github.com/charmbracelet/bubbletea"
)

```

--------------------------------

### func WithFilter

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Supplies an event filter that will be invoked before Bubble Tea processes a tea.Msg. The filter can return any tea.Msg which will then get handled by Bubble Tea instead of the original event. If the filter returns nil, the event will be ignored.

```APIDOC
## func WithFilter

### Description
WithFilter supplies an event filter that will be invoked before Bubble Tea processes a tea.Msg. The event filter can return any tea.Msg which will then get handled by Bubble Tea instead of the original event. If the event filter returns nil, the event will be ignored and Bubble Tea will not process it.

### Signature
func WithFilter(filter func(Model, Msg) Msg) ProgramOption

### Parameters
- **filter** (func(Model, Msg) Msg) - Required - The event filter function.

### Example
```go
func filter(m tea.Model, msg tea.Msg) tea.Msg {
	if _, ok := msg.(tea.QuitMsg); !ok {
		return msg
	}

	model := m.(myModel)
	if model.hasChanges {
		return nil
	}

	return msg
}

p := tea.NewProgram(Model{}, tea.WithFilter(filter))

if _,err := p.Run(); err != nil {
	fmt.Println("Error running program:", err)
	os.Exit(1)
}
```
```

--------------------------------

### func LogToFile

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Sets up default logging to a file, useful when the terminal is occupied by the TUI. Creates the file if it doesn't exist and returns the file handle and error.

```APIDOC
## func LogToFile

### Description
Sets up default logging to log to a file. This is helpful as we can't print to the terminal since our TUI is occupying it. If the file doesn't exist it will be created.

### Function Signature
```go
func LogToFile(path string, prefix string) (*os.File, error)
```

### Parameters
- **path** (string) - Required - The file path for the log file.
- **prefix** (string) - Required - The log prefix.

### Returns
- **(*os.File, error)** - The file handle and an error if any.

### Example
```go
f, err := LogToFile("debug.log", "debug")
if err != nil {
    fmt.Println("fatal:", err)
    os.Exit(1)
}
defer f.Close()
```
```

--------------------------------

### func NewProgram(model Model, opts ...ProgramOption) *Program

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

NewProgram creates a new Program with the given model and options.

```APIDOC
## func NewProgram

### Description
NewProgram creates a new Program with the given model and options.

### Signature
`func NewProgram(model Model, opts ...ProgramOption) *Program`

### Parameters
- **model** (Model) - The initial model.
- **opts** (...ProgramOption) - The program options.

### Returns
- *Program - A new Program.
```

--------------------------------

### LogToFile function signature

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

LogToFile sets up default logging to a file, creating the file if it doesn't exist. It's useful because the TUI occupies the terminal. Remember to close the file when done.

```go
func LogToFile(path string, prefix string) (*os.File, error)
```

--------------------------------

### func Printf(template string, args ...interface{}) Cmd

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Printf returns a command that prints a formatted string to the output.

```APIDOC
## func Printf

### Description
Printf returns a command that prints a formatted string to the output.

### Signature
`func Printf(template string, args ...interface{}) Cmd`

### Parameters
- **template** (string) - The format string.
- **args** (...interface{}) - The arguments to format.

### Returns
- Cmd - A command that prints the formatted string.
```

--------------------------------

### func (p *Program) Run() (returnModel Model, returnErr error)

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Run runs the program and returns the final model and an error.

```APIDOC
## func (p *Program) Run

### Description
Run runs the program and returns the final model and an error.

### Signature
`func (p *Program) Run() (returnModel Model, returnErr error)`

### Parameters
- **p** (*Program) - The Program.

### Returns
- (returnModel Model, returnErr error) - The final model and an error if any.
```

--------------------------------

### func NewProgram(model Model, opts ...ProgramOption) *Program

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

NewProgram creates a new Program.

```APIDOC
## func NewProgram(model Model, opts ...ProgramOption) *Program

### Description
NewProgram creates a new Program.

### Signature
```go
func NewProgram(model Model, opts ...ProgramOption) *Program
```
```

--------------------------------

### func (p *Program) Println(args ...interface{})

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Println prints a line to the program's output.

```APIDOC
## func (p *Program) Println

### Description
Println prints a line to the program's output.

### Signature
`func (p *Program) Println(args ...interface{})`

### Parameters
- **p** (*Program) - The Program.
- **args** (...interface{}) - The values to print.
```

--------------------------------

### func (p *Program) Println(args ...interface{})

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Println prints above the Program. This output is unmanaged by the program and will persist across renders by the Program. If the altscreen is active no output will be printed.

```APIDOC
## func (p *Program) Println(args ...interface{})

### Description
Println prints above the Program. This output is unmanaged by the program and will persist across renders by the Program.

If the altscreen is active no output will be printed.

### Signature
```go
func (p *Program) Println(args ...interface{})
```
```

--------------------------------

### View method rendering the UI

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

The View method builds a string representing the entire UI. It iterates over choices, showing a cursor indicator and a checkbox, and includes a header and footer. It returns the string for rendering.

```go
func (m model) View() string {
    // The header
    s := "What should we buy at the market?\n\n"

    // Iterate over our choices
    for i, choice := range m.choices {

        // Is the cursor pointing at this choice?
        cursor := " " // no cursor
        if m.cursor == i {
            cursor = ">" // cursor!
        }

        // Is this choice selected?
        checked := " " // not selected
        if _, ok := m.selected[i]; ok {
            checked = "x" // selected!
        }

        // Render the row
        s += fmt.Sprintf("%s [%s] %s\n", cursor, checked, choice)
    }

    // The footer
    s += "\nPress q to quit.\n"

    // Send the UI for rendering
    return s
}

```

--------------------------------

### func Println(args ...interface{}) Cmd

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Println returns a command that prints a line to the output.

```APIDOC
## func Println

### Description
Println returns a command that prints a line to the output.

### Signature
`func Println(args ...interface{}) Cmd`

### Parameters
- **args** (...interface{}) - The values to print.

### Returns
- Cmd - A command that prints the line.
```

--------------------------------

### WithEnvironment function signature

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Sets environment variables for the program, useful for remote sessions.

```go
func WithEnvironment(env []string) ProgramOption
```

--------------------------------

### func LogToFile(path string, prefix string) (*os.File, error)

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Logs to a file with a given prefix. Returns the file handle and an error if any.

```APIDOC
## func LogToFile

### Description
Logs to a file with a given prefix. Returns the file handle and an error if any.

### Signature
`func LogToFile(path string, prefix string) (*os.File, error)`

### Parameters
- **path** (string) - The file path to log to.
- **prefix** (string) - The prefix for log lines.

### Returns
- (*os.File, error) - The file handle and an error if any.
```

--------------------------------

### func (k KeyMsg) String() (str string)

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

String returns a string representation of the KeyMsg.

```APIDOC
## func (k KeyMsg) String

### Description
String returns a string representation of the KeyMsg.

### Signature
`func (k KeyMsg) String() (str string)`

### Parameters
- **k** (KeyMsg) - The KeyMsg value.

### Returns
- (str string) - The string representation.
```

--------------------------------

### type ProgramOption

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

ProgramOption is used to set options when initializing a Program. Program can accept a variable number of options.

```APIDOC
## type ProgramOption

### Description
ProgramOption is used to set options when initializing a Program. Program can accept a variable number of options.

### Type Definition
```go
type ProgramOption func(*Program)
```

### Example
```go
p := NewProgram(model, WithInput(someInput), WithOutput(someOutput))
```
```

--------------------------------

### func Every

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Creates a command that ticks in sync with the system clock. Useful for periodic actions. The tick may not run for the entire specified duration due to clock alignment.

```APIDOC
## func Every

### Description
Every is a command that ticks in sync with the system clock. So, if you wanted to tick with the system clock every second, minute or hour you could use this. It's also handy for having different things tick in sync.
Because we're ticking with the system clock the tick will likely not run for the entire specified duration. For example, if we're ticking for one minute and the clock is at 12:34:20 then the next tick will happen at 12:35:00, 40 seconds later.

### Function Signature
```go
func Every(duration time.Duration, fn func(time.Time) Msg) Cmd
```

### Parameters
- **duration** (time.Duration) - Required - The duration between ticks.
- **fn** (func(time.Time) Msg) - Required - A function that takes the tick time and returns a message.

### Returns
- **Cmd** - A command that sends a single message at the next tick.

### Example
```go
type TickMsg time.Time

cmd := Every(time.Second, func(t time.Time) Msg {
    return TickMsg(t)
})
```

### Notes
Every sends a single message and won't automatically dispatch messages at an interval. To do that, you'll want to return another Every command after receiving your tick message.

```go
type TickMsg time.Time

// Send a message every second.
func tickEvery() Cmd {
    return Every(time.Second, func(t time.Time) Msg {
        return TickMsg(t)
    })
}

func (m model) Init() Cmd {
    // Start ticking.
    return tickEvery()
}

func (m model) Update(msg Msg) (Model, Cmd) {
    switch msg.(type) {
    case TickMsg:
        // Return your Every command again to loop.
        return m, tickEvery()
    }
    return m, nil
}
```
```

--------------------------------

### func EnterAltScreen() Msg

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

EnterAltScreen is a special command that tells the Bubble Tea program to enter the alternate screen buffer. Because commands run asynchronously, this command should not be used in your model's Init function. To initialize your program with the altscreen enabled use the WithAltScreen ProgramOption instead.

```APIDOC
## func EnterAltScreen() Msg

### Description
EnterAltScreen is a special command that tells the Bubble Tea program to enter the alternate screen buffer. Because commands run asynchronously, this command should not be used in your model's Init function. To initialize your program with the altscreen enabled use the WithAltScreen ProgramOption instead.

### Method
FUNCTION

### Endpoint
EnterAltScreen

### Parameters
None

### Response
#### Success Response
- **Msg** - A message that triggers the program to enter the alternate screen buffer.
```

--------------------------------

### WithFPS function signature

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Sets a custom maximum FPS for the renderer. Defaults to 60 if less than 1, capped at 120.

```go
func WithFPS(fps int) ProgramOption
```

--------------------------------

### func (p *Program) Printf(template string, args ...interface{})

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Printf prints a formatted string to the program's output.

```APIDOC
## func (p *Program) Printf

### Description
Printf prints a formatted string to the program's output.

### Signature
`func (p *Program) Printf(template string, args ...interface{})`

### Parameters
- **p** (*Program) - The Program.
- **template** (string) - The format string.
- **args** (...interface{}) - The arguments to format.
```

--------------------------------

### func WithAltScreen() ProgramOption

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

WithAltScreen returns a ProgramOption that enables the alternate screen.

```APIDOC
## func WithAltScreen

### Description
WithAltScreen returns a ProgramOption that enables the alternate screen.

### Signature
`func WithAltScreen() ProgramOption`

### Returns
- ProgramOption - A program option.
```

--------------------------------

### func (k KeyType) String() (str string)

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

String returns a string representation of the KeyType.

```APIDOC
## func (k KeyType) String

### Description
String returns a string representation of the KeyType.

### Signature
`func (k KeyType) String() (str string)`

### Parameters
- **k** (KeyType) - The KeyType value.

### Returns
- (str string) - The string representation.
```

--------------------------------

### WithInput

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Sets the input for the program, defaulting to stdin. Can be disabled by passing nil.

```APIDOC
## WithInput

### Description
Sets the input which, by default, is stdin. In most cases you won't need to use this. To disable input entirely pass nil.

### Function Signature
func WithInput(input io.Reader) ProgramOption

### Parameters
- **input** (io.Reader) - The input source. Pass nil to disable input.

### Example
```go
p := NewProgram(model, WithInput(nil))
```
```

--------------------------------

### WithInputTTY

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Opens a new TTY for input (or console input device on Windows).

```APIDOC
## WithInputTTY

### Description
Opens a new TTY for input (or console input device on Windows).

### Function Signature
func WithInputTTY() ProgramOption
```

--------------------------------

### func (p *Program) Printf(template string, args ...interface{})

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Printf prints above the Program. It takes a format template followed by values similar to fmt.Printf. This output is unmanaged by the program and will persist across renders by the Program. Unlike fmt.Printf (but similar to log.Printf) the message will be print on its own line. If the altscreen is active no output will be printed.

```APIDOC
## func (p *Program) Printf(template string, args ...interface{})

### Description
Printf prints above the Program. It takes a format template followed by values similar to fmt.Printf. This output is unmanaged by the program and will persist across renders by the Program.

Unlike fmt.Printf (but similar to log.Printf) the message will be print on its own line.

If the altscreen is active no output will be printed.

### Signature
```go
func (p *Program) Printf(template string, args ...interface{})
```
```

--------------------------------

### func LogToFileWith(path string, prefix string, log LogOptionsSetter) (*os.File, error)

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Logs to a file with a given prefix and custom log options. Returns the file handle and an error if any.

```APIDOC
## func LogToFileWith

### Description
Logs to a file with a given prefix and custom log options. Returns the file handle and an error if any.

### Signature
`func LogToFileWith(path string, prefix string, log LogOptionsSetter) (*os.File, error)`

### Parameters
- **path** (string) - The file path to log to.
- **prefix** (string) - The prefix for log lines.
- **log** (LogOptionsSetter) - The log options setter.

### Returns
- (*os.File, error) - The file handle and an error if any.
```

--------------------------------

### func WithEnvironment(env []string) ProgramOption

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

WithEnvironment returns a ProgramOption that sets the environment variables.

```APIDOC
## func WithEnvironment

### Description
WithEnvironment returns a ProgramOption that sets the environment variables.

### Signature
`func WithEnvironment(env []string) ProgramOption`

### Parameters
- **env** ([]string) - The environment variables.

### Returns
- ProgramOption - A program option.
```

--------------------------------

### func Sequence(cmds ...Cmd) Cmd

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Sequence runs commands sequentially, one after another.

```APIDOC
## func Sequence

### Description
Sequence runs commands sequentially, one after another.

### Signature
`func Sequence(cmds ...Cmd) Cmd`

### Parameters
- **cmds** (...Cmd) - The commands to run in sequence.

### Returns
- Cmd - A command that runs the given commands sequentially.
```

--------------------------------

### WithMouseAllMotion function signature

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Enables mouse in 'all motion' mode, capturing click, release, wheel, and motion events regardless of button state. Falls back to X10 mode if SGR is unsupported.

```go
func WithMouseAllMotion() ProgramOption
```

--------------------------------

### func ShowCursor() Msg

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

ShowCursor is a special command for manually instructing Bubble Tea to show the cursor.

```APIDOC
## func ShowCursor() Msg

### Description
ShowCursor is a special command for manually instructing Bubble Tea to show the cursor.

### Signature
```go
func ShowCursor() Msg
```
```

--------------------------------

### Cmd type definition

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Cmd is an IO operation that returns a message when complete. If nil, it's a no-op. Use for HTTP requests, timers, saving/loading from disk, etc. There's almost never a reason to use a command to send a message to another part of the program.

```go
type Cmd func() Msg
```

--------------------------------

### func (k Key) String() (str string)

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

String returns a string representation of the Key.

```APIDOC
## func (k Key) String

### Description
String returns a string representation of the Key.

### Signature
`func (k Key) String() (str string)`

### Parameters
- **k** (Key) - The Key value.

### Returns
- (str string) - The string representation.
```

--------------------------------

### KeyType.String

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Returns the string representation of a KeyType value.

```APIDOC
## KeyType.String

### Description
Returns the string representation of a KeyType value.

### Method
String

### Signature
func (k KeyType) String() (str string)

### Parameters
- **k** (KeyType) - The key type to convert to string.

### Returns
- **str** (string) - The string representation of the key type.

```

--------------------------------

### Define the model struct for the shopping list

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Defines the model struct that holds the application state: a slice of choices, a cursor index, and a set of selected items.

```go
type model struct {
    choices  []string           // items on the to-do list
    cursor   int                // which to-do list item our cursor is pointing at
    selected map[int]struct{}   // which to-do items are selected
}

```

--------------------------------

### WithMouseCellMotion

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Enables mouse support in 'cell motion' mode, capturing click, release, wheel, and drag events.

```APIDOC
## WithMouseCellMotion

### Description
Starts the program with the mouse enabled in "cell motion" mode. Cell motion mode enables mouse click, release, and wheel events. Mouse movement events are also captured if a mouse button is pressed (i.e., drag events). Cell motion mode is better supported than all motion mode. This will try to enable the mouse in extended mode (SGR), if that is not supported by the terminal it will fall back to normal mode (X10). To enable mouse cell motion once the program has already started running use the EnableMouseCellMotion command. To disable the mouse when the program is running use the DisableMouse command. The mouse will be automatically disabled when the program exits.

### Function Signature
func WithMouseCellMotion() ProgramOption
```

--------------------------------

### func ClearScreen() Msg

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

ClearScreen is a special command that tells the program to clear the screen before the next update. It can be used to move the cursor to the top left of the screen and clear visual clutter when the alt screen is not in use.

```APIDOC
## func ClearScreen() Msg

### Description
ClearScreen is a special command that tells the program to clear the screen before the next update. This can be used to move the cursor to the top left of the screen and clear visual clutter when the alt screen is not in use.

### Method
FUNCTION

### Endpoint
ClearScreen

### Parameters
None

### Response
#### Success Response
- **Msg** - A message that triggers the program to clear the screen.
```

--------------------------------

### Update method handling key messages

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

The Update method receives a tea.Msg and returns an updated model and a command. It uses a type switch to handle tea.KeyMsg, and a nested switch on the key string to move the cursor, toggle selection, or quit. It returns nil for the command.

```go
func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
    switch msg := msg.(type) {

    // Is it a key press?
    case tea.KeyMsg:

        // Cool, what was the actual key pressed?
        switch msg.String() {

        // These keys should exit the program.
        case "ctrl+c", "q":
            return m, tea.Quit

        // The "up" and "k" keys move the cursor up
        case "up", "k":
            if m.cursor > 0 {
                m.cursor--
            }

        // The "down" and "j" keys move the cursor down
        case "down", "j":
            if m.cursor < len(m.choices)-1 {
                m.cursor++
            }

        // The "enter" key and the spacebar (a literal space) toggle
        // the selected state for the item that the cursor is pointing at.
        case "enter", " ":
            _, ok := m.selected[m.cursor]
            if ok {
                delete(m.selected, m.cursor)
            } else {
                m.selected[m.cursor] = struct{}{}
            }
        }
    }

    // Return the updated model to the Bubble Tea runtime for processing.
    // Note that we're not returning a command.
    return m, nil
}

```

--------------------------------

### Log to a file with tea.LogToFile

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Log to a file instead of stdout when DEBUG environment variable is set. Uses tea.LogToFile("debug.log", "debug") and exits on error. Monitor with tail -f debug.log.

```go
if len(os.Getenv("DEBUG")) > 0 {
	f, err := tea.LogToFile("debug.log", "debug")
	if err != nil {
		fmt.Println("fatal:", err)
		os.Exit(1)
	}
	defer f.Close()
}

```

--------------------------------

### func (m MouseMsg) String() string

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

String returns a string representation of the MouseMsg.

```APIDOC
## func (m MouseMsg) String

### Description
String returns a string representation of the MouseMsg.

### Signature
`func (m MouseMsg) String() string`

### Parameters
- **m** (MouseMsg) - The MouseMsg value.

### Returns
- string - The string representation.
```

--------------------------------

### WithMouseAllMotion

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Enables mouse support in 'all motion' mode, capturing click, release, wheel, and motion events regardless of button state.

```APIDOC
## WithMouseAllMotion

### Description
Starts the program with the mouse enabled in "all motion" mode. This enables mouse click, release, wheel, and motion events, which are delivered regardless of whether a mouse button is pressed, effectively enabling support for hover interactions. This will try to enable the mouse in extended mode (SGR), if that is not supported by the terminal it will fall back to normal mode (X10). Many modern terminals support this, but not all. If in doubt, use EnableMouseCellMotion instead. To enable the mouse once the program has already started running use the EnableMouseAllMotion command. To disable the mouse when the program is running use the DisableMouse command. The mouse will be automatically disabled when the program exits.

### Function Signature
func WithMouseAllMotion() ProgramOption
```

--------------------------------

### ProgramOption type definition

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

ProgramOption is used to set options when initializing a Program.

```go
type ProgramOption func(*Program)
```

--------------------------------

### Key type declaration

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Defines the Key struct with fields Type, Runes, Alt, and Paste, containing information about a keypress.

```go
type Key struct {
	Type  KeyType
	Runes []rune
	Alt   bool
	Paste bool
}
```

--------------------------------

### ResumeMsg

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Can be listened to do something once a program is resumed back from a suspend state.

```APIDOC
## ResumeMsg

### Description
Can be listen to do something once a program is resumed back from a suspend state.

### Type Definition
type ResumeMsg struct{}
```

--------------------------------

### WithOutput

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Sets the output for the program, defaulting to stdout.

```APIDOC
## WithOutput

### Description
Sets the output which, by default, is stdout. In most cases you won't need to use this.

### Function Signature
func WithOutput(output io.Writer) ProgramOption

### Parameters
- **output** (io.Writer) - The output writer.
```

--------------------------------

### Batch function signature

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Batch performs a bunch of commands concurrently with no ordering guarantees. Use it to return several commands.

```go
func Batch(cmds ...Cmd) Cmd
```

--------------------------------

### func Exec(c ExecCommand, fn ExecCallback) Cmd

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Exec runs an external command and returns a command that sends the result to the callback.

```APIDOC
## func Exec

### Description
Exec runs an external command and returns a command that sends the result to the callback.

### Signature
`func Exec(c ExecCommand, fn ExecCallback) Cmd`

### Parameters
- **c** (ExecCommand) - The command to execute.
- **fn** (ExecCallback) - The callback to invoke with the result.

### Returns
- Cmd - A command that runs the external command.
```

--------------------------------

### WithInputTTY function signature

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Opens a new TTY for input (or console input device on Windows).

```go
func WithInputTTY() ProgramOption
```

--------------------------------

### WithInput function signature

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Sets the input for the program, defaulting to stdin. Pass nil to disable input entirely.

```go
func WithInput(input io.Reader) ProgramOption
```

--------------------------------

### WithContext function signature

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Specifies a context for the Program, useful for cancellation from outside.

```go
func WithContext(ctx context.Context) ProgramOption
```

--------------------------------

### LogToFileWith function signature

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

LogToFileWith allows calling LogToFile with a custom LogOptionsSetter.

```go
func LogToFileWith(path string, prefix string, log LogOptionsSetter) (*os.File, error)
```

--------------------------------

### Every function signature

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Every is a command that ticks in sync with the system clock. It's handy for having different things tick in sync. The tick may not run for the entire specified duration because it aligns with the system clock.

```go
func Every(duration time.Duration, fn func(time.Time) Msg) Cmd
```

--------------------------------

### KeyMsg.String method declaration

Source: https://pkg.go.dev/github.com/charmbracelet/bubbletea

Declares the String method on KeyMsg, returning a string representation for a key message, safe for key comparison.

```go
func (k KeyMsg) String() (str string)
```
Tokens:
Raw