# libtmux:switch-client

- **Package:** libtmux
- **Language:** Common Lisp
- **Kind:** function
- **Source:** https://github.com/libtmux/libtmux-lisp/blob/c2e5fc4ed3befda21f45dfa5d5868c38fd138311/src/client-operations.lisp#L41
- **Public owner:** libtmux
- **Page:** https://libtmux.org/en/lisp/latest/reference/libtmux-switch-client/

```
(switch-client client target session &key update-environment (observe t) cancel-token timeout output-limit)
```

Switch captured terminal TARGET to SESSION and return a COMMAND-OUTCOME.
CLIENT is the connection owning both observations. UPDATE-ENVIRONMENT defaults
NIL, preserving the destination session environment; true applies tmux's
update-environment option using TARGET's environment. OBSERVE defaults true and
supplies a replacement attached-client through OUTCOME-VALUE. Earlier captures
stay unchanged; failed follow-up acquisition stays in OUTCOME-OBSERVATION-ERROR.
Blocks for preflight, dispatch and optional observation under shared limits.
Preflight checks the unique client name and PID/creation/tty fingerprint; tmux
does not atomically guard that fingerprint at dispatch. A changed or foreign
target signals STALE-TARGET. Operational failures retain their outcome; no
mutation is retried. Control clients are not supported by this operation.

See also: `libtmux:detach-client`, `libtmux:fetch-clients`, `libtmux:outcome-value`, `libtmux:refresh`.

## Parameters

- `client`
- `target`
- `session`
- `update-environment?`
- `observe?`
- `cancel-token?`
- `timeout?`
- `output-limit?`

## tmux command

The tmux commands behind `switch-client`.

- [`switch-client`](/en/tmux/latest/manual/switch-client/)

## tmux C API

The C declarations in tmux that implement these commands.

- [`cmd_switch_client_entry`](/en/tmux/latest/reference/c-variable-cmd_switch_client_entry/) (attribute)
- [`cmd_switch_client_exec`](/en/tmux/latest/reference/c-function-cmd-switch-client-c-cmd_switch_client_exec/) (function)

## Guides

Pages that discuss `switch-client`.

- [Explicit operations](/en/lisp/latest/guides/operations/)