### Retrieve Command-Line Arguments with Shellout

Source: https://context7.com/tynanbe/shellout/llms.txt

Shows how to access and parse command-line arguments passed to a Gleam program using `shellout.arguments`. Examples include checking for flags, extracting values associated with flags, and filtering arguments to identify input files.

```gleam
import shellout
import gleam/io
import gleam/list
import gleam/string

pub fn main() {
  // Get all command-line arguments
  // Example: gleam run -- --verbose --output=file.txt input.txt
  let args = shellout.arguments()
  // args = ["--verbose", "--output=file.txt", "input.txt"]

  // Parse flags and values
  let verbose = list.contains(args, "--verbose")
  let output_file = args
    |> list.find(fn(arg) { string.starts_with(arg, "--output=") })
    |> result.map(fn(arg) { string.drop_left(arg, 9) })
    |> result.unwrap("output.txt")

  let input_files = args
    |> list.filter(fn(arg) { !string.starts_with(arg, "--") })

  case input_files {
    [] -> io.println_error("Error: No input files specified")
    files -> {
      io.println("Processing files: " <> string.join(files, ", "))
      io.println("Output: " <> output_file)
      io.println("Verbose: " <> bool.to_string(verbose))
    }
  }
}

```

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

### Execute Shell Commands with Shellout

Source: https://context7.com/tynanbe/shellout/llms.txt

Demonstrates how to execute system commands using the `shellout.command` function. It covers basic execution, setting environment variables, and allowing stdout to flow directly to the terminal. Error handling for command failures is also shown.

```gleam
import shellout
import gleam/io

pub fn main() {
  // Basic command execution
  case shellout.command(run: "ls", with: ["-lah"], in: ".", opt: []) {
    Ok(output) -> io.println(output)
    Error(#(status, message)) -> {
      io.print_error("Command failed with status: ")
      io.print_error(int.to_string(status))
      io.print_error("\n")
      io.print_error(message)
    }
  }

  // Execute command with environment variables
  case shellout.command(
    run: "node",
    with: ["app.js"],
    in: "/home/user/project",
    opt: [shellout.SetEnvironment([
      #("NODE_ENV", "production"),
      #("PORT", "3000"),
      #("API_KEY", "secret123")
    ])]
  ) {
    Ok(output) -> io.println("App output: " <> output)
    Error(#(code, err)) -> io.print_error("Failed: " <> err)
  }

  // Let stdout flow through (interactive commands)
  case shellout.command(
    run: "vim",
    with: ["file.txt"],
    in: ".",
    opt: [shellout.LetBeStdout]
  ) {
    Ok(_) -> io.println("Editor closed")
    Error(#(status, _)) -> io.println("Editor exited with: " <> int.to_string(status))
  }
}

```

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

### Execute Shell Command in Gleam

Source: https://github.com/tynanbe/shellout/blob/main/README.md

Demonstrates how to execute a shell command (e.g., 'ls') within a Gleam project using the shellout library. It handles both successful output and error reporting, including custom styling for error messages.

```gleam
import gleam/dict
import gleam/io
import gleam/result
import shellout.{type Lookups}

pub const lookups: Lookups = [
  #(
    ["color", "background"],
    [
      #("buttercup", ["252", "226", "174"]),
      #("mint", ["182", "255", "234"]),
      #("pink", ["255", "175", "243"]),
    ],
  ),
]

pub fn main() {
  shellout.arguments()
  |> shellout.command(run: "ls", in: ".", opt: [])
  |> result.map(with: fn(output) {
    io.print(output)
    0
  })
  |> result.map_error(with: fn(detail) {
    let #(status, message) = detail
    let style =
      shellout.display(["bold", "italic"])
      |> dict.merge(from: shellout.color(["pink"]))
      |> dict.merge(from: shellout.background(["brightblack"]))
    message
    |> shellout.style(with: style, custom: lookups)
    |> io.print_error
    status
  })
  |> result.unwrap_both
  |> shellout.exit
}
```

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

### Add Shellout as Mix Dependency

Source: https://github.com/tynanbe/shellout/blob/main/README.md

Instructions for adding the 'shellout' library as a dependency to a Mix (Elixir) project by modifying the 'mix.exs' file.

