Metheus Governance MCP CLI

0.2.304 · active · verified Wed Apr 22

This package provides a command-line interface (CLI) for interacting with the Metheus Governance Micro-Control Plane (MCP). It facilitates tasks such as bootstrapping the environment, managing local chat bot configurations, running health checks, and bridging stdio to the Metheus HTTPS gateway for proxying. The current stable version is 0.2.304, indicating active development. The CLI handles authentication, registration with various AI clients (Codex, Claude, Gemini, Antigravity, Cursor), and local secret management for chat platforms like Telegram, Slack, and KakaoTalk. Its key differentiator is providing a local control plane for Metheus-managed AI governance, allowing for granular configuration of bot roles, AI client bindings, and message routing. While no explicit release cadence is stated, the versioning suggests ongoing updates and enhancements to its capabilities.

Common errors

```
Error: Node.js version 16.x.x is not supported. Please upgrade to Node.js >=18.0.0.
```
cause Attempting to run the CLI with an outdated Node.js version that does not meet the minimum requirement of 18.0.0.

fix Upgrade your Node.js installation to version 18 or newer. For example, using NVM: `nvm install 18 && nvm use 18`.
```
Auth token missing or expired. Please log in.
```
cause The Metheus authentication token required by the CLI is either not present on the system, invalid, or has expired.

fix Run `metheus-governance-mcp-cli auth login` to initiate the authentication process and obtain a valid token.
```
command not found: metheus-governance-mcp-cli
```
cause The CLI executable is not in your system's PATH, likely due to an incomplete or failed global npm installation.

fix Ensure the package is installed globally using `npm install -g metheus-governance-mcp-cli@latest`. Verify npm's global bin directory is in your PATH.

Warnings

deprecated The legacy command alias `metheus-governance-mcp` is still supported, but new installations and documentation primarily use `metheus-governance-mcp-cli`.
Fix: Prefer using `metheus-governance-mcp-cli` for all commands to ensure future compatibility and align with current best practices.
gotcha Configuration files for Telegram bots have been refactored. Global settings now reside in `~/.metheus/telegram-bots/global.env`, while per-bot secrets and server metadata are in `~/.metheus/telegram-bots/<ServerBotName>.env`.
Fix: Review and migrate existing Telegram bot configurations to match the new file structure as detailed in the README. Ensure secrets are correctly placed in the per-bot files and global settings in `global.env`.
breaking The Node.js version requirement is `>=18.0.0`. Running the CLI with older Node.js versions will result in errors and prevent correct functionality.
Fix: Upgrade your Node.js installation to version 18 or newer using tools like NVM (`nvm install 18 && nvm use 18`) or official installers.
gotcha Project chat destination identifiers (e.g., `chat_id`, channel names) should not be stored in local environment files (`~/.metheus/*.env`). These are managed server-side by Metheus.
Fix: Ensure local `.env` files only contain bot tokens and local transport options. Avoid adding any project-specific routing metadata to these local files.

Install

npm install metheus-governance-mcp-cli npm
yarn add metheus-governance-mcp-cli yarn
pnpm add metheus-governance-mcp-cli pnpm

Imports

metheus-governance-mcp-cli
wrong:
```
import { metheusGovernanceMcpCli } from 'metheus-governance-mcp-cli'
```
correct:
```
metheus-governance-mcp-cli [command] [args]
```
This package provides a global command-line executable. Functionalities are accessed via shell commands after global npm installation, not via JavaScript `import` statements.
metheus-governance-mcp
```
metheus-governance-mcp [command] [args]
```
This is a legacy alias for `metheus-governance-mcp-cli`. While still supported, `metheus-governance-mcp-cli` should be preferred for consistency and future compatibility.
doctor
wrong:
```
doctor
```
correct:
```
metheus-governance-mcp-cli doctor
```
Subcommands like `doctor` are invoked by appending them to the main CLI executable. Calling 'doctor' directly will result in a 'command not found' error.
auth
wrong:
```
import { auth } from 'metheus-governance-mcp-cli'
```
correct:
```
metheus-governance-mcp-cli auth login
```
The `auth` command handles local Metheus token management. Specific actions like `login` are passed as arguments to the `auth` subcommand.

Quickstart

Installs the CLI globally and demonstrates basic usage for bootstrapping, running health checks, authentication, and adding a new bot.

npm install -g metheus-governance-mcp-cli@latest

# Run in bootstrap mode to check auth and register clients
metheus-governance-mcp-cli

# Alternatively, run end-to-end health checks
metheus-governance-mcp-cli doctor

# To log in if your token is missing or expired
metheus-governance-mcp-cli auth login

# Example of setting up a local bot environment
metheus-governance-mcp-cli bot add my_telegram_bot --provider telegram --role worker

view raw JSON →