runlayer 0.22.2

A command-line interface for running MCP servers via HTTP transport

Runlayer CLI

The Runlayer CLI enables secure execution of trusted MCP servers with enterprise-grade security, auditing, and permission management. Run Model Context Protocol servers through an authenticated proxy that enforces access controls, maintains audit logs, and manages permissions - allowing AI agents to safely connect to internal systems without exposing credentials or running unvetted code locally.

The CLI also provides deployment capabilities to build and deploy Docker-based services to your Runlayer infrastructure, and scanning capabilities to discover MCP server configurations across devices.

Quick Start

The easiest way to get started is to copy the complete command from the server overview page in your Runlayer app - it includes all the required parameters pre-filled for your server.

Alternatively, you can construct the command manually:

uvx runlayer login --host <runlayer_url>
uvx runlayer run <server_uuid> --host <runlayer_url>

Commands

run - Run an MCP Server

Run an MCP server through the Runlayer proxy.

Command Arguments

• server_uuid: UUID of your MCP server (found in your Runlayer deployment)

Command Options

• --secret, -s: Raw API key override for authentication (optional; normal usage is runlayer login)
• --host: Your Runlayer instance URL (e.g., https://runlayer.example.com)

Global Options

These options can be passed to any command:

• --secret, -s: Raw API key override for authentication (user or org key)
• --host, -H: Runlayer host URL
• --org-api-key: Name of a stored org API key to use (see org-api-key command)

Example

uvx runlayer login --host https://runlayer.example.com
uvx runlayer run abc123-def456 --host https://runlayer.example.com

login - Authenticate with Runlayer

Authenticate using a browser-based device flow. Opens a browser and displays a code for verification.

Command Options

• --host, -H: Runlayer host URL (required if not already configured)

Example

uvx runlayer login --host https://runlayer.example.com

logout - Clear Credentials

Clear saved Runlayer credentials from the credential store and config file.

Command Options

• --host, -H: Clear credentials for a specific host only (clears all if omitted)

Example

# Clear all credentials
uvx runlayer logout

# Clear credentials for a specific host
uvx runlayer logout --host https://runlayer.example.com

cache - Manage CLI Cache

Manage the Runlayer CLI OAuth client cache.

cache clear

Remove the OAuth client cache directory.

uvx runlayer cache clear

deploy - Deploy a Service

Deploy a Docker-based service to your Runlayer infrastructure based on a runlayer.yaml configuration file.

Command Options

• --config, -c: Path to runlayer.yaml config file (default: runlayer.yaml)
• --secret, -s: Raw API key override for authentication (optional; normal usage is runlayer login)
• --host, -H: Your Runlayer instance URL (required if not already configured)
• --env-file, -e: Path to .env file for environment variable substitution (optional, defaults to .env in config file directory or current directory)

Example

uvx runlayer login --host https://runlayer.example.com
uvx runlayer deploy --config runlayer.yaml --host https://runlayer.example.com

Configuration File (runlayer.yaml)

The deploy command reads from a runlayer.yaml file that defines your service configuration:

name: my-awesome-service
runtime: docker

build:
  dockerfile: Dockerfile
  context: .
  platform: x86  # or "arm"

service:
  port: 8000
  path: /api

infrastructure:
  cpu: 512
  memory: 1024

env:
  DATABASE_URL: postgres://...
  API_KEY: secret123

Environment Variable Substitution

The CLI supports standard Docker Compose / shell-style environment variable substitution in your runlayer.yaml file. This allows you to reference local environment variables or values from a .env file without hardcoding sensitive values.

Variable Syntax:

• ${VAR} - Required variable (error if not set)
• ${VAR:-default} - Use default value if variable is unset or empty
• ${VAR-default} - Use default value only if variable is unset (not if empty)
• $$DEPLOYMENT_URL, $$RUNLAYER_URL, $$RUNLAYER_OAUTH_CALLBACK_URL - Reserved system variables (backend replaces at deploy time)

Example Configuration:

name: my-service
env:
  API_KEY: ${MY_API_KEY}                      # Required - error if not set
  DATABASE_URL: ${DATABASE_URL}               # Required
  LOG_LEVEL: ${LOG_LEVEL:-info}               # Default to 'info' if not set
  DEBUG: ${DEBUG:-false}                      # Default to 'false'
  WEBHOOK_URL: $$DEPLOYMENT_URL/webhook    # Backend replaces (double $$)

Usage:

# Using environment variables
export MY_API_KEY=secret123
export DATABASE_URL=postgres://localhost/db
uvx runlayer deploy --host https://runlayer.example.com

# Using a .env file (auto-discovered from config file directory or current directory)
# Place .env file next to runlayer.yaml or in current directory
uvx runlayer deploy --host https://runlayer.example.com

# Using a specific .env file
uvx runlayer deploy --host https://runlayer.example.com --env-file .env.prod

Auto-discovery: The CLI automatically looks for a .env file in:

1. The same directory as your runlayer.yaml config file
2. The current working directory (if config file is elsewhere)

If you specify --env-file, it will use that file instead of auto-discovery.

Standard .env file format:

MY_API_KEY=secret123
DATABASE_URL=postgres://localhost/db
LOG_LEVEL=debug

Note: Variables from .env files override values from os.environ. The $$VAR syntax (double dollar sign) is reserved for backend variable substitution and will not be replaced by the CLI.

deploy validate - Validate Configuration

Validate runlayer.yaml configuration without deploying.

Command Options

• --config, -c: Path to runlayer.yaml config file (default: runlayer.yaml)
• --env-file, -e: Path to .env file for environment variable substitution
• --secret, -s: Raw API key override for authentication
• --host, -H: Your Runlayer instance URL

Example

uvx runlayer deploy validate --config runlayer.yaml

deploy pull - Pull Deployment Configuration

Fetch deployment configuration from the backend and save as YAML.

Command Options

• --config, -c: Path to save runlayer.yaml config file (default: runlayer.yaml)
• --deployment-id, -d: Deployment ID to pull (overrides config file)
• --secret, -s: Raw API key override for authentication
• --host, -H: Your Runlayer instance URL

Example

uvx runlayer deploy pull --deployment-id <deployment-id>

deploy destroy - Destroy a Deployment

Destroy a deployment and tear down its infrastructure.

Command Options

• --config, -c: Path to runlayer.yaml config file (default: runlayer.yaml)
• --deployment-id, -d: Deployment ID to destroy (overrides config file)
• --secret, -s: Raw API key override for authentication
• --host, -H: Your Runlayer instance URL

Example

uvx runlayer deploy destroy --deployment-id <deployment-id>

deploy init - Initialize a New Deployment

Create a new deployment and generate a runlayer.yaml configuration file.

Example

uvx runlayer login --host https://runlayer.example.com
uvx runlayer deploy init --config runlayer.yaml --host https://runlayer.example.com

org-api-key - Manage Organization API Keys

Store, list, and remove named organization API keys in the CLI config. Org API keys are scoped keys created in the Runlayer web app (Settings > API Keys) for specific roles like MCP Watch scanning or Security Scan API access.

org-api-key add - Store a Named Key

uvx runlayer org-api-key add <name> --secret <key>

• name: A short name to reference this key by (e.g., mcp-watch, security-scan)
• --secret, -s: The org API key value (rl_org_...). Prompted securely if omitted.
• --host, -H: Host to store the key for (defaults to current host)

org-api-key remove - Remove a Named Key

uvx runlayer org-api-key remove <name>

org-api-key list - List Stored Keys

uvx runlayer org-api-key list

Shows key names and truncated prefixes for the current host.

Using Stored Org API Keys

Once stored, reference a key by name with the --org-api-key flag on any command:

# Use a stored org key for scanning
uvx runlayer scan --org-api-key mcp-watch

# The --org-api-key flag also works as a global option
uvx runlayer --org-api-key mcp-watch scan

# Or via environment variable (scan command only)
RUNLAYER_ORG_API_KEY_NAME=mcp-watch uvx runlayer scan

The --secret flag still accepts any raw API key (user or org) directly and takes priority over --org-api-key.

scan - Scan MCP Client Configurations

Scan for MCP server configurations, skills, and plugins across supported clients (Cursor, Claude Desktop, Claude Code, VS Code, Windsurf, Goose, Zed, OpenCode, Codex) and submit results to Runlayer for classification.

Command Options

• --secret, -s: Raw API key override for authentication (optional unless --dry-run)
• --host, -H: Your Runlayer instance URL (required unless already configured)
• --org-api-key: Name of a stored org API key to use for authentication
• --dry-run, -n: Print scan results as JSON without submitting to API
• --verbose, -v: Enable verbose output
• --quiet, -q: Suppress all output except errors
• --device-id: Custom device identifier (auto-generated if not provided)
• --org-device-id: Organization-provided device ID (e.g., MDM asset tag)
• --no-projects: Skip scanning for project-level configurations
• --project-depth: Maximum directory depth for project scanning (default: 5)
• --project-timeout: Timeout in seconds for project scanning (default: 60)
• --username: Override detected username (e.g., for MDM deployments running as root)

Example

# With a stored org API key
uvx runlayer scan --org-api-key mcp-watch

# With saved login credentials
uvx runlayer login --host https://runlayer.example.com
uvx runlayer scan --host https://runlayer.example.com

setup install - Install MCP Servers and Plugins

Install MCP servers and plugins directly to your client configuration files.

Supported Clients

• cursor - Cursor IDE
• claude_desktop - Claude Desktop
• claude_code - Claude Code (supports plugins)
• vscode - VS Code
• windsurf - Windsurf
• goose - Goose
• zed - Zed

Note: Plugins are only supported for Claude Code.

Command Options

• --client, -c: Target client (required for non-interactive mode)
• --server-id, -S: Server ID(s) to install (can be repeated)
• --plugin-id, -P: Plugin ID(s) to install (Claude Code only, can be repeated)
• --interactive, -i: Interactive mode - browse and select servers/plugins
• --secret, -s: Your Runlayer API key (optional if logged in)
• --host, -H: Your Runlayer instance URL (optional if logged in)
• --header: HTTP header for remote servers (format: Key: Value, can be repeated)
• --yes, -y: Skip confirmation prompts

Authentication for Remote Servers

For remote MCP servers requiring authentication, use the --header option:

# Add authorization header
uvx runlayer setup install --client vscode --server-id abc123 --header "Authorization: Bearer your-token"

# Add custom API key header
uvx runlayer setup install --client cursor --server-id abc123 --header "X-Api-Key: your-key"

# Multiple headers
uvx runlayer setup install --client vscode --server-id abc123 \
  --header "Authorization: Bearer token" \
  --header "X-Custom-Header: value"

Config File Handling

The CLI safely handles JSONC files (JSON with comments and trailing commas), which are used by VS Code, Zed, and other editors. Existing comments and formatting are preserved when installing servers.

Note for VS Code users: VS Code supports user-level and profile-specific MCP configurations. The CLI installs to the default user settings location. If you use VS Code profiles, you may need to manually copy configurations between profiles.

Non-Interactive Mode

Install specific servers or plugins by ID:

# Install a single server to Cursor
uvx runlayer setup install --client cursor --server-id abc123

# Install multiple servers
uvx runlayer setup install --client cursor --server-id abc123 --server-id def456

# Install servers and plugins to Claude Code
uvx runlayer setup install --client claude_code --server-id abc123 --plugin-id xyz789

Interactive Mode

Browse available servers and plugins, then select which to install:

# Interactive mode with client selection
uvx runlayer setup install --interactive

# Interactive mode with pre-selected client
uvx runlayer setup install --interactive --client cursor

Examples

# First, log in to your Runlayer instance
uvx runlayer login --host https://runlayer.example.com

# Interactive installation
uvx runlayer setup install --interactive

# Non-interactive installation
uvx runlayer setup install --client cursor --server-id abc123 --host https://runlayer.example.com

# Skip confirmation prompts
uvx runlayer setup install --client cursor --server-id abc123 --yes

setup hooks - Install Client Hooks

Install or uninstall Runlayer hooks that validate MCP tool calls and block access to sensitive files (.env, MCP configs).

Command Options

• --client, -c: Client to configure (cursor or claude_code). All clients if omitted.
• --install, -i: Install hooks
• --uninstall, -u: Uninstall hooks
• --all-events: Register all hook events including pipeline (default: enforcement only)
• --no-enforcement: Monitoring only — register hooks but skip blocking enforcement
• --mdm: Install to enterprise location (requires elevated permissions)
• --host, -H: Validate this host exists in config before install
• --yes, -y: Skip confirmation prompt

Example

# Install hooks for all clients
uvx runlayer setup hooks --install

# Install for Claude Code only
uvx runlayer setup hooks --install --client claude_code

# Install to enterprise (MDM) location
sudo uvx runlayer setup hooks --install --mdm

# Monitor without blocking
uvx runlayer setup hooks --install --no-enforcement

# Uninstall
uvx runlayer setup hooks --uninstall

setup sync - Sync Auto-Synced Servers

Install all auto-synced servers to client configs. Auto-detects installed clients or use --client to target a specific one.

Command Options

• --client, -c: Target client (auto-detects if omitted)
• --header: HTTP header for remote servers (format: Key: Value, can be repeated)
• --secret, -s: Your Runlayer API key (optional if logged in)
• --host, -H: Your Runlayer instance URL (optional if logged in)
• --yes, -y: Skip confirmation prompts

Example

# Sync to all detected clients
uvx runlayer setup sync

# Sync to a specific client
uvx runlayer setup sync --client cursor --yes

skills - Manage Skills

Push, install, and manage reusable prompt packages.

skills push

uvx runlayer skills push [PATH] --namespace <namespace> [OPTIONS]

• PATH: Root directory to scan (default: .)
• If PATH itself is a skill dir, the pushed skill path uses that folder name
• If PATH contains many skill dirs, each pushed skill path uses its relative subpath
• --namespace, -N: Required. Groups skills by repo (e.g. myorg/my-repo)
• --public: Publish pushed skills as public
• --prune: Delete remote skills whose directories no longer exist locally
• --dry-run, -n: Preview changes without making API calls

skills scan

uvx runlayer skills scan <PATH> [OPTIONS]

• PATH: Skill dir, SKILL.md path, or a root containing many skills
• --name: Override skill name sent to the security scan API for single-skill scans only
• --fail-on: Exit non-zero on warn or block
• Output is always JSON. Single-skill scans return one scan object; multi-skill scans return { "skills": [...] }

This calls the security scan API to score one or many local skills without pushing them to the Runlayer skills catalog or AI Watch shadow-skill discovery flow.

skills add

uvx runlayer skills add [SOURCE] [OPTIONS]

• SOURCE: Skill UUID or namespace (e.g. Org/Repo). Optional when --all is used
• --all: Install all accessible skills across namespaces
• --skill: Filter by skill name within a namespace
• --client, -c: Target editor: claude_code (default), cursor, opencode, vscode
• --global, -g: Install globally instead of project-level
• --dry-run, -n: Preview without writing files

skills list

uvx runlayer skills list [OPTIONS]

• --client, -c: Target editor (default: claude_code)
• --global, -g: List global skills

skills update

uvx runlayer skills update [OPTIONS]

• --skill: Update a specific skill only
• --client, -c: Target editor (default: claude_code)
• --global, -g: Update global skills
• --dry-run, -n: Preview without writing files

skills remove

uvx runlayer skills remove [NAME] [OPTIONS]

• NAME: Skill name. Optional when --all is used
• --all: Remove all installed skills in the selected scope
• --yes: Skip confirmation prompt
• --client, -c: Target editor (default: claude_code)
• --global, -g: Remove from global skills

plugins - Manage Plugins

Push, install, and manage plugin bundles (MCP connectors + skills).

Supported Clients

Client	Install mode
claude_code (default)	Native
cursor	Native
vscode	Native
windsurf	MCP fallback
goose	MCP fallback
zed	MCP fallback
opencode	MCP fallback

plugins push

uvx runlayer plugins push [PATH] --namespace <namespace> [OPTIONS]

• PATH: Root directory to scan (default: .)
• --namespace, -N: Required. Groups plugins by repo or source namespace
• --public: Publish the plugin as public
• --dynamic-tools: Enable dynamic tools mode
• --prune: Delete remote plugins missing locally
• --dry-run, -n: Preview changes without making writes

plugins add

uvx runlayer plugins add [SOURCE] [OPTIONS]

• SOURCE: Plugin UUID or namespace. Optional when --all is used
• --all: Install all accessible plugins across namespaces
• --plugin: Filter by plugin name within a namespace
• --client, -c: Target editor (default: claude_code)
• --global, -g: Install globally instead of project-level
• --dry-run, -n: Preview without writing files

plugins list

uvx runlayer plugins list [OPTIONS]

• --client, -c: Target editor (default: claude_code)
• --global, -g: List global plugins

plugins update

uvx runlayer plugins update [OPTIONS]

• --plugin: Update a specific plugin only
• --client, -c: Target editor (default: claude_code)
• --global, -g: Update global plugins
• --dry-run, -n: Preview without writing files

plugins remove

uvx runlayer plugins remove [PLUGIN_REF] [OPTIONS]

• PLUGIN_REF: Plugin name or UUID. Optional when --all is used
• --all: Remove all installed plugins in the selected scope
• --yes: Skip confirmation prompt
• --client, -c: Target editor (default: claude_code)
• --global, -g: Remove from global plugins

verified-local - Run a Verified Local MCP Server Proxy

Secure proxy for verified local MCP servers. Verifies code signatures before forwarding MCP traffic to local applications, ensuring the target application hasn't been tampered with.

Command Arguments

• server_id: Server identifier (e.g., com.figma/desktop-mcp)

Command Options

• --list, -l: List available server IDs and exit
• --verbose, -v: Enable verbose output

Example

# List available servers
uvx runlayer verified-local --list

# Run a verified proxy
uvx runlayer verified-local com.figma/desktop-mcp

Credential Storage

When you run runlayer login, the CLI stores your API key in your operating system's credential store. The backing service depends on the platform:

Platform	Backend
macOS	Keychain Access
Windows	Windows Credential Vault
Linux (desktop)	Secret Service (GNOME Keyring / KDE Wallet)
CI / Docker / headless	Falls back to ~/.runlayer/config.yaml

The ~/.runlayer/config.yaml file still stores host URLs, default host, and org API keys — but user API keys are kept in the credential store when it is usable.

If no credential store is available (headless environments, SSH sessions without D-Bus, and similar), credentials fall back to the config file with a one-time warning. No action is needed — the CLI handles this automatically.

Upgrading from older versions: Existing secrets in config.yaml continue to work. New logins store user API keys in the credential store. Run runlayer login again to move a host's secret off the file and into the store.

Logs

Logs are written to ~/.runlayer/logs/. Set LOG_LEVEL environment variable to control verbosity (DEBUG, INFO, WARNING, ERROR).