> ## Documentation Index
> Fetch the complete documentation index at: https://meridiona-mintlify-2ae70a19.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Meridian CLI Reference: Commands, Flags, and Usage

> Complete reference for every meridian CLI command — setup, start, stop, logs, doctor, config, permissions, update, and uninstall — plus the install.sh flags for source builds.

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

<Accordion title="meridian setup">
  ```bash theme={null}
  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](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.

  <Note>
    Source-built contributors run `./install.sh` from the repo root instead. The on-disk layout under `~/.meridian/` is the same.
  </Note>
</Accordion>

<Accordion title="meridian update">
  ```bash theme={null}
  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.
</Accordion>

<Accordion title="meridian start">
  ```bash theme={null}
  meridian start
  ```

  Enables and bootstraps every Meridian LaunchAgent, then prints a live status summary. The daemons started are, in order:

  | Label                      | Service                                                             |
  | -------------------------- | ------------------------------------------------------------------- |
  | `com.meridiona.screenpipe` | screenpipe ambient recorder                                         |
  | `com.meridiona.daemon`     | Meridian Rust ETL daemon                                            |
  | `com.meridiona.mlx-server` | MLX inference server                                                |
  | `com.meridiona.ui`         | Next.js dashboard at [http://localhost:3939](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.

  <Note>
    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.
  </Note>
</Accordion>

<Accordion title="meridian stop">
  ```bash theme={null}
  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`.
</Accordion>

<Accordion title="meridian restart">
  ```bash theme={null}
  meridian restart
  ```

  Runs `meridian stop`, waits one second, then runs `meridian start`. Use this after changing environment variables or rebuilding the daemon binary.
</Accordion>

<Accordion title="meridian status">
  ```bash theme={null}
  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.
</Accordion>

<Accordion title="meridian logs [target] [-f] [-n N]">
  ```bash theme={null}
  meridian logs [target] [-f] [-n N]
  ```

  Tails a log file from `~/.meridian/logs/`. All arguments are optional.

  **Valid targets**

  | Target               | File                                    |
  | -------------------- | --------------------------------------- |
  | `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**

  | Flag   | Description                          |
  | ------ | ------------------------------------ |
  | `-f`   | Follow (stream) the log in real time |
  | `-n N` | Show the last N lines (default: 100) |

  **Examples**

  ```bash theme={null}
  # 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
  ```
</Accordion>

<Accordion title="meridian doctor">
  ```bash theme={null}
  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.
</Accordion>

<Accordion title="meridian config edit">
  ```bash theme={null}
  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.

  <Tip>
    You can also set `$EDITOR` to any editor you prefer before calling this command:

    ```bash theme={null}
    EDITOR=code meridian config edit
    ```
  </Tip>
</Accordion>

<Accordion title="meridian permissions">
  ```bash theme={null}
  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.

  <Warning>
    Without Screen Recording permission, screenpipe cannot capture frames and Meridian will have no data to process.
  </Warning>
</Accordion>

<Accordion title="meridian uninstall">
  ```bash theme={null}
  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:

  ```bash theme={null}
  rm -rf ~/.meridian
  ```
</Accordion>

***

## 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.

<CardGroup cols={2}>
  <Card title="--no-ui" icon="window-minimize">
    Skip the Next.js dashboard build. Useful on headless machines or when you only need the daemon and MCP server.
  </Card>

  <Card title="--dry-run" icon="eye">
    Preview every action the installer would take without executing any of them. Helpful for auditing the setup on a new machine.
  </Card>

  <Card title="--no-daemon" icon="server">
    Build all binaries but do not register any launchd agents. Use this if you want to manage service startup yourself.
  </Card>

  <Card title="--skip-permissions" icon="shield">
    Skip the interactive macOS permissions walkthrough. Useful when re-running the installer after permissions are already granted, or in scripted environments.
  </Card>

  <Card title="--skip-env" icon="key">
    Skip all credential prompts entirely. Existing values in the `.env` files are preserved. Use alongside `--skip-permissions` for fully non-interactive re-installs.
  </Card>

  <Card title="--mlx" icon="microchip">
    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.
  </Card>
</CardGroup>

**Example — build only, no prompts, no daemon registration:**

```bash theme={null}
./install.sh --no-daemon --skip-permissions --skip-env
```