npm package: @gatorsecurity/cli
Description: G8R CLI for MCP server management and policy enforcement
Author: Gator Security
Latest version: 0.3.0

# @gatorsecurity/cli

G8R CLI for MCP server management and policy enforcement.

## Installation

### Development (from monorepo)

```bash
# Build the CLI
pnpm --filter @gatorsecurity/cli build

# Run directly
./packages/cli/dist/index.js --help

# Or link globally
cd packages/cli && npm link

# Verify installation
g8r --help
```

### Unlink

```bash
cd packages/cli && npm unlink
```

## Configuration

The CLI stores configuration in `~/.g8r/`:
- `~/.g8r/config.json` - Default profile
- `~/.g8r/profiles/<name>.json` - Named profiles

### Profiles

Use `G8R_PROFILE` to switch between configurations:

```bash
# Use dev profile
G8R_PROFILE=dev g8r config list

# Set up dev profile for local development
G8R_PROFILE=dev g8r config dev

# Or create a shell alias
alias g8r-dev='G8R_PROFILE=dev g8r'
```

### For Local Development

```bash
# Quick setup with dev profile
G8R_PROFILE=dev g8r config dev

# Or manually set URLs
g8r config set platformUrl http://localhost:8200
g8r config set webUrl http://localhost:8400
```

**Default production values:**
- `platformUrl`: https://api.g8r.live
- `webUrl`: https://app.g8r.live

## Commands

### Setup

- `g8r init` - Interactive setup wizard (configure AI client, wrap servers with gateway)
- `g8r login` - Authenticate with G8R platform (opens browser)
- `g8r logout` - Clear stored credentials
- `g8r whoami [--json]` - Show current user and organization

### Configuration

- `g8r config list` - Show profile and configuration values
- `g8r config get <key>` - Get a specific config value
- `g8r config set <key> <value>` - Set a config value
- `g8r config dev` - Configure for local development (localhost URLs)

Available config keys:
- `platformUrl` - Backend API URL
- `webUrl` - Web UI URL for authentication
- `defaultDeny` - Fail closed (true) or fail open (false) on policy errors

### Servers

- `g8r servers list` - List MCP servers from all AI client configs
- `g8r servers search [query]` - Search for MCP servers on npm
- `g8r servers add --package <pkg>` - Add server with CVE check (e.g., `--package @playwright/mcp@0.0.40`)
- `g8r servers add --command <cmd> --args <args>` - Add server with custom command
- `g8r servers remove [name]` - Remove server from AI client config

Options for `servers add`:
- `--client <client>` - Target client (claude-desktop, claude-code, cursor, vscode)
- `--name <name>` - Server name (auto-generated from package if not specified)
- `--no-gateway` - Don't wrap with g8r-gateway
- `--skip-security` - Skip CVE vulnerability check
- `--local` - Add to project config instead of global

Options for `servers search`:
- `--limit <n>` - Max results to show (default: 15)
- `--json` - Output as JSON

### Policies

- `g8r policies list` - List security policies for your organization
- `g8r policies list --type <type>` - Filter by policy type (tool, cve, dependency)
- `g8r policies list --json` - Output as JSON

### Plugins

- `g8r plugins list` - List enabled plugins from platform
- `g8r plugins sync` - Sync plugin status

### Sandbox Management

- `g8r sandbox start` - Start sandbox container
- `g8r sandbox stop` - Stop sandbox container
- `g8r sandbox status` - Show sandbox status

## Environment Variables

- `G8R_PROFILE` - Use a named profile (e.g., `dev`, `staging`)
- `G8R_WEB_URL` - Override web URL for login (bypasses config)
- `G8R_DEBUG` - Enable debug logging (set to `true`)

## Examples

### Basic workflow

```bash
# Login (opens browser)
g8r login

# Verify authentication
g8r whoami

# Set up your AI client (Claude Desktop, Cursor, VS Code, etc.)
g8r init

# Check enabled plugins
g8r plugins list
```

### Search and add MCP servers

```bash
# Search for MCP servers
g8r servers search playwright
g8r servers search github

# Add a server (with automatic CVE check)
g8r servers add --package @playwright/mcp

# List configured servers
g8r servers list
```

### View security policies

```bash
# List all policies
g8r policies list

# Filter by type
g8r policies list --type cve

# Output as JSON
g8r policies list --json
```

### Local development workflow

```bash
# Set up dev profile (one time)
G8R_PROFILE=dev g8r config dev
G8R_PROFILE=dev g8r login

# Use dev profile
G8R_PROFILE=dev g8r whoami
G8R_PROFILE=dev g8r init
```

### Debug logging

```bash
# Enable debug logs
G8R_DEBUG=true g8r login 2>debug.log
```

## Troubleshooting

### "Login opens production URL instead of local"
- Run `g8r config list` to verify URLs
- Set correct URLs: `g8r config set webUrl http://localhost:8400`

### "Authentication failed"
- Verify server is running: `curl http://localhost:8200/health`
- Check config: `g8r config list`
- Clear and re-login: `g8r logout && g8r login`