diff --git a/src/content/docs/support-and-community/troubleshooting-and-support/logging-out-and-uninstalling.mdx b/src/content/docs/support-and-community/troubleshooting-and-support/logging-out-and-uninstalling.mdx index cce2b243..9cf0926d 100644 --- a/src/content/docs/support-and-community/troubleshooting-and-support/logging-out-and-uninstalling.mdx +++ b/src/content/docs/support-and-community/troubleshooting-and-support/logging-out-and-uninstalling.mdx @@ -90,21 +90,24 @@ If you're using Warp Preview, replace "Warp-Stable" with "Warp-Preview" in the c ```powershell # Remove Warp settings in the Windows Registry Remove-Item -Path "HKCU:\Software\Warp.dev\Warp" -Recurse -Force - # Remove Warp user files, logs, database, Codebase Context, and MCP logs + # Remove Warp settings, keybindings, logs, database, Codebase Context, and MCP logs Remove-Item -Path "$env:LOCALAPPDATA\warp\Warp" -Recurse -Force - # Remove Warp themes and launch configurations + # Remove Warp themes, tab configs, workflows, and launch configurations Remove-Item -Path "$env:APPDATA\warp\Warp" -Recurse -Force + # Remove MCP server config and bundled skills (shared across Stable and Preview) + Remove-Item -Path "$env:USERPROFILE\.warp" -Recurse -Force ``` **For Warp Preview users:** ```powershell # Remove Warp Preview settings in the Windows Registry - Remove-Item -Path "HKCU:\Software\Warp.dev\Warp-Preview" -Recurse -Force - # Remove Warp Preview user files, logs, database, Codebase Context, and MCP logs - Remove-Item -Path "$env:LOCALAPPDATA\warp\Warp-Preview" -Recurse -Force - # Remove Warp Preview themes and launch configurations - Remove-Item -Path "$env:APPDATA\warp\Warp-Preview" -Recurse -Force + Remove-Item -Path "HKCU:\Software\Warp.dev\WarpPreview" -Recurse -Force + # Remove Warp Preview settings, keybindings, logs, database, Codebase Context, and MCP logs + Remove-Item -Path "$env:LOCALAPPDATA\warp\WarpPreview" -Recurse -Force + # Remove Warp Preview themes, tab configs, workflows, and launch configurations + Remove-Item -Path "$env:APPDATA\warp\WarpPreview" -Recurse -Force + # Note: Removing $env:USERPROFILE\.warp also removes Stable's MCP config and skills. ``` @@ -126,12 +129,14 @@ If you're using Warp Preview, replace "Warp-Stable" with "Warp-Preview" in the c **Removing Warp settings, files, logs, and database** ```bash - # Remove Warp settings files + # Remove Warp settings and keybindings files rm -r ${XDG_CONFIG_HOME:-$HOME/.config}/warp-terminal - # Remove Warp user files, logs, database, Codebase Context, and MCP logs + # Remove Warp logs, database, Codebase Context, and MCP logs rm -r ${XDG_STATE_HOME:-$HOME/.local/state}/warp-terminal - # Remove Warp themes and launch configurations - rm -r ${XDG_STATE_HOME:-$HOME/.local/share}/warp-terminal + # Remove Warp themes, tab configs, workflows, and launch configurations + rm -r ${XDG_DATA_HOME:-$HOME/.local/share}/warp-terminal + # Remove MCP server config and bundled skills (shared across Stable and Preview) + rm -r $HOME/.warp ``` **For Warp Preview users:** @@ -150,12 +155,13 @@ If you're using Warp Preview, replace "Warp-Stable" with "Warp-Preview" in the c * Uninstall Warp Preview using the same package manager that you used to install it. ```bash - # Remove Warp Preview settings files + # Remove Warp Preview settings and keybindings files rm -r ${XDG_CONFIG_HOME:-$HOME/.config}/warp-terminal-preview - # Remove Warp Preview user files, logs, database, Codebase Context, and MCP logs + # Remove Warp Preview logs, database, Codebase Context, and MCP logs rm -r ${XDG_STATE_HOME:-$HOME/.local/state}/warp-terminal-preview - # Remove Warp Preview themes and launch configurations - rm -r ${XDG_STATE_HOME:-$HOME/.local/share}/warp-terminal-preview + # Remove Warp Preview themes, tab configs, workflows, and launch configurations + rm -r ${XDG_DATA_HOME:-$HOME/.local/share}/warp-terminal-preview + # Note: Removing $HOME/.warp also removes Stable's MCP config and skills. ``` diff --git a/src/content/docs/terminal/appearance/custom-themes.mdx b/src/content/docs/terminal/appearance/custom-themes.mdx index 6a083b48..1b6beeb5 100644 --- a/src/content/docs/terminal/appearance/custom-themes.mdx +++ b/src/content/docs/terminal/appearance/custom-themes.mdx @@ -170,8 +170,12 @@ foreground: '#839496' ############################################################### SEE BELOW background_image: - # the path is relative to ~/.warp/themes/ - # the full path to the picture is: ~/.warp/themes/warp.jpg + # The path is relative to your platform's themes directory: + # macOS: ~/.warp/themes/ + # Windows: %APPDATA%\warp\Warp\data\themes\ + # Linux: ${XDG_DATA_HOME:-$HOME/.local/share}/warp-terminal/themes/ + # For example, on macOS the full path to the picture below is: + # ~/.warp/themes/warp.jpg path: warp.jpg # the opacity value is required and can range from 0-100 opacity: 60 diff --git a/src/content/docs/terminal/settings/file-locations.mdx b/src/content/docs/terminal/settings/file-locations.mdx new file mode 100644 index 00000000..628b4131 --- /dev/null +++ b/src/content/docs/terminal/settings/file-locations.mdx @@ -0,0 +1,163 @@ +--- +title: File and folder locations +description: >- + Reference for where Warp stores config, themes, tab configs, settings, + keybindings, logs, and other files on macOS, Windows, and Linux. +sidebar: + label: "File locations" +--- +import { Tabs, TabItem } from '@astrojs/starlight/components'; + +This reference lists every directory and file Warp reads or writes on disk, organized by platform and Warp release channel. Use it when you want to back up your config, edit a file directly, debug a missing setting, or symlink Warp's configuration from another shell (for example, [WSL](#symlinking-warps-config-from-wsl)). + +## How Warp organizes files + +Warp groups its files into three buckets, and the directory each bucket maps to depends on your platform. Knowing the bucket explains why two files that feel related (themes and settings, for example) live in different roots on Windows and Linux but the same root on macOS. + +* **Portable user data** - Files you'd want to copy to a new machine, such as themes, tab configs, workflows, and launch configurations. +* **Non-portable config** - Local-only configuration that doesn't make sense to roam, such as `settings.toml` and `keybindings.yaml`. +* **Non-portable state** - Machine-specific state like logs, the local database, and the Codebase Context index. + +In addition, a small set of cross-cutting files always live in your home directory on every platform — currently MCP server config and bundled skills. Both Stable and Preview share the same `~/.warp/` directory for these files (Preview does **not** use `~/.warp-preview/` for MCP config or skills, so installing Preview alongside Stable shares the same MCP servers and skills). Other release channels do use a channel-suffixed directory — for example, `~/.warp-oss/` for OSS. These files sit in the home directory so they're easy to reference from shell config, version control, or other tools. + +## File locations by platform + +The tables below cover the **Stable** channel. For **Preview**, see [Preview channel paths](#preview-channel-paths). + + + + On macOS, Stable keeps every Warp-authored file under `~/.warp/`. Preview uses `~/.warp-preview/` for everything except the cross-platform `~/.warp/` carve-out. + + **Portable user data** + + * **Themes** - `~/.warp/themes/` + * **Tab configs** - `~/.warp/tab_configs/` + * **Default tab configs** (shipped, user-editable) - `~/.warp/default_tab_configs/` + * **Workflows** (local) - `~/.warp/workflows/` + * **Launch configurations** - `~/.warp/launch_configurations/` + + **Non-portable config** + + * **Settings file** - `~/.warp/settings.toml` + * **Keybindings** - `~/.warp/keybindings.yaml` + * **User preferences** (legacy) - macOS `defaults` domain `dev.warp.Warp-Stable` + + **Non-portable state** + + * **Logs** - `~/Library/Logs/warp.log*` + * **Crash reports** - `~/Library/Logs/DiagnosticReports/` (Warp `.ips` files) + * **Database, Codebase Context index, MCP logs** - `~/Library/Group Containers/2BBY89MBSN.dev.warp/Library/Application Support/dev.warp.Warp-Stable/` + + **Cross-platform (always in your home directory)** + + * **MCP server config** - `~/.warp/.mcp.json` + * **Bundled skills** - `~/.warp/skills/` + * **Agent config** - `~/.agents/` + + + On Windows, Warp follows the platform conventions used by the [`directories`](https://docs.rs/directories) crate, which splits user data across `%APPDATA%` (Roaming) and `%LOCALAPPDATA%` (Local). Themes and tab configs are portable and live in Roaming, while settings, logs, and the local database are machine-specific and live in Local. Two separate `data\` directories exist as a result — one under each root — so check the full path when locating files. + + **Portable user data** (`%APPDATA%\warp\Warp\data\`, Roaming) + + * **Themes** - `%APPDATA%\warp\Warp\data\themes\` + * **Tab configs** - `%APPDATA%\warp\Warp\data\tab_configs\` + * **Default tab configs** (shipped, user-editable) - `%APPDATA%\warp\Warp\data\default_tab_configs\` + * **Workflows** (local) - `%APPDATA%\warp\Warp\data\workflows\` + * **Launch configurations** - `%APPDATA%\warp\Warp\data\launch_configurations\` + + **Non-portable config** (`%LOCALAPPDATA%\warp\Warp\config\`) + + * **Settings file** - `%LOCALAPPDATA%\warp\Warp\config\settings.toml` + * **Keybindings** - `%LOCALAPPDATA%\warp\Warp\config\keybindings.yaml` + * **User preferences** (legacy) - Windows Registry key `HKCU:\Software\Warp.dev\Warp` + + **Non-portable state** (`%LOCALAPPDATA%\warp\Warp\data\`) + + * **Logs** - `%LOCALAPPDATA%\warp\Warp\data\logs\warp.log*` + * **Database, Codebase Context index, MCP logs** - other subdirectories under `%LOCALAPPDATA%\warp\Warp\data\` + * **Cache** - `%LOCALAPPDATA%\warp\Warp\cache\` + + **Cross-platform (always in your home directory)** + + * **MCP server config** - `%USERPROFILE%\.warp\.mcp.json` + * **Bundled skills** - `%USERPROFILE%\.warp\skills\` + * **Agent config** - `%USERPROFILE%\.agents\` + + + On Linux, Warp follows the [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html). Each path below uses the standard XDG environment variable with its default fallback. + + **Portable user data** (`${XDG_DATA_HOME:-$HOME/.local/share}/warp-terminal/`) + + * **Themes** - `${XDG_DATA_HOME:-$HOME/.local/share}/warp-terminal/themes/` + * **Tab configs** - `${XDG_DATA_HOME:-$HOME/.local/share}/warp-terminal/tab_configs/` + * **Default tab configs** (shipped, user-editable) - `${XDG_DATA_HOME:-$HOME/.local/share}/warp-terminal/default_tab_configs/` + * **Workflows** (local) - `${XDG_DATA_HOME:-$HOME/.local/share}/warp-terminal/workflows/` + * **Launch configurations** - `${XDG_DATA_HOME:-$HOME/.local/share}/warp-terminal/launch_configurations/` + + **Non-portable config** (`${XDG_CONFIG_HOME:-$HOME/.config}/warp-terminal/`) + + * **Settings file** - `${XDG_CONFIG_HOME:-$HOME/.config}/warp-terminal/settings.toml` + * **Keybindings** - `${XDG_CONFIG_HOME:-$HOME/.config}/warp-terminal/keybindings.yaml` + + **Non-portable state** (`${XDG_STATE_HOME:-$HOME/.local/state}/warp-terminal/`) + + * **Logs** - `${XDG_STATE_HOME:-$HOME/.local/state}/warp-terminal/warp.log*` + * **Database, Codebase Context index, MCP logs** - other files under `${XDG_STATE_HOME:-$HOME/.local/state}/warp-terminal/` + * **Cache** - `${XDG_CACHE_HOME:-$HOME/.cache}/warp-terminal/` + + **Cross-platform (always in your home directory)** + + * **MCP server config** - `~/.warp/.mcp.json` + * **Bundled skills** - `~/.warp/skills/` + * **Agent config** - `~/.agents/` + + + +## Preview channel paths + +Preview uses a separate set of directories so it never overwrites your Stable config: + +* **macOS** - Replace `~/.warp/` with `~/.warp-preview/` and `Warp-Stable` with `Warp-Preview` in the macOS paths above. The cross-platform `~/.warp/` carve-out (MCP config, skills) is shared with Stable and does not get a `-preview` suffix. +* **Windows** - Replace `\warp\Warp\` with `\warp\WarpPreview\` in every path. Logs become `%LOCALAPPDATA%\warp\WarpPreview\data\logs\warp_preview.log*`. The Registry key is `HKCU:\Software\Warp.dev\WarpPreview` (no hyphen — `Warp-Preview` is the macOS bundle identifier, not the Windows app name). The cross-platform `%USERPROFILE%\.warp\` carve-out (MCP config, skills) is shared with Stable. +* **Linux** - Append `-preview` to each `warp-terminal` directory (for example, `~/.config/warp-terminal-preview/settings.toml`). Logs become `${XDG_STATE_HOME:-$HOME/.local/state}/warp-terminal-preview/warp_preview.log*`. The cross-platform `~/.warp/` carve-out (MCP config, skills) is shared with Stable. + +## Symlinking Warp's config from WSL + +If you run Warp on Windows and also use WSL, you can share Warp's config with your WSL `$HOME` so that tools running inside WSL can read the same themes, tab configs, settings, MCP servers, and agent config. WSL `$HOME` (typically `/home//`) is a separate Linux filesystem from your Windows profile (`%USERPROFILE%`, typically `C:\Users\\`), so `~/.warp/` and `~/.agents/` inside WSL are **not** automatically the same as the Windows-side directories with those names — every Warp directory you want to share needs its own symlink that points back to the Windows path. + +Your WSL Linux username (`$USER`) is also usually different from your Windows account name, so don't assume `/mnt/c/Users/$USER` resolves to your Windows profile. Resolve `%USERPROFILE%` through `cmd.exe` and convert it with `wslpath` instead, then run the symlinks from a WSL shell: + +```bash +# Resolve the Windows %USERPROFILE% (e.g. C:\Users\Alex) into a WSL path +# (e.g. /mnt/c/Users/Alex). Avoids hard-coding the Windows username or +# assuming it matches your WSL $USER. +WIN_HOME=$(wslpath "$(cmd.exe /C 'echo %USERPROFILE%' 2>/dev/null | tr -d '\r')") + +# Portable data: themes, tab configs, workflows, launch configurations (Roaming AppData). +ln -s "$WIN_HOME/AppData/Roaming/warp/Warp/data" ~/.warp-windows-data + +# Local config: settings.toml, keybindings.yaml (Local AppData). +ln -s "$WIN_HOME/AppData/Local/warp/Warp/config" ~/.warp-windows-config + +# Cross-platform carve-outs that live under Windows %USERPROFILE%: +# MCP server config and bundled skills (Windows-side ~/.warp). +ln -s "$WIN_HOME/.warp" ~/.warp + +# Agent config (Windows-side ~/.agents). +ln -s "$WIN_HOME/.agents" ~/.agents +``` + +If `~/.warp` or `~/.agents` already exist in WSL, remove or back them up first — otherwise `ln` will create the link inside the existing directory instead of replacing it. If you prefer to hard-code the Windows username instead of using `wslpath`, find it from WSL with `cmd.exe /C 'echo %USERNAME%' 2>/dev/null | tr -d '\r'` and replace `$WIN_HOME` above with `/mnt/c/Users/`. + +:::note +Warp on Windows does not currently load config from `~/.warp/tab_configs/` or `~/.warp/themes/` — those paths only work on macOS. If you have config files in those home-directory paths from a different machine, copy or symlink them into the Windows `%APPDATA%\warp\Warp\data\` directory before they take effect. +::: + +## Related pages + +* [Settings file](/terminal/settings/) - Format, hot-reload behavior, and common examples for `settings.toml`. +* [All settings reference](/terminal/settings/all-settings/) - Every setting available in `settings.toml`, organized by section. +* [Keyboard shortcuts](/getting-started/keyboard-shortcuts/) - How to view and remap shortcuts, including the `keybindings.yaml` file. +* [Tab Configs](/terminal/windows/tab-configs/) - TOML format and schema for tab config files in `tab_configs/`. +* [Custom themes](/terminal/appearance/custom-themes/) - YAML format and image conventions for themes in `themes/`. +* [Uninstalling Warp](/support-and-community/troubleshooting-and-support/logging-out-and-uninstalling/) - Commands for removing all of these files when uninstalling. diff --git a/src/content/docs/terminal/settings/index.mdx b/src/content/docs/terminal/settings/index.mdx index d01ee9b9..90173895 100644 --- a/src/content/docs/terminal/settings/index.mdx +++ b/src/content/docs/terminal/settings/index.mdx @@ -38,6 +38,8 @@ Depending on your platform and Warp release channel, `settings.toml` is located * Stable — `%LOCALAPPDATA%\warp\Warp\config\settings.toml` * Preview — `%LOCALAPPDATA%\warp\WarpPreview\config\settings.toml` +For the locations of every other Warp file — themes, tab configs, keybindings, logs, the local database, and more — see [File and folder locations](/terminal/settings/file-locations/). + ## Settings file format The file uses [TOML v1.1](https://toml.io/en/v1.1.0) syntax. Settings are organized into **sections** (TOML tables) that group related options — for example, `[appearance.text]` contains font settings and `[agents.profiles]` contains agent permission settings. @@ -170,6 +172,7 @@ Confirm you're editing the correct file for your platform and Warp release chann ## Related pages * [All settings reference](/terminal/settings/all-settings/) — Complete list of every available setting with descriptions, types, and defaults +* [File and folder locations](/terminal/settings/file-locations/) — Where Warp stores every config, data, and state file across macOS, Windows, and Linux * [Customizing Warp](/getting-started/quickstart/customizing-warp/) — Overview of all customization options * [Custom themes](/terminal/appearance/custom-themes/) — Create and load custom YAML or Base16 themes * [Keyboard shortcuts](/getting-started/keyboard-shortcuts/) — Customize keybindings diff --git a/src/content/docs/terminal/windows/tab-configs.mdx b/src/content/docs/terminal/windows/tab-configs.mdx index 13106e5d..9fa8a34c 100644 --- a/src/content/docs/terminal/windows/tab-configs.mdx +++ b/src/content/docs/terminal/windows/tab-configs.mdx @@ -4,6 +4,7 @@ description: >- Tab Configs let you define reusable tab setups — including directory, startup commands, pane layout, shell, and theme — in a simple TOML file. --- +import { Tabs, TabItem } from '@astrojs/starlight/components'; import VideoEmbed from '@components/VideoEmbed.astro'; Tab Configs let you define reusable tab setups — including directory, startup commands, pane layout, shell, and theme — in a simple TOML file. Select a Tab Config from the `+` menu to open a fully configured tab with a single click. @@ -12,18 +13,34 @@ Tab Configs let you define reusable tab setups — including directory, startup ## How Tab Configs work -Each Tab Config is a `.toml` file stored in `~/.warp/tab_configs/`. Every file defines a single tab layout with optional pane splits, startup commands, and parameterized inputs. Tab Configs appear in the `+` menu alongside your existing tabs, so you can launch a preconfigured workspace instantly. +Each Tab Config is a `.toml` file stored in Warp's `tab_configs` directory. Every file defines a single tab layout with optional pane splits, startup commands, and parameterized inputs. Tab Configs appear in the `+` menu alongside your existing tabs, so you can launch a preconfigured workspace instantly. + +The `tab_configs` directory lives in a different location on each platform: + + + + `~/.warp/tab_configs/` (Stable) or `~/.warp-preview/tab_configs/` (Preview). + + + `%APPDATA%\warp\Warp\data\tab_configs\` (Stable) or `%APPDATA%\warp\WarpPreview\data\tab_configs\` (Preview). + + + `${XDG_DATA_HOME:-$HOME/.local/share}/warp-terminal/tab_configs/` (Stable) or `${XDG_DATA_HOME:-$HOME/.local/share}/warp-terminal-preview/tab_configs/` (Preview). + + + +For the full list of Warp file locations, see [File and folder locations](/terminal/settings/file-locations/). ## Creating a Tab Config ### From the UI 1. Click the **+** button in the tab bar to open the new-tab menu. -2. Click **+ New tab config**. Warp creates a new `.toml` file in `~/.warp/tab_configs/` and opens it for editing. +2. Click **+ New tab config**. Warp creates a new `.toml` file in the `tab_configs` directory and opens it for editing. ### Manually -1. Create a new `.toml` file in `~/.warp/tab_configs/`. Use snake_case for the file name (e.g., `dev_server.toml`). +1. Create a new `.toml` file in the `tab_configs` directory shown above. Use snake_case for the file name (e.g., `dev_server.toml`). 2. Define the tab layout using the schema below, then save the file. The new config appears in the `+` menu automatically. ### Save an existing tab as a Tab Config diff --git a/src/sidebar.ts b/src/sidebar.ts index 4fdd0297..f64c9e80 100644 --- a/src/sidebar.ts +++ b/src/sidebar.ts @@ -145,6 +145,7 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [ items: [ { slug: 'terminal/settings', label: 'Overview' }, { slug: 'terminal/settings/all-settings', label: 'All settings reference' }, + { slug: 'terminal/settings/file-locations', label: 'File locations' }, ], }, {