pm - VS Code Project Manager CLI

English | 日本語

I wanted to use VS Code Project Manager from the terminal too!

With the pm command, you can jump to any project registered in VS Code Project Manager.

Prerequisites

pm uses fzf for interactive project selection. Install it before setting up pm.

# macOS
brew install fzf

# Debian / Ubuntu
sudo apt install fzf

# Fedora
sudo dnf install fzf

# Arch Linux
sudo pacman -S fzf

Install

macOS/Linux (recommended)

curl -fsSL https://raw.githubusercontent.com/nozomiishii/pm/main/install.sh | bash

The pm binary is downloaded to ~/.pm/bin/pm, and the wrapper script that calls pm is placed at ~/.pm/pm.zsh. The .zshrc configuration is added automatically.

Restart your terminal or run source ~/.zshrc to start using pm.

npm

npm install -g @nozomiishii/pm

Uninstall

pm uninstall

Removes the binary, config files, and .zshrc entries.

Usage

pm --help

Usage: pm [options] [command]

Commands:
  cd [name]                    Jump to a project (fzf if no name given)
  ls                           List project names
  logo                         Display the pm logo
  uninstall                    Uninstall pm from your system

Options:
  --config <path>              Path to projects.json (or PM_CONFIG)
  --help                       Show this help
  --version                    Show version

Running `pm` without a command opens the fzf picker.

pm --help

pm

Opens fzf picker and jumps to the selected project.

pm

pm cd

Jumps to a project by name. Falls back to fzf if no name is given.

pm cd <name>

pm ls

Lists all project names.

pm ls

Configuration

The installer configures .zshrc automatically. For manual setup, add the following:

# (Optional) Path to projects.json. Defaults to the VS Code Project Manager path
export PM_CONFIG="$HOME/path/to/projects.json"

# Required
export PATH="$HOME/.pm/bin:$PATH"
source "$HOME/.pm/pm.zsh"

PM_CONFIG

pm reads project data from a projects.json file. If PM_CONFIG is omitted, it defaults to the VS Code Project Manager config path.

OS	Default path
macOS	~/Library/Application Support/Code/User/globalStorage/alefragnani.project-manager/projects.json
Linux	~/.config/Code/User/globalStorage/alefragnani.project-manager/projects.json
Windows	%APPDATA%/Code/User/globalStorage/alefragnani.project-manager/projects.json

You can also override the path temporarily with the --config flag:

pm --config ./projects.json ls

source "$HOME/.pm/pm.zsh"

The pm binary runs as a separate process, so cd inside the binary cannot change the calling shell's directory. The shell function loaded by source "$HOME/.pm/pm.zsh" runs cd in the current shell when the binary outputs a directory path.

# What pm.zsh does (simplified)
pm() {
  local output
  output="$(command pm "$@")"       # Run the binary
  [[ -d "$output" ]] && cd "$output"  # cd if output is a directory
}

This mechanism also provides tab completion for project names.

Tips

Launch with a Ghostty keybind

If you use Ghostty, add the following line to your config to launch pm with a single keybind.

keybind = super+alt+j=text:pm\n

Pressing super+alt+j sends pm + Enter to the current terminal, instantly opening the fzf picker.

The config file path differs by OS, so see the Configuration page in the Ghostty docs for the exact location.

Acknowledgments

pm is heavily inspired by these projects. Thank you so much for boosting my productivity.

• VS Code Project Manager — The extension that pioneered projects.json-based project switching. The best of the best.
• Raycast VSCode Project Manager — Use VS Code Project Manager from Raycast. Amazing.

License

MIT