ploston-cli 1.7.0

Unified CLI for Ploston - Bridge, Runner, and Management Commands

Ploston CLI

Command-line interface and local runner for Ploston - Deterministic Agent Execution Layer

Overview

The Ploston CLI provides two main capabilities:

1. CLI Client - A thin HTTP client for interacting with Ploston servers
2. Local Runner - An edge runner for executing MCP tools locally while connected to a remote Control Plane

Key Design Principle: The CLI client does not embed any server components. It communicates exclusively via HTTP with a running Ploston server. The runner connects via WebSocket to the Control Plane and executes MCP tools locally.

Installation

From PyPI

pip install ploston-cli

From Source

git clone https://github.com/ostanlabs/ploston-cli.git
cd ploston-cli
make install

Verify Installation

ploston version

Quick Start

# 1. Deploy the Control Plane locally
ploston bootstrap --edge

# 2. Inject Ploston into your agent's MCP config
ploston inject

# 3. Restart your agent — Ploston MCP servers appear automatically

# 4. List available workflows
ploston workflows list

# 5. Run a workflow
ploston run my-workflow -i key=value

For manual server configuration (without bootstrap):

ploston config set server http://localhost:8022
# or: export PLOSTON_SERVER=http://localhost:8022

Server Connection

The CLI connects to a Ploston server via HTTP. Configure the server URL using:

1. CLI flag: --server http://localhost:8080
2. Environment variable: PLOSTON_SERVER=http://localhost:8080
3. Config file: ~/.ploston/config.yaml

# Set server URL in config
ploston config set server http://localhost:8080

# Check current configuration
ploston config show --local

Commands

Global Options

Option	Description
--server URL	Ploston server URL
-v, --verbose	Increase verbosity (can be repeated)
-q, --quiet	Suppress output
--json	Output as JSON

ploston bootstrap

Deploy the Ploston Control Plane locally via Docker Compose (default) or Kubernetes.

# Deploy with latest tested dev images
ploston bootstrap --edge

# Include full observability stack (Grafana, ClickHouse, OTEL Collector)
ploston bootstrap --edge --with-observability

# Deploy to Kubernetes
ploston bootstrap --target k8s --namespace ploston

# Build from local source
ploston bootstrap --build-from-source

Option	Description
--target [docker|k8s]	Deployment target (default: docker)
--edge	Use latest tested dev images
--image-tag TEXT	Specific Docker image tag
--build-from-source	Build images from local source
--port INTEGER	Control Plane port
--with-observability	Include Prometheus + Grafana + ClickHouse + OTEL Collector
--with-native-tools	Include native-tools MCP server
--no-import	Skip auto-detection and import of existing MCP configs
-y, --non-interactive	Accept all defaults
--namespace TEXT	K8s namespace
--domain TEXT	Base domain for K8s ingress

Subcommands: down, logs, restart, restart-runner, rollback, status, restore-from-file.

ploston inject

Re-run Ploston config injection into agent configs without re-importing servers.

# Inject into all detected agents
ploston inject

# Inject into a specific agent only
ploston inject --inject-target cursor

# Non-interactive (inject all detected targets)
ploston inject --non-interactive

Supported targets: Claude Desktop, Cursor, Claude Code, Windsurf, Gemini CLI, Cline, VS Code Copilot, Codex, Zed.

ploston inspector

Start/stop the local Session Inspector web UI for MCP discoverability.

# Start inspector daemon (or open browser if already running)
ploston inspector

# Explicit start/stop/status
ploston inspector start
ploston inspector stop
ploston inspector status

# Tail logs
ploston inspector logs -f

ploston executions

Inspect workflow execution history.

# List recent executions
ploston executions list

# Show execution details with step trace
ploston executions show <execution-id>

ploston init

Initialize Ploston configuration and optionally import existing MCP configs.

# Auto-detect and import from Claude Desktop / Cursor
ploston init --import

# Import from a specific source
ploston init --import --source claude

# Import and inject Ploston bridge entries into source config
ploston init --import --inject

# Non-interactive mode
ploston init --import --non-interactive