```elixir
defp deps do
  [
    {:shellout, "~> 1.7"},
  ]
end
```

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

### Add Shellout as Gleam Dependency

Source: https://github.com/tynanbe/shellout/blob/main/README.md

Instructions for adding the 'shellout' library as a dependency to a Gleam project by modifying the 'gleam.toml' file.

```shell
gleam add shellout
```

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

### Apply ANSI Display Styles with Shellout

Source: https://context7.com/tynanbe/shellout/llms.txt

Demonstrates how to apply various terminal display effects and color values using `shellout.style`. It covers reset, bold, dim, colors, and bright colors, showing how to combine them.

```gleam
import shellout
import gleam/io

pub fn show_all_styles() {
  // Display effects (shellout.displays constant)
  let displays = [
    "reset", "bold", "dim", "italic", "underline",
    "blink", "fastblink", "reverse", "hide", "strike",
    "normal", "noitalic", "nounderline", "noblink",
    "noreverse", "nohide", "nostrike"
  ]

  // Basic colors (shellout.colors constant)
  let colors = [
    "black", "red", "green", "yellow",
    "blue", "magenta", "cyan", "white", "default"
  ]

  // Bright colors
  let bright_colors = [
    "brightblack", "brightred", "brightgreen", "brightyellow",
    "brightblue", "brightmagenta", "brightcyan", "brightwhite"
  ]

  // Demo all color combinations
  colors
  |> list.each(fn(color) {
    let text = shellout.style(
      color,
      with: shellout.color([color]),
      custom: []
    )
    io.println(text)
  })
}
```

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

### Style Terminal Output with ANSI Codes using Shellout

Source: https://context7.com/tynanbe/shellout/llms.txt

Illustrates how to style terminal output with colors, backgrounds, and text effects using ANSI escape codes via the `shellout.style` function. It demonstrates basic styling, combined effects, custom color lookups, and direct RGB color specification.

```gleam
import shellout.{type Lookups}
import gleam/dict
import gleam/io

pub const lookups: Lookups = [
  #(
    ["color", "background"],
    [
      #("buttercup", ["252", "226", "174"]),
      #("mint", ["182", "255", "234"]),
      #("pink", ["255", "175", "243"]),
    ],
  ),
]

pub fn main() {
  // Basic color styling
  let message = shellout.style(
    "Success!",
    with: shellout.color(["green"]),
    custom: []
  )
  io.println(message)

  // Combined styles
  let error = shellout.style(
    "Error: File not found",
    with: shellout.display(["bold", "underline"])
      |> dict.merge(shellout.color(["red"])),
    custom: []
  )
  io.print_error(error)

  // Custom colors with RGB values
  let custom_styled = shellout.style(
    "Custom styled text",
    with: shellout.display(["bold", "italic"])
      |> dict.merge(shellout.color(["pink"]))
      |> dict.merge(shellout.background(["brightblack"])),
    custom: lookups
  )
  io.println(custom_styled)

  // RGB colors directly
  let rgb_text = shellout.style(
    "RGB colored",
    with: shellout.color(["255", "128", "64"]),
    custom: []
  )
  io.println(rgb_text)

  // Multiple display effects
  let fancy = shellout.style(
    "Warning!",
    with: shellout.display(["bold", "blink"])
      |> dict.merge(shellout.color(["brightyellow"]))
      |> dict.merge(shellout.background(["red"])),
    custom: []
  )
  io.println(fancy)
}

```

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

### Find Executable Paths with Shellout

Source: https://context7.com/tynanbe/shellout/llms.txt

Locates executables in the system PATH or verifies file existence using `shellout.which`. It can check for system commands, custom scripts, and handle cases where executables are not found.

```gleam
import shellout
import gleam/io

pub fn main() {
  // Find system executables
  case shellout.which("python3") {
    Ok(path) -> io.println("Python found at: " <> path)
    Error(msg) -> io.print_error(msg)
  }

  // Check for required tools
  let required_tools = ["git", "node", "npm"]
  let results = required_tools
    |> list.map(fn(tool) {
      #(tool, shellout.which(tool))
    })

  results
    |> list.each(fn(result) {
      let #(tool, path_result) = result
      case path_result {
        Ok(path) -> io.println(tool <> " ✓ " <> path)
        Error(_) -> io.println(tool <> " ✗ not found")
      }
    })

  // Check relative paths
  case shellout.which("./scripts/build.sh") {
    Ok(path) -> {
      io.println("Build script found: " <> path)
      shellout.command(run: path, with: [], in: ".", opt: [])
    }
    Error(err) -> {
      io.print_error("Build script not found: " <> err)
      Error(#(1, err))
    }
  }
}
```

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

### Add Shellout as Rebar3 Dependency

Source: https://github.com/tynanbe/shellout/blob/main/README.md

Instructions for adding the 'shellout' library as a dependency to a Rebar3 (Erlang) project by modifying the 'rebar.config' file.

```erlang
{deps, [
  {shellout, "1.7.0"}
]}.
```

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

### Control I/O Streams with Shellout

Source: https://context7.com/tynanbe/shellout/llms.txt

Provides options to manage how standard input, output, and error streams are handled. This includes capturing all output, letting streams pass through to the terminal, and enabling overlapped I/O on Windows.

```gleam
import shellout

pub fn main() {
  // Capture all output (default behavior)
  let result = shellout.command(
    run: "echo",
    with: ["Hello"],
    in: ".",
    opt: []
  )
  // result = Ok("Hello\n")

  // Let stdout pass through (for interactive commands)
  let result = shellout.command(
    run: "htop",
    with: [],
    in: ".",
    opt: [shellout.LetBeStdout]
  )
  // Output displays directly to terminal, result = Ok("")

  // Let stderr pass through separately
  let result = shellout.command(
    run: "grep",
    with: ["pattern", "nonexistent.txt"],
    in: ".",
    opt: [shellout.LetBeStderr]
  )
  // Errors display to terminal, result still captures stderr on JS

  // Windows overlapped I/O
  let result = shellout.command(
    run: "long-running.exe",
    with: [],
    in: ".",
    opt: [shellout.OverlappedStdio]
  )
  // Enables overlapped I/O on Windows for better performance
}
```

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

### Manage Environment Variables with Shellout

Source: https://context7.com/tynanbe/shellout/llms.txt

Allows setting, overriding, or unsetting environment variables for spawned processes. The `shellout.SetEnvironment` option within `shellout.command` is used for this purpose.

```gleam
import shellout

pub fn main() {
  // Set multiple environment variables
  shellout.command(
    run: "sh",
    with: ["-c", "echo $API_URL $DB_HOST $PORT"],
    in: ".",
    opt: [shellout.SetEnvironment([
      #("API_URL", "https://api.example.com"),
      #("DB_HOST", "localhost:5432"),
      #("PORT", "8080")
    ])]
  )

  // Unset environment variables (set to empty string)
  shellout.command(
    run: "sh",
    with: ["-c", "echo HOME=$HOME PATH=$PATH"],
    in: ".",
    opt: [shellout.SetEnvironment([
      #("HOME", ""),
      #("PATH", "/custom/bin:/usr/bin")
    ])]
  )

  // Multiple SetEnvironment options (last value wins)
  shellout.command(
    run: "node",
    with: ["app.js"],
    in: ".",
    opt: [
      shellout.SetEnvironment([#("NODE_ENV", "development")]),
      shellout.SetEnvironment([#("NODE_ENV", "production"), #("PORT", "3000")])
    ]
  )
  // Result: NODE_ENV="production", PORT="3000"
}
```

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

### Control Process Exit Codes with Shellout

Source: https://context7.com/tynanbe/shellout/llms.txt

Manages program termination by returning specific exit codes based on command execution results. It uses `shellout.command` to run a command and `shellout.exit` to control the final exit status.

```gleam
import shellout
import gleam/io
import gleam/result

pub fn main() {
  shellout.command(run: "test", with: ["-f", "config.json"], in: ".", opt: [])
  |> result.map(fn(_) {
    io.println("Configuration file exists")
    0
  })
  |> result.map_error(fn(detail) {
    let #(status, message) = detail
    io.print_error("Configuration check failed\n")
    io.print_error(message)
    status
  })
  |> result.unwrap_both
  |> shellout.exit
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.