xfce-workspaces

Manage XFCE workspace names from the command line. Add, remove, rename, reorder, and reset workspaces using the xfconf backend — no need to dig through GUI settings.

Requirements

• XFCE desktop (uses xfconf-query and xfce4-panel)
• Node.js ≥ 18

Quick start

# Install globally
npm install -g xfce-workspaces

# Or run directly
npx xfce-workspaces list

Commands

list (default)

Show all workspaces with 1-based indices.

$ xfce-workspaces
Workspaces (4):
  1: Main
  2: Dev
  3: Chat
  4: Music

add <name>

Append a new workspace at the end.

$ xfce-workspaces add "Email"
Added workspace: "Email" (now 5 total)

insert <index> <name>

Insert a workspace at a specific position (1-based).

$ xfce-workspaces insert 2 "Notes"
Inserted workspace "Notes" at position 2 (now 6 total)

remove <index>

Remove a workspace by its index. Cannot remove the last remaining workspace.

$ xfce-workspaces remove 3
Removed workspace: "Chat" (now 5 total)

rename <index> <name>

Change the name of an existing workspace.

$ xfce-workspaces rename 2 "Code"
Renamed workspace 2: "Dev" → "Code"

rename-name <old-name> <new-name>

Rename the first workspace matching a given name.

$ xfce-workspaces rename-name "Dev" "Code"
Renamed workspace: "Dev" → "Code"

move <from> <to>

Reorder workspaces by moving a label from one position to another (1-based).

Note: This only renames/reorders the workspace labels. It does not move application windows from one workspace to another — that is out of scope for this tool.

$ xfce-workspaces move 4 1
Moved "Music" from position 4 → 1

set <names...>

Replace all workspace names in one go.

$ xfce-workspaces set Main Dev Chat Music
Set 4 workspace(s): "Main", "Dev", "Chat", "Music"

reset

Reset all names to XFCE defaults ("Workspace 1", "Workspace 2", …).

$ xfce-workspaces reset
Reset 4 workspace(s) to defaults.

refresh

Restart the panel so workspace labels pick up the latest changes.

$ xfce-workspaces refresh
Panel restarted.

Shell completion (zsh only)

One-time setup

# 1. Create the completions directory
mkdir -p ~/.zsh/completions

# 2. Write the completion script
xfce-workspaces completion > ~/.zsh/completions/_xfce-workspaces

Then add these lines to your ~/.zshrc (before any compinit call):

fpath=(~/.zsh/completions $fpath)
autoload -Uz compinit && compinit

Reload your shell and tab-completion works for all subcommands, options, workspace indices (queried dynamically), and workspace names.

Note: If your ~/.zshrc already has a compinit line, you only need to add the fpath line before it.

What gets completed

| Context | Completions | |---|---| | First argument | All subcommands (list, add, insert, …) | | Global flags | --help, --version, -h, -V | | Index arguments | 1–N (queried dynamically from current workspace count) | | Name arguments | Existing workspace names (for remove-name) |

How it works

The tool reads and writes to XFCE's configuration channel xfwm4 property /general/workspace_names. Changes are immediate — only the panel widget needs a restart (xfce4-panel -r) to visually reflect name changes.

Credits

• Commander.js — CLI framework
• Claude Code (deepseek-v4-pro[1m]) — AI-assisted development

License

MIT