ploston server

Manage MCP servers registered on the Control Plane.

# List configured MCP servers
ploston server list

# Add an MCP server
ploston server add <name>

# Remove an MCP server
ploston server remove <name>

ploston run

Execute a workflow on the server.

# Run with inline inputs
ploston run my-workflow -i name=John -i age=30

# Run with input file
ploston run my-workflow --input-file inputs.yaml

# Run with timeout
ploston run my-workflow -t 60

# Get JSON output
ploston --json run my-workflow

Option	Description
-i, --input KEY=VALUE	Input parameter (can be repeated)
--input-file PATH	YAML/JSON file with inputs
-t, --timeout SECONDS	Execution timeout

ploston validate

Validate a workflow YAML file locally.

# Basic validation (local only, no server needed)
ploston validate workflow.yaml

# Strict mode (warnings as errors)
ploston validate --strict workflow.yaml

# Check that tools exist on server
ploston validate --check-tools workflow.yaml

Option	Description
--strict	Treat warnings as errors
--check-tools	Verify tools exist on server

ploston workflows

Manage workflows on the server.

# List all workflows
ploston workflows list

# Show workflow details
ploston workflows show my-workflow

# JSON output
ploston --json workflows list

ploston tools

Manage tools on the server.

# List all tools
ploston tools list

# Show tool details
ploston tools show read_file

# Refresh tool schemas from MCP servers
ploston tools refresh

ploston config

Manage CLI and server configuration.

# Show local CLI config
ploston config show --local

# Show server config
ploston config show

# Show specific section
ploston config show --section mcp

# Set CLI config values
ploston config set server http://localhost:8080
ploston config set timeout 60

# Unset CLI config values
ploston config unset timeout

Valid sections: server, mcp, tools, workflows, execution, python_exec, logging, plugins, security, telemetry

ploston version

Show version information.

ploston version

Shows both CLI version and connected server version.

ploston bridge

Start MCP bridge for Claude Desktop, Cursor, and other MCP clients.

# Basic usage
ploston bridge --url http://localhost:8080

# With authentication
ploston bridge --url https://cp.example.com --token plt_xxx

# With custom timeout and logging
ploston bridge --url http://localhost:8080 --timeout 60 --log-level debug

Option	Environment Variable	Description
--url	PLOSTON_URL	Control Plane URL (required)
--token	PLOSTON_TOKEN	Bearer token for authentication
--timeout	PLOSTON_TIMEOUT	Request timeout in seconds (default: 30)
--log-level	PLOSTON_LOG_LEVEL	Log level: debug, info, warning, error
--log-file	PLOSTON_LOG_FILE	Log file path (default: ~/.ploston/bridge.log)
--retry-attempts	PLOSTON_RETRY_ATTEMPTS	Startup retry attempts (default: 3)
--retry-delay	PLOSTON_RETRY_DELAY	Delay between retries (default: 1.0s)

Claude Desktop Configuration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "ploston": {
      "command": "ploston",
      "args": ["bridge", "--url", "http://localhost:8080"],
      "env": {
        "PLOSTON_TOKEN": "your-token-here"
      }
    }
  }
}

Cursor Configuration

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "ploston": {
      "command": "ploston",
      "args": ["bridge", "--url", "http://localhost:8080"],
      "env": {
        "PLOSTON_TOKEN": "your-token-here"
      }
    }
  }
}

Troubleshooting

Bridge won't start:

• Check that the CP URL is correct and reachable
• Verify the token is valid (if authentication is required)
• Check ~/.ploston/bridge.log for detailed error messages

Connection drops:

• The bridge auto-reconnects on connection loss
• Check network connectivity to the CP
• Increase --timeout for slow networks

Tools not appearing:

• Ensure the CP has tools configured
• Check that your token has permission to access tools
• Run ploston tools list to verify tools are available

ploston runner

Start a local runner that connects to a Ploston Control Plane and executes MCP tools locally.

# Start runner with config file
ploston runner start --config runner-config.yaml

# Start runner with inline MCP servers
ploston runner start --url http://localhost:8080 --mcps filesystem,memory

