pj-cli 0.2.2

Project launcher CLI with fuzzy matching
pj-cli-0.2.2 is not a library.

pj

A fast, terminal-based project launcher with fuzzy matching. Quickly navigate between projects, organize them with tags, and launch your editor with a single command.

Features

  • Fuzzy Matching: Interactive TUI with real-time filtering powered by skim
  • Frecency Ranking: Smart ordering based on frequency and recency of access
  • Hierarchical Tags: Organize projects with nested tags (e.g., work/backend)
  • Shell Integration: Automatic directory changing for bash, zsh, fish, and sh
  • Editor Integration: Launch your preferred editor when selecting a project
  • Git Integration: Auto-initialize git repositories when adding projects
  • GitHub Integration: Optionally create GitHub remotes via the gh CLI

Installation

Homebrew

brew install alceal/tap/pj

Cargo

cargo install pj-cli

From Source

git clone https://github.com/alceal/pj
cd pj
cargo install --path .

Quick Start

Run the interactive setup wizard:

pj --init

This will configure your shell, editor, and preferences. The wizard detects your shell automatically and installs the necessary shell function for directory changing.

Add your first project:

cd ~/projects/my-app
pj -a -t work,rust

Select and open a project:

pj

Commands

Command Description
pj Open interactive project selector
pj <filter> Filter projects by terms (auto-selects if single match)
pj --init Run the setup wizard
pj --config Interactive configuration editor
pj --list Display all tracked projects with status
pj -a / pj --add Add current directory as a project
pj --rm Remove projects interactively
pj --rm-missing Remove all projects with missing paths

Options

Option Description
-t, --tags <TAGS> Add tags to project(s) or filter when adding
--rm-tags <TAGS> Remove tags from project(s)
-e, --editor <EDITOR> Override the configured editor
--no-editor Skip opening editor (just cd if enabled)
--cd / --no-cd Override directory change behavior

Examples

# Add project with multiple tags
pj -a -t work/backend,rust,api

# Filter projects by name (auto-selects if single match)
pj rust
pj my-project

# Open project with a different editor
pj -e zed

# List all tracked projects
pj --list

# Remove all projects with missing paths
pj --rm-missing

# Edit configuration interactively
pj --config

Configuration

Configuration is stored in ~/.pj/config.toml:

editor = "code"           # Editor command to launch
cd_on_select = true       # Change directory when selecting a project
git_init_on_add = true    # Initialize git when adding a project
gh_create_on_add = false  # Create GitHub remote when adding (requires gh CLI)

Project data is stored in ~/.pj/projects.json.

Shell Integration

When cd_on_select is enabled, pj installs a shell function that wraps the binary to enable directory changing. The setup wizard handles this automatically for:

  • Bash: Added to ~/.bashrc
  • Zsh: Added to ~/.zshrc
  • Fish: Added to ~/.config/fish/config.fish
  • POSIX sh: Added to ~/.profile

Tag Hierarchy

Tags support hierarchical organization using / as a separator:

# Add with hierarchical tags
pj -a -t work/frontend/dashboard

# Filter by tag in selection
pj work           # Fuzzy matches against path and tags
pj work/frontend  # More specific filter

License

This project is licensed under the MIT License. See the LICENSE.txt file for details.