Pathem
Browse all guides

Use Pathem from the command line

Install the bundled command-line handoff and use open, reveal, or preview with an existing path.

Make the bundled CLI available

  1. Use a packaged Pathem.app containing the command-line helper. A bare source-run process may not include the installable bundled CLI.
  2. Open Preferences > Integrations. In the Terminal command row, choose Install. Read the resulting Installed at path to see which writable directory was selected.
  3. Open a new terminal or refresh your shell's command lookup. Run command -v pathem to check which executable will be used.
  4. If the command cannot be installed, inspect the reported directory or conflicting file. Do not delete an unrelated executable merely to make room for Pathem's link.
  5. If a user-owned directory such as ~/.local/bin is chosen, ensure your own shell includes that directory in PATH. Do not add broad writable locations to PATH just to avoid understanding the error.

Choose the correct handoff

Open navigates into a directory, reveal selects an item in its parent folder, and preview opens the read-only viewer. Each command takes one existing path; relative paths are resolved from the shell's current directory.

  1. Replace the example filename with a harmless file that actually exists. Quote paths containing spaces.
  2. Use reveal when your editor should select a file in its folder rather than merely open its parent directory.
  3. Inspect the folder or viewer that appears in Pathem. A successful handoff is not a file copy and does not create a missing path.
  4. For editor integrations, pass the selected file's real path through the integration's documented placeholder syntax. Test one file with spaces before configuring a broader action.
pathem open "$HOME/Downloads"
pathem reveal "$HOME/Downloads/example.txt"
pathem preview "$HOME/Downloads/example.txt"

Troubleshoot or remove the handoff

A missing-path error means the CLI could not find the requested path before handing it to the app. A command-not-found error is a shell/PATH problem. A different application opening the URL is a LaunchServices association issue; these require different fixes.

The app's CLI removal control removes only the symlink it recognizes as its own. Moving or replacing Pathem.app can change where a saved link points; check command -v and the installed app location before reinstalling it.

Do not use a shell handoff as a way to bypass filesystem permissions. The receiving app still operates under the access macOS grants it.

Keep going