CLI

Commands

workset new <name> [--path <path>] [--group <name> ...] [--repo <alias> ...]
workset ls
workset exec [<workspace>] [-- <command> [args...]]
workset hooks run -w <workspace> <repo> [--event <event>] [--reason <reason>] [--trust]
workset session start [<workspace>] [-- <command> [args...]] [--yes] [--attach]
workset session attach [<workspace>] [<name>] [--yes]
workset session stop [<workspace>] [<name>] [--yes]
workset session show [<workspace>] [<name>]
workset session ls [<workspace>]
workset version
workset --version
workset config show|set
workset repo alias ls|add|set|rm
workset repo add -w <workspace> <source> [--name] [--repo-dir]
workset repo ls -w <workspace>
workset repo rm -w <workspace> <name> [--delete-worktrees] [--delete-local]
workset status -w <workspace>
workset group ls|show|create|rm|add|remove
workset group apply -w <workspace> <name>
workset rm -w <name|path> [--delete]
workset completion <bash|zsh|fish|powershell>

Commands that operate on a workspace require an explicit target: pass -w <workspace> (name or path) or set defaults.workspace. Most flags should appear before positional args; -w/--workspace, --path, --group, --repo, --json, --plain, --config, and --verbose are also recognized after args.

GitHub auth

Workset uses your GitHub CLI session by default. In the desktop app, configure auth in Settings -> GitHub. For CLI-only usage, run:

gh auth login

To import a PAT without the GUI, set WORKSET_GITHUB_PAT in your environment. This stores the token in your OS keychain and switches auth mode to PAT.

WORKSET_GITHUB_PAT=ghp_... workset <command>

If gh is not on PATH (e.g., Nix), set the override in ~/.workset/config.yaml:

github:
  cli_path: /Users/you/.nix-profile/bin/gh

Safety checks

workset rm --delete and workset repo rm --delete-* run safety checks before removing files. Branches are treated as merged when the base branch already contains the same file contents (covers squash merges).

Sessions

workset session start starts a persistent session. By default it uses tmux if available, falls back to screen, and finally runs the command directly (exec backend). You can force a backend with --backend. Use --interactive/--pty only with --backend exec. Use --attach to immediately attach for tmux/screen (ignored for exec). To enable the built-in tmux/screen status line, set defaults.session_theme to workset in the global config (see Config).

workset session start demo -- zsh
workset session start demo --backend exec --interactive
workset session attach demo
workset session attach demo --yes
workset session show demo
workset session stop demo

Session metadata is stored locally in <workspace>/.workset/state.json.

Shell completion

Generate a completion script for your shell and source it:

# bash
workset completion bash > ~/.workset-completion.bash
source ~/.workset-completion.bash

# zsh
workset completion zsh > ~/.workset-completion.zsh
source ~/.workset-completion.zsh

# fish
workset completion fish > ~/.config/fish/completions/workset.fish

# powershell
workset completion powershell > workset.ps1
. ./workset.ps1

Completion includes hints for workspace names, group names, repo aliases, repo names within a workspace, and recorded session names when commands expect those positional args.

Output modes

workset new --json
workset new demo --plain
workset repo ls -w demo --json
workset status -w demo --json

CLI