# Start runner with custom name
ploston runner start --url http://localhost:8080 --name my-runner --mcps filesystem

Option	Environment Variable	Description
--url	PLOSTON_URL	Control Plane URL (required)
--token	PLOSTON_TOKEN	Bearer token for authentication
--name	PLOSTON_RUNNER_NAME	Runner name (default: hostname)
--config	-	Path to runner config YAML file
--mcps	-	Comma-separated list of MCP servers to enable
--log-level	PLOSTON_LOG_LEVEL	Log level: debug, info, warning, error

Runner Configuration File

# runner-config.yaml
name: my-local-runner
control_plane:
  url: http://localhost:8080
  token: plt_xxx  # Optional

mcps:
  filesystem:
    command: npx
    args: ["-y", "@anthropic/mcp-server-filesystem", "/path/to/allowed"]
  memory:
    command: npx
    args: ["-y", "@anthropic/mcp-server-memory"]

How It Works

1. Runner connects to the Control Plane via WebSocket
2. Runner registers its available MCP tools with the CP
3. When a workflow needs a local tool, CP routes the request to the runner
4. Runner executes the tool via MCP and returns the result
5. If connection is lost, runner exits (code 1) for process supervisor restart

Use Cases

• Local file access: Execute filesystem tools on your machine
• Private APIs: Connect to internal services not accessible from the CP
• GPU workloads: Run ML inference tools on local hardware
• Development: Test MCP servers before deploying to production

Configuration

CLI Configuration

The CLI stores its configuration in ~/.ploston/config.yaml:

# ~/.ploston/config.yaml
server: http://localhost:8080
timeout: 30
output_format: text

Configuration precedence (highest to lowest):

1. CLI flags (--server)
2. Environment variables (PLOSTON_SERVER)
3. Config file (~/.ploston/config.yaml)
4. Default values

Environment Variables

Variable	Description	Default
PLOSTON_SERVER	Server URL	http://localhost:8080
PLOSTON_TIMEOUT	Request timeout (seconds)	30
PLOSTON_OUTPUT_FORMAT	Output format (text or json)	text

JSON Output

All commands support --json for machine-readable output:

# List workflows as JSON
ploston --json workflows list

# Run workflow with JSON output
ploston --json run my-workflow -i key=value

# Validate with JSON output
ploston --json validate workflow.yaml

Starting a Server

The CLI is a client only. To start a Ploston server, use the ploston package:

# Install the server package
pip install ploston

# Start the server
ploston-server --port 8080

Or use Docker:

docker run -p 8080:8080 ostanlabs/ploston:latest

Development

Prerequisites

• Python 3.12+
• uv package manager

Setup

make install

Commands

make help       # Show all commands
make test       # Run all tests
make test-unit  # Run unit tests only
make lint       # Run linter
make format     # Format code
make check      # Run lint + tests
make build      # Build package

Testing

Tests are organized across two locations:

Test Type	Location	Run Command
Unit tests	packages/ploston-cli/tests/unit/	make test-unit (in package)
Integration tests	packages/ploston-cli/tests/integration/	make test (in package)
E2E tests	tests/e2e/docker_compose/ (meta-repo)	make test-e2e-docker-compose (in meta-repo)

E2E tests live in the meta-repo because they require:

• Docker Compose infrastructure (CP running)
• Installed CLI (from test-pypi or local build)
• Coordination between multiple components (CLI, CP, Runner)

To run E2E tests:

# From meta-repo root
make test-e2e-docker-compose

Features

• HTTP-only client: No server dependencies, works with any Ploston server
• Server capability detection: Automatically detects available features from the connected server
• Rich output: Beautiful terminal output with colors and formatting
• JSON mode: Machine-readable output for scripting
• Local validation: Validate workflow YAML without server connection

Architecture decisions

The design decisions behind Ploston are recorded as ADRs: https://docs.ploston.ai/adr/

License

Apache-2.0

Disclaimer

This project is developed independently in a personal capacity and is not affiliated with, endorsed by, or connected to any employer. No proprietary or confidential information from any employer has been used in this project.