Skip to main content
Version: v2 (current)

Install on macOS

Install the PanDev Metrics CLI plugin on macOS in about 3 minutes. After this guide your terminal activity (base command + timestamp) shows up in PanDev Metrics dashboards.

Before you begin​

  • macOS with Homebrew installed (brew.sh)

  • Your PanDev Metrics API token — open the web app, go to Settings → Plugins → CLI, and copy the value from the Enter your token step. Tokens start with pandev_.

    The token already carries the server address and the workspace, so there is no separate Server URL to enter.

Step 1 — Install the plugin via Homebrew​

curl -fsSL https://raw.githubusercontent.com/pandev-metriks/pandev-cli/main/install.sh | bash
sudo pandev-cli-plugin --install

The first command runs the official installer: it sets up the PanDev Homebrew tap (when brew is available) and installs the binary. The second registers the background daemon (this is the only step that needs sudo).

Step 2 — Authenticate​

Run pandev login and paste your token at the prompt.

sudo pandev login
# Enter your PanDev token (starts with 'pandev_'):

To skip the prompt — in a provisioning script, for example — pass the token as a flag:

sudo pandev login -t pandev_...

--token pandev_... and --token=pandev_... do the same thing.

caution

A token is a credential — anyone holding it can send metrics as you. Keep it out of commits and shared chats, and prefer the interactive prompt on a shared machine so the token does not land in your shell history.

The token is stored locally so the daemon reconnects automatically after restarts.

Step 3 — Verify​

Confirm that the daemon is running and authenticated:

pandev status

Check that heartbeats are accumulating:

pandev time

You can also open Settings → Plugin → CLI plugin in the PanDev Metrics UI — your machine should appear with a recent heartbeat timestamp.

Useful commands​

pandev --help     # List every command the plugin exposes
pandev status     # Daemon health and auth state
pandev time       # CLI activity captured today
pandev login      # Re-authenticate

Update​

Homebrew handles upgrades:

brew update && brew upgrade pandev-cli-plugin

Uninstall​

sudo pandev-cli-plugin --uninstall
brew uninstall pandev-cli-plugin
brew untap pandev-metriks/pandev-cli

Troubleshooting​

pandev status says "not authenticated"

Run sudo pandev login again. If the issue persists, check that your Server URL has no trailing slash and that you can reach it from the same machine: curl -I <server-url>.

pandev status shows the daemon as not running

Re-run the install registration step:

sudo pandev-cli-plugin --install

Then pandev status again.

Self-signed certificate on on-prem server

The plugin honours macOS keychain trust. Import your organisation's root CA via Keychain Access → System → Certificates and mark it as trusted for SSL.

No data in the dashboard after 30 minutes

Confirm three things:

  1. pandev status reports authenticated and running
  2. pandev time shows a non-zero value
  3. The token you signed in with belongs to the same account and workspace you are viewing in the PanDev Metrics UI

Heartbeats appear in dashboards within a few minutes of cron jobs running.

FAQ​

Does it support Apple Silicon (M1/M2/M3)?​

Yes. Homebrew installs the correct binary for your architecture automatically.

Why does installation need sudo?​

The one-time pandev-cli-plugin --install registers a launch agent so the daemon starts at login. After that the daemon runs as your user — no further sudo needed.

What shells are supported?​

zsh (default on macOS), bash, and fish. The plugin hooks into the shell on installation.

How do I switch to a different server or workspace?​

Copy a token from the target workspace in the web app and run sudo pandev login -t <NEW_TOKEN>. The server address is inside the token, so there is nothing else to change.