A zero-dependency CLI tool for fuzzy searching and executing scripts within json. This is especially useful for exploring package.json fields with dot notation, and querying any JSON config files across monorepos and regular projects.
Traverse. Search. Execute. Fuzzy search filter your JSON files in style. 🤘
Why fjsf?
Stop typing full script names. Run fjsf init once, then just type npm run <TAB> and get an interactive tooltip with all your scripts. That's it. No more:
Typing npm run test:unit:watch:verbose
Opening package.json to remember script names
Scrolling through npm run help text
Context switching between editor and terminal
Type less. Run faster. Stay in flow.
Architecture
You start here. Lost. In a sea of monorepo workspaces trying to remember the script you need, you type fjsf and...
graph TD A[CLI Entry] --> B{Parse Mode} B -->|scripts| C[Scripts Mode] B -->|find| D[Find Mode] B -->|path| E[Path Mode] B -->|exec| F[Exec Mode] B -->|init| G[Shell Integration] B -->|help/quit| H[Exit] C --> I[Discover package.json] I --> J[Extract Scripts] J --> K[Fuzzy Search UI] K --> L[Execute Script] D --> M[Find All Files] M --> N[Flatten JSON] N --> O[Cache with mtime] O --> K E --> P[Load Single File] P --> N F --> Q[Read JSON] Q --> R[Validate Key] R --> L G --> S[Detect Shell] S --> T[Add Autocomplete] T --> U[Add Alias]
You end here. Just as lonely as before. But you executed that npm script you needed lickety-split!
Features
Shell Integration: Interactive tooltip when you type npm run <TAB> - fuzzy search scripts without leaving your terminal
Scripts Mode: Fuzzy search and execute npm scripts
Find Mode: Find all versions of a file across your repo and fuzzy search their JSON
Path Mode: Query a specific JSON file with fuzzy search
Exec Mode: Execute specific keys from JSON files directly
Smart Caching: JSON files are cached in memory with mtime validation for instant searches
Supports monorepos with workspaces (npm, pnpm, yarn, bun)
Automatic package manager detection
Zero dependencies - built with Bun
Interactive terminal UI with keyboard navigation
Shows which workspace and file each entry belongs to
Usage
Scripts Mode (Default)
Search and execute npm scripts from package.json:
fjsf # Search all package.json scriptsfjsf <package.json> # Search specific package.json file
Find Mode
Find all versions of a file across your repo and fuzzy search their JSON:
fjsf find <filename> # Find all files with this namefjsf f <filename> # Short form
Examples:
fjsf find package.json # Find all package.json files, search their contentsfjsf f tsconfig.json # Find all tsconfig.json filesfjsf find .eslintrc.json # Find all .eslintrc.json files
This will:
Find ALL files matching the name across your repo (including workspaces)
Flatten all their JSON into dot-notation paths
Let you fuzzy search across ALL fields from ALL found files
Show which file/workspace each result comes from
Search examples once in find mode:
Type react - View all React dependencies across all package.json files
Type version - Check versions across workspaces
Type compilerOptions.target - See all TS targets in tsconfigs
Type scripts.test - Find all test scripts
Path Mode
Query a specific JSON file (single file):
fjsf path <file> # Query a specific JSON filefjsf p <file> # Short form
Examples:
fjsf path ./tsconfig.json # Query single tsconfig.jsonfjsf p ./package.json # Query single package.jsonfjsf path ./config/app.json # Query any JSON file
This mode:
Loads ONE specific JSON file
Flattens it into dot-notation paths
Provides fuzzy search across all fields in that file
Exec Mode
Execute a specific key from a JSON file:
fjsf exec <file> <key> # Execute a key (scripts only)fjsf e <file> <key> # Short form
Examples:
fjsf exec package.json scripts.build # Run the build scriptfjsf e package.json scripts.test # Run the test scriptfjsf e package.json scripts.dev # Run the dev script
Note: Can only execute keys that start with scripts. and have string values.
Shell Integration
Never need to ask, "what was that npm script again?" again!
fjsf init
After setup, restart your shell. Now the magic happens:
npm run <TAB> # Interactive tooltip appears! # Shows: test, build, dev, lint... # Type to filter, arrow keys to navigate, Enter to runnpm run t<TAB> # Shows: test, test:watch, typecheck...pnpm run bui<TAB> # Shows: build, build:prod, build:dev...yarn run d<TAB> # Shows: dev, deploy, docs...bun run li<TAB> # Shows: lint, lint:fix...
How it works:
fjsf init creates a ~/.fjsf/ directory with shell-specific integration files and adds a single source line to your shell config (.zshrc, .bashrc, or .config/fish/config.fish).
Type npm run (or pnpm/yarn/bun) followed by optional partial script name
Press Tab to trigger the interactive tooltip
The tooltip appears right at your cursor showing fuzzy-matched scripts
Your partial input becomes the fuzzy search query
Arrow up/down to navigate matches
Press Enter to execute the selected script
The same fjsf interface you know, but inline in your terminal
Using with fzf-tab:
If you use fzf-tab or other completion enhancers, use native mode:
fjsf init --mode=native
Native mode integrates with your shell's completion system instead of hijacking Tab, allowing fzf-tab to display completions with its fuzzy finder UI.
Clean uninstall:
rm -rf ~/.fjsf# Then remove the "# fjsf" and source line from your shell config
Why this is awesome:
No context switching - stays in your terminal flow
Fuzzy matching means npm run t finds test, typecheck, test:watch
Works across all package managers (npm, pnpm, yarn, bun)
Shows workspace info in monorepos
Zero dependencies, instant performance
Supports: bash, zsh, fish
Customizing the key binding:
If Tab conflicts with other completions (like bun's native completions), you can change the key binding. After running fjsf init, edit the integration file in ~/.fjsf/:
Zsh (~/.fjsf/init.zsh):
bindkey '^I' _fjsf_widget # Change to your preferred key# Examples: '^F' (Ctrl+F), '^G' (Ctrl+G)
Bash (~/.fjsf/init.bash):
bind -x '"\\C-i": _fjsf_complete' # Change to your preferred key# Examples: '"\\C-f"' (Ctrl+F), '"\\C-g"' (Ctrl+G)
Fish (~/.fjsf/init.fish):
bind \t _fjsf_widget # Change to your preferred key# Examples: \cf (Ctrl+F), \cg (Ctrl+G)
Common key bindings: ^I/\t (Tab), ^F/\cf (Ctrl+F), ^G/\cg (Ctrl+G)
Help & Quit
fjsf help # Show helpfjsf h # Short formfjsf quit # Exit gracefullyfjsf q # Short form
Keyboard Controls
Type to search (fuzzy matching)
↑/↓ - Navigate through results
Enter - Execute selected script (scripts mode only)
q, Esc or Ctrl+C - Exit
Modes
Scripts Mode:
Discovers all package.json files in your repository
Extracts scripts from each package
Detects your package manager (bun, pnpm, yarn, or npm)
Provides fuzzy search across script names and workspaces
Executes scripts with the correct package manager command
Find Mode:
Searches your repository for all files matching the given filename
Flattens all found JSON files into searchable dot-notation paths
Caches JSON with mtime validation for fast subsequent searches
Provides fuzzy search across paths, keys, and values from ALL found files
Shows which file/workspace each entry belongs to
Exec Mode:
Reads the specified JSON file
Navigates to the specified key using dot notation
Validates the key is a script (starts with scripts.)
Executes the script with the appropriate package manager
Installation
npm
bun install -g fjsf
Homebrew
brew tap yowainwright/fjsfbrew install fjsf
Binary
Download the latest binary for your platform from the releases page:
Linux: fjsf-linux-x64
macOS (Intel): fjsf-darwin-x64
macOS (ARM): fjsf-darwin-arm64
Windows: fjsf-windows-x64.exe
Make the binary executable and move it to your PATH: