# Read and change options

Source: https://libtmux.org/en/powershell/latest/guides/options/

> Read and change options: LibTmux documentation.

Pass a native server, session, window or pane to select its option table.
Use `-Scope` to override the table and `-Global` for that scope's global
defaults. For example, a server handle with `-Scope Session -Global`
addresses global session defaults. Choose the endpoint explicitly with
[New-TmuxServer](https://libtmux.org/en/powershell/latest/reference/libtmux-new-tmuxserver/).

Read the effective key mode from a previously selected `$session`:

<!-- example: options.read -->
```powershell
$session | Get-TmuxOption -Name 'status-keys' -IncludeInherited
```

Each result is a native [`TmuxOption`](<https://libtmux.org/en/csharp/latest/reference/libtmux-tmuxoption/>). Its [`Name`][tmuxoption-name],
[`Index`][tmuxoption-index], [`Inherited`](<https://libtmux.org/en/csharp/latest/reference/libtmux-tmuxoption-inherited/>) and [`Value`][tmuxoption-value]
describe what tmux reported. Omit `-Name` to list a table. A normal read lists
local values; `-IncludeInherited` adds inherited values. `-Quiet` makes a
missing option produce no rows. [`Where-Object`](<https://learn.microsoft.com/powershell/module/microsoft.powershell.core/where-object?view=powershell-7.4>) filters returned rows locally.

Store a user option and return the value tmux actually stored:

<!-- example: options.set -->
```powershell
$session | Set-TmuxOption -Name '@project' -Value 'api' -PassThru
```

`-PassThru` emits a native [`TmuxOptionValue`](<https://libtmux.org/en/csharp/latest/reference/libtmux-tmuxoptionvalue/>); its [`Raw`][tmuxoptionvalue-raw],
[`Boolean`][tmuxoptionvalue-boolean], [`Integer`](<https://libtmux.org/en/csharp/latest/reference/libtmux-tmuxoptionvalue-integer/>) and [`State`](<https://libtmux.org/en/csharp/latest/reference/libtmux-tmuxoptionvalue-state/>) fields preserve
tmux's interpretation. Without it, setting emits no success output. `-Append`
and `-ExpandFormat` return the stored result, not just the supplied argument.
`-PreventOverwrite` asks tmux to refuse replacement and can produce an error.

Remove a previously stored user option:

<!-- example: options.remove -->
```powershell
$session | Remove-TmuxOption -Name '@scratch'
```

Removing a built-in override restores inheritance. An empty string is a
stored value, so setting `''` does not remove an option. Indexed names such
as `command-alias[40]` read, set or remove that specific array entry;
listing the base name preserves sparse indices. tmux expands formats in
option names, so `#` is not guaranteed literal.

Set and Remove support `-WhatIf` and `-Confirm`; previews contact no server.
Errors retain the original core exception and owner. `-ErrorAction Continue`
permits later owners; [`Stop`][erroraction-stop] terminates the pipeline.
Cancellation cannot undo a dispatched mutation. Readback does not make a
mutation atomic with other clients.

[tmuxoption-name]: https://libtmux.org/en/csharp/latest/reference/libtmux-tmuxoption-name/
[tmuxoption-index]: https://libtmux.org/en/csharp/latest/reference/libtmux-tmuxoption-index/
[tmuxoption-value]: https://libtmux.org/en/csharp/latest/reference/libtmux-tmuxoption-value/
[tmuxoptionvalue-raw]: https://libtmux.org/en/csharp/latest/reference/libtmux-tmuxoptionvalue-raw/
[tmuxoptionvalue-boolean]: https://libtmux.org/en/csharp/latest/reference/libtmux-tmuxoptionvalue-boolean/
[erroraction-stop]: https://learn.microsoft.com/en-us/dotnet/api/system.management.automation.actionpreference#system-management-automation-actionpreference-stop