> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/wezterm/wezterm/llms.txt
> Use this file to discover all available pages before exploring further.

# wezterm set-working-directory

> Notify the terminal of the current working directory using OSC 7

The `set-working-directory` command emits an OSC 7 escape sequence to advise the terminal of the current working directory.

## Synopsis

```bash theme={null}
wezterm set-working-directory [OPTIONS] [CWD] [HOST]
```

## Description

This command emits an OSC 7 (Operating System Command 7) escape sequence that informs the terminal emulator about the current working directory. This is useful for:

* Enabling semantic terminal features based on directory context
* Allowing new tabs/panes to open in the same directory
* Integration with shell prompts and directory-aware tools
* Working with remote sessions over SSH

Many shells can be configured to automatically emit this sequence, but this command provides manual control when needed.

## Arguments

<ParamField path="CWD" type="path">
  The directory to specify.

  If omitted, will use the current directory of the process itself (equivalent to `$PWD` or `$(pwd)`).

  **Example:**

  ```bash theme={null}
  wezterm set-working-directory /home/user/projects
  wezterm set-working-directory ~/Documents
  ```
</ParamField>

<ParamField path="HOST" type="string">
  The hostname to use in the constructed `file://` URL.

  If omitted, the system hostname will be used. This is particularly useful when working on remote systems via SSH.

  **Example:**

  ```bash theme={null}
  wezterm set-working-directory /home/user server.example.com
  ```
</ParamField>

## Options

<ParamField path="--tmux-passthru" type="enum">
  How to manage passing the escape sequence through to tmux.

  **Possible values:**

  * `disable` - Don't use tmux passthrough
  * `enable` - Always use tmux passthrough
  * `detect` - Automatically detect if running in tmux (default)

  When running inside tmux, the OSC 7 sequence needs special handling to pass through tmux to the outer terminal.

  **Example:**

  ```bash theme={null}
  wezterm set-working-directory --tmux-passthru enable
  ```
</ParamField>

## Examples

### Set to current directory

```bash theme={null}
wezterm set-working-directory
```

This uses the current working directory (`$PWD`).

### Set to specific directory

```bash theme={null}
wezterm set-working-directory /home/user/projects/myapp
```

### Set with custom hostname

```bash theme={null}
wezterm set-working-directory /var/www production-server
```

This creates a URL like: `file://production-server/var/www`

### Use in shell prompt

Add to your `.bashrc` or `.zshrc`:

```bash theme={null}
# Bash
function set_wezterm_cwd() {
  wezterm set-working-directory
}
PROMPT_COMMAND="set_wezterm_cwd;$PROMPT_COMMAND"
```

```zsh theme={null}
# Zsh
function set_wezterm_cwd() {
  wezterm set-working-directory
}
precmd_functions+=(set_wezterm_cwd)
```

### Use in fish shell

Add to your `config.fish`:

```fish theme={null}
function __wezterm_set_cwd --on-variable PWD
  wezterm set-working-directory
end
```

### Inside tmux

```bash theme={null}
wezterm set-working-directory --tmux-passthru enable
```

### With directory change

```bash theme={null}
cd ~/projects/myapp && wezterm set-working-directory
```

## Integration with Shells

### Bash

Add to `~/.bashrc`:

```bash theme={null}
if [ -n "$WEZTERM_EXECUTABLE" ]; then
  function _wezterm_set_cwd() {
    wezterm set-working-directory 2>/dev/null
  }
  PROMPT_COMMAND="_wezterm_set_cwd;${PROMPT_COMMAND}"
fi
```

### Zsh

Add to `~/.zshrc`:

```zsh theme={null}
if [[ -n "$WEZTERM_EXECUTABLE" ]]; then
  function _wezterm_set_cwd() {
    wezterm set-working-directory 2>/dev/null
  }
  autoload -Uz add-zsh-hook
  add-zsh-hook precmd _wezterm_set_cwd
fi
```

### Fish

Add to `~/.config/fish/config.fish`:

```fish theme={null}
if set -q WEZTERM_EXECUTABLE
  function __wezterm_set_user_var_on_cwd --on-variable PWD
    wezterm set-working-directory 2>/dev/null
  end
  __wezterm_set_user_var_on_cwd
end
```

### PowerShell

Add to your PowerShell profile:

```powershell theme={null}
if ($env:WEZTERM_EXECUTABLE) {
  function Set-WeztermCwd {
    wezterm set-working-directory 2>$null
  }
  
  # Call on prompt
  function Prompt {
    Set-WeztermCwd
    # Your normal prompt here
  }
}
```

## OSC 7 Sequence Format

The OSC 7 sequence has the format:

```
\033]7;file://HOSTNAME/PATH\033\\
```

For example:

```
\033]7;file://laptop/home/user/projects\033\\
```

WezTerm automatically:

1. Converts the provided path to an absolute path
2. URL-encodes special characters
3. Constructs the proper `file://` URL
4. Emits the OSC 7 sequence

## Use Cases

### New tabs inherit directory

When you open a new tab in WezTerm, it can automatically use the current working directory of the active pane:

```lua theme={null}
-- In wezterm.lua
return {
  default_cwd = wezterm.home_dir,
}
```

With OSC 7 properly set, new tabs will open in the actual current directory.

### SSH sessions

When working on a remote server via SSH:

```bash theme={null}
ssh user@remote
cd /var/log
wezterm set-working-directory /var/log remote-server
```

Now WezTerm knows you're in `/var/log` on `remote-server`.

### Directory-aware features

Some WezTerm features use the current directory:

* File path completion
* Quick file opening
* Status bar showing current directory

### Semantic zones

WezTerm can use directory information for semantic zones, allowing you to:

* Navigate between command outputs
* Select entire commands with their output
* Copy commands without the output

## Troubleshooting

### OSC 7 not working in tmux

Make sure to use:

```bash theme={null}
wezterm set-working-directory --tmux-passthru detect
```

Or configure tmux to pass through escape sequences:

```tmux theme={null}
set -g allow-passthrough on
```

### Directory not updating in new tabs

1. Check that your shell is calling `set-working-directory`
2. Verify the escape sequence is being emitted:
   ```bash theme={null}
   wezterm set-working-directory && echo "Done"
   ```
3. Check your WezTerm configuration

### Spaces in directory names

The command handles spaces automatically:

```bash theme={null}
wezterm set-working-directory "/home/user/My Documents"
```

## Manual OSC 7 Emission

If you prefer not to use the `wezterm` command, you can emit OSC 7 directly:

```bash theme={null}
# Bash/Zsh
printf '\033]7;file://%s%s\033\\' "$HOSTNAME" "$PWD"
```

However, using `wezterm set-working-directory` is recommended as it handles:

* URL encoding
* Hostname detection
* Tmux passthrough
* Path normalization

## Related

* [wezterm start](/cli/start) - Start terminal with specific directory
* [wezterm imgcat](/cli/imgcat) - Display images in terminal
* WezTerm Shell Integration Documentation