Skip to content

Getting Started

Install

brew tap strantalis/homebrew-tap
brew install workset

Upgrade:

brew update
brew upgrade --cask workset

go install github.com/strantalis/workset/cmd/workset@latest

npm install -g @strantalis/workset@latest

Download the latest release from:
https://github.com/strantalis/workset/releases/latest

Tip

If you use go install, ensure $(go env GOPATH)/bin is on your PATH.

Desktop app (Wails)

Workset includes a desktop UI built with Wails (Go backend + Svelte frontend). The app lives in wails-ui/workset.

cd wails-ui/workset
wails3 dev
wails3 package

You'll need the Wails CLI plus Go and Node.js installed locally.

Create a workspace

workset new demo
workset repo add git@github.com:your/org-repo.git -w demo
workset status -w demo

workset group create platform
workset group add platform repo-alias
workset group apply -w demo platform

Set a default workspace

workset config set defaults.workspace demo

Tip

Once defaults.workspace is set, you can omit -w for most commands.

Start a session

workset session start demo -- zsh
workset session start demo --yes -- zsh
workset session attach demo
workset session attach demo --yes
workset session stop demo
workset session stop demo --yes

To force a backend:

workset session start demo --backend exec --interactive

GitHub authentication (desktop app)

Workset's desktop UI uses GitHub CLI by default. Install gh, run gh auth login, then open Settings -> GitHub to confirm you're connected.

If you prefer not to use the CLI, switch to Personal access token in Settings -> GitHub and save a token with access to the repos you need (including private repos). Workset stores the token in your OS keychain.

CLI-only usage (no GUI): set WORKSET_GITHUB_PAT to import a PAT into the keychain, or add a github.cli_path override in ~/.workset/config.yaml if gh is not on PATH.

Run a one-off command

workset exec demo -- ls

Enable shell completion (optional)

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

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

For fish or powershell, see the CLI page for the full set of commands.

Next steps

  • Read the Concepts page to understand workspaces, repo defaults, and templates.
  • Review the Config page to customize defaults and repo aliases.
  • Use the Command Index to find the right CLI call fast.
  • Explore the Desktop App if you prefer a GUI.