Skip to main content
The meridian CLI is a bash script that wraps macOS launchd, letting you manage all Meridian services without touching launchctl directly. When you install via npm (npm install -g @meridiona/meridian), the CLI is placed on your PATH automatically. Source-built contributors get the same binary symlinked into /usr/local/bin/meridian (or ~/.local/bin/meridian) by ./install.sh.

​
Commands

meridian setup
The one-time installer run after npm install -g @meridiona/meridian. Copies the prebuilt app bundle to ~/.meridian/app, installs any missing prerequisites (Homebrew packages, Python 3.11, ffmpeg, screenpipe), prepares the on-device model environment, and registers four launchd agents that start automatically:
  • com.meridiona.screenpipe — capture
  • com.meridiona.daemon — pipeline (ETL, classification, worklog drafting)
  • com.meridiona.mlx-server — on-device model
  • com.meridiona.ui — dashboard at http://localhost:3939
After setup completes, meridian setup walks you through the macOS permissions panes (Screen Recording, Accessibility). Run it again at any time to re-register services or top up missing prerequisites; it’s idempotent.
Source-built contributors run ./install.sh from the repo root instead. The on-disk layout under ~/.meridian/ is the same.
meridian update
Pulls the latest release of @meridiona/meridian from npm and re-runs meridian setup so the registered launchd agents pick up the new binary. Your config in ~/.meridian/app/.env and database at ~/.meridian/meridian.db are preserved.
meridian start
Enables and bootstraps every Meridian LaunchAgent, then prints a live status summary. The daemons started are, in order:
LabelService
com.meridiona.screenpipescreenpipe ambient recorder
com.meridiona.daemonMeridian Rust ETL daemon
com.meridiona.mlx-serverMLX inference server
com.meridiona.uiNext.js dashboard at http://localhost:3939
If any .plist file is missing, meridian start prints an error for that service and exits with a non-zero code. Re-run meridian setup (or ./install.sh for source builds) to reinstall missing plists.
The Rust daemon TCP-connects to the MLX server at startup to verify it is reachable. If the MLX server is not running, the daemon exits immediately. Start all services together with meridian start rather than launching them individually.
meridian stop
Disables and boots out every LaunchAgent, then kills any orphaned mlx_lm.server processes that launchd does not track. The .plist files in ~/Library/LaunchAgents/ are left in place so meridian start can bring everything back up.Use this command before editing ~/.meridian/app/.env so the daemon picks up the new values on the next meridian start.
meridian restart
Runs meridian stop, waits one second, then runs meridian start. Use this after changing environment variables or rebuilding the daemon binary.
meridian status
Queries launchd for the running state of every registered service and prints a colour-coded summary:
  • ✓ running (pid N) — service is up and has a PID
  • ⊘ loaded but not running — launchd has the plist but the process is not active (e.g. a service paused between scheduled slots)
  • ✗ not installed — plist is missing; run meridian setup (or ./install.sh for source builds)
Run meridian status any time you are unsure whether the stack is up.
meridian logs [target] [-f] [-n N]
Tails a log file from ~/.meridian/logs/. All arguments are optional.Valid targets
TargetFile
daemon (default)~/.meridian/logs/daemon.log
daemon-error~/.meridian/logs/daemon-error.log
mlx-server~/.meridian/logs/mlx-server.log
mlx-server-error~/.meridian/logs/mlx-server-error.log
screenpipe~/.meridian/logs/screenpipe.log
screenpipe-error~/.meridian/logs/screenpipe-error.log
ui~/.meridian/logs/ui.log
ui-error~/.meridian/logs/ui-error.log
Flags
FlagDescription
-fFollow (stream) the log in real time
-n NShow the last N lines (default: 100)
Examples
# Stream the Rust daemon log live
meridian logs daemon -f

# Last 50 lines of the MLX server log
meridian logs mlx-server -n 50

# Tail errors from screenpipe
meridian logs screenpipe-error

meridian doctor
Runs a full suite of environment health checks and prints a pass/fail result for each one. Checks include:
  • macOS on Apple Silicon detected
  • meridian and meridian-daemon binaries exist and are executable
  • Service .plist files are installed and pass plutil -lint (daemon, mlx-server, screenpipe, UI)
  • Daemon process is running
  • ~/.meridian/app/.env configuration file exists
  • screenpipe binary is in $PATH
  • screenpipe database exists at ~/.screenpipe/db.sqlite
  • screenpipe process is running
  • Python environment is set up for the MLX server
  • MLX server is reachable on 127.0.0.1:$MLX_SERVER_PORT
  • Next.js UI has been built and the dashboard responds on http://localhost:$MERIDIAN_UI_PORT
At the end, doctor prints a count of failed checks. A clean run looks like:
✓ all checks passed
Run meridian doctor as the first diagnostic step whenever something seems wrong.
meridian config edit
Opens ~/.meridian/app/.env in your $EDITOR (falls back to nano if $EDITOR is not set). This is the canonical way to update API keys, change the poll interval, or toggle classification without hunting for the file path. On source-built installs, the same command opens the repo-root .env.After saving, run meridian restart so the daemon picks up the new values.
You can also set $EDITOR to any editor you prefer before calling this command:
EDITOR=code meridian config edit

meridian permissions
Walks you interactively through the two macOS privacy panes that screenpipe requires:
  1. Screen Recording — opens the System Settings pane; click +, navigate to the screenpipe binary, add it, and toggle it on.
  2. Accessibility — same steps.
After each step the script waits for you to press Enter. Run meridian restart afterwards so screenpipe picks up the newly granted permissions. Audio capture is disabled by default, so no Microphone permission is required.
Without Screen Recording permission, screenpipe cannot capture frames and Meridian will have no data to process.
meridian uninstall
Prompts for confirmation, then stops all daemons, runs each service’s uninstall script, kills orphaned mlx_lm.server processes, and removes the meridian and meridian-daemon shims. After uninstall, you can also npm uninstall -g @meridiona/meridian to remove the CLI package itself.Your data at ~/.meridian/ is not removed. Delete it manually if you want to wipe everything:
rm -rf ~/.meridian

​
install.sh Flags (source builds)

Most users install from npm with npm install -g @meridiona/meridian && meridian setup and never touch install.sh. The source installer is only relevant if you cloned the repo to contribute to Meridian itself. It accepts the following flags to customise or automate the setup process.

--no-ui

Skip the Next.js dashboard build. Useful on headless machines or when you only need the daemon and MCP server.

--dry-run

Preview every action the installer would take without executing any of them. Helpful for auditing the setup on a new machine.

--no-daemon

Build all binaries but do not register any launchd agents. Use this if you want to manage service startup yourself.

--skip-permissions

Skip the interactive macOS permissions walkthrough. Useful when re-running the installer after permissions are already granted, or in scripted environments.

--skip-env

Skip all credential prompts entirely. Existing values in the .env files are preserved. Use alongside --skip-permissions for fully non-interactive re-installs.

--mlx

Install and register the persistent MLX inference server as a launchd daemon. Requires Apple Silicon. Enables faster, on-device session classification with no external API calls.
Example — build only, no prompts, no daemon registration: 
./install.sh --no-daemon --skip-permissions --skip-env