> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gorules.io/llms.txt
> Use this file to discover all available pages before exploring further.

# GoRules CLI

> Bridge your GoRules BRMS projects to local development and AI tooling.

The GoRules CLI (`@gorules/cli`) is an open-source command-line tool that bridges [GoRules BRMS](https://gorules.io) projects to your local development environment. It exposes an MCP (Model Context Protocol) server so AI-powered editors like Claude Code, Cursor, and Windsurf can read, evaluate, and interact with your decision logic directly.

**GitHub:** [github.com/gorules/cli](https://github.com/gorules/cli)

## Installation

```bash theme={null}
# npm
npm install -g @gorules/cli

# Or run directly with npx
npx @gorules/cli mcp start
```

## Quick start

Start the MCP bridge:

```bash theme={null}
gorules mcp start
```

This launches a local server on port 41919 that:

1. Exposes an MCP endpoint for AI tools to discover and call GoRules tools
2. Exposes REST endpoints for evaluating decisions and fetching decision files
3. Opens a WebSocket connection that the GoRules browser editor connects to

Once running, open your GoRules project in the browser and click **Connect MCP** to link the editor to your local CLI.

## Commands

### `gorules mcp start`

Start the MCP bridge server.

| Flag     | Alias | Default     | Description           |
| -------- | ----- | ----------- | --------------------- |
| `--port` | `-p`  | `41919`     | Server port           |
| `--host` | `-h`  | `localhost` | Server host           |
| `--url`  | `-u`  | -           | GoRules server URL    |
| `--open` | -     | `false`     | Open browser on start |

## REST API

When the bridge is running, it exposes HTTP endpoints for local development.

### Evaluate a decision

```bash theme={null}
POST http://localhost:41919/evaluate/{filePath}
```

```json theme={null}
{
  "context": {
    "customer": { "tier": "premium" },
    "orderTotal": 150
  },
  "trace": false
}
```

Response:

```json theme={null}
{
  "result": { "discount": 0.15, "freeShipping": true }
}
```

Optional body fields: `trace` (boolean), `maxDepth` (number).

### Retrieve a decision file

```bash theme={null}
GET http://localhost:41919/file/{filePath}
```

Returns the raw decision graph JSON. You can use this as a loader for the ZEN Engine:

```javascript theme={null}
import { ZenEngine } from "@gorules/zen-engine";

const engine = new ZenEngine({
  loader: async (key) => {
    const res = await fetch(`http://localhost:41919/file/${key}`);
    return res.json();
  },
});

const result = await engine.evaluate("my-decision", {
  customer: { tier: "premium" },
  orderTotal: 150,
});
```

## How it works

The CLI acts as a bridge between AI tools and the GoRules browser editor:

```mermaid theme={null}
graph TD
    A[AI Tool - Claude, Cursor, etc.] -->|MCP Protocol| B[GoRules CLI - localhost:41919]
    B -->|WebSocket| C[GoRules Browser Editor]
    C -->|API| D[GoRules BRMS Platform]
```

1. The CLI starts and generates a connection token
2. The GoRules browser editor connects via WebSocket using the token
3. The editor sends a tool manifest - the list of available tools for that project
4. AI tools discover these tools via MCP and invoke them
5. The CLI forwards tool calls to the browser, which executes them and returns results

The CLI is stateless - it doesn't store credentials or project data. All tool execution happens in the browser editor, which has an authenticated session with the GoRules platform.

## License

MIT