CLI Reference¶

Complete reference for all Ploston command-line interface commands.

Running the CLI¶

After installing Ploston CLI (pip install ploston-cli), the ploston command is available:

ploston <command>

Command Groups¶

Command	Description
`ploston bootstrap`	Set up the Ploston Control Plane (Docker Compose)
`ploston bridge`	Start an MCP bridge to the Control Plane (for Claude Desktop / Cursor / Claude Code)
`ploston init`	Initialize a new Ploston project in the current directory
`ploston inject`	Re-run config injection into MCP clients
`ploston server`	Manage MCP servers registered on the Control Plane
`ploston run`	Execute a workflow on the server
`ploston validate`	Validate a workflow YAML file
`ploston version`	Show version information
`ploston workflows`	Manage workflows (`list`, `show`)
`ploston tools`	Manage tools (`list`, `show`, `refresh`)
`ploston executions`	Inspect execution history (`list`, `show`)
`ploston runner`	Manage runners (`list`, `show`, `delete`, `get-token`, `regenerate-token`, `start`, `stop`, `status`, `logs`)
`ploston config`	Manage configuration (`show`, `set`, `unset`, `diff`)

Global Options¶

These options apply to all commands:

Option	Env Var	Description
`-s, --server URL`	`PLOSTON_SERVER`	Server URL
`-v, --verbose`	—	Increase verbosity (can be repeated: -vv)
`-q, --quiet`	—	Suppress output
`--json`	—	Output as JSON
`-k, --insecure`	`PLOSTON_INSECURE`	Skip SSL certificate verification
`--help`	—	Show help message

Server URL precedence:

--server flag
PLOSTON_SERVER environment variable
~/.ploston/config.yaml
Default: http://localhost:8022

Commands¶

`ploston bootstrap`¶

Set up and manage the Ploston Control Plane via Docker Compose.

ploston bootstrap [OPTIONS]

Use ploston bootstrap --help for a full list of options including --pre-release, --with-observability, status, down, and logs.

`ploston bridge`¶

Start an MCP bridge to the Control Plane. This is the primary integration point for Claude Desktop, Cursor, and Claude Code.

ploston bridge --url <cp-url> [OPTIONS]

Options:

Flag	Env Var	Default	Description
`--url URL`	`PLOSTON_URL`	(required)	Control Plane URL
`--token TOKEN`	`PLOSTON_TOKEN`	—	Bearer token for auth
`--timeout SECONDS`	`PLOSTON_TIMEOUT`	30.0	Request timeout
`--log-level LEVEL`	`PLOSTON_LOG_LEVEL`	info	`debug` / `info` / `warning` / `error`
`--log-file PATH`	`PLOSTON_LOG_FILE`	`~/.ploston/bridge.log`	Log file path (not stdout)
`--insecure`	`PLOSTON_INSECURE`	false	Skip SSL verification
`--tools MODE`	`PLOSTON_TOOLS`	all	`all` / `local` / `native` (legacy)
`--expose VALUE`	`PLOSTON_EXPOSE`	—	Inline filter (see below)
`--tags TAG`	`PLOSTON_TAGS`	—	Tag expression(s), repeatable
`--runner NAME`	`PLOSTON_RUNNER`	—	Runner name for disambiguation
`--retry-attempts N`	`PLOSTON_RETRY_ATTEMPTS`	3	Startup health check retries
`--retry-delay S`	`PLOSTON_RETRY_DELAY`	1.0	Delay between retries

Tool filtering — three modes:

--tools all|local|native (legacy, prefer --tags):
all — All tools: native-tools + local-runner + MCP servers (default)
local — Local-runner tools only
native — Native system tools only
--expose <value> — inline sugar:
--expose workflows → tag kind:workflow
--expose authoring → tag kind:workflow_mgmt
--expose <server-name> → tools from that MCP server only (e.g. --expose github)
--tags <expr> (preferred, repeatable, OR-ed):
--tags kind:workflow — workflow execution tools only
--tags kind:workflow_mgmt — workflow management tools only
--tags server:github — tools from a specific server
--tags source:runner — runner-hosted tools only
When --tags is provided it overrides --expose and --tools.

Pre-flight health check: When --expose <server> and --runner <name> are both set, bridge checks that the named MCP server is available on that runner before entering the stdio loop. If unavailable, it prints the error and crash log excerpt to stderr and exits 1.

Debug mode:

PLOSTON_DEBUG=1 ploston bridge --url http://localhost:8022
tail -f ~/.ploston/bridge.log

Setting PLOSTON_DEBUG=1 forces log level to debug regardless of --log-level.

Examples:

# Default: all tools
ploston bridge --url http://localhost:8022

# Workflow tools only (for a dedicated workflow agent bridge)
ploston bridge --url http://localhost:8022 --tags kind:workflow

# Specific MCP server only, with runner disambiguation
ploston bridge --url http://localhost:8022 --expose github --runner local

# Remote CP with auth
ploston bridge --url https://cp.example.com --token plt_xxxxx

`ploston init`¶

Initialize a new Ploston project in the current directory. Creates a starter config file and example workflow.

ploston init

`ploston inject`¶

Re-run Ploston config injection into MCP client config files (Claude Desktop, Cursor, etc.) without re-importing servers.

ploston inject [OPTIONS]

Options:

Option	Description
`--target TARGET`	Injection target(s), repeatable: `claude`, `cursor`, `claude-code`

`ploston server`¶

Manage MCP servers registered on the Control Plane.

`ploston server list`¶

List registered MCP servers on the CP.

ploston server list

`ploston server add`¶

Add an MCP server to the Control Plane.

ploston server add NAME --command CMD [OPTIONS]

Options:

Option	Description
`--command CMD`	Server command (e.g. `npx`, `uvx`)
`--args JSON`	Server args as JSON array
`--env JSON`	Environment variables as JSON object
`--detect`	Auto-detect available MCP servers
`--inject`	Inject into MCP client configs after adding
`--inject-target TARGET`	Injection target: `claude`, `cursor`, `claude-code`

Examples:

# Add manually
ploston server add fetch --command npx --args '["@mcp/fetch"]'

# Add and inject into Claude Desktop
ploston server add fetch --command npx --args '["@mcp/fetch"]' --inject

# Auto-detect available servers
ploston server add --detect

`ploston server remove`¶

Remove an MCP server from the Control Plane.

ploston server remove NAME [OPTIONS]

Options:

Option	Description
`--force`	Skip confirmation

`ploston run`¶

Execute a workflow on the Ploston server.

ploston run WORKFLOW [OPTIONS]

Arguments:

Argument	Description
`WORKFLOW`	Workflow name (registered on server)

Options:

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

Examples:

# Run with input parameters
ploston run hello -i name=Alice

# Run with inputs from file
ploston run process --input-file inputs.json

# Run with timeout
ploston run long-task --timeout 300

`ploston validate`¶

Validate a workflow YAML file.

ploston validate FILE [OPTIONS]

Options:

Option	Description
`--strict`	Treat warnings as errors
`--check-tools`	Verify tools exist on the server (requires connection)

Examples:

# Basic validation
ploston validate workflows/my-workflow.yaml

# Strict validation
ploston validate workflows/my-workflow.yaml --strict

# Validate and check tools are available
ploston validate workflows/my-workflow.yaml --check-tools

`ploston version`¶

Show version information (CLI and server).

ploston version

`ploston workflows`¶

Manage workflows on the server.

`ploston workflows list`¶

List registered workflows.

ploston workflows list

`ploston workflows show`¶

Show workflow details including YAML, inputs, outputs, and step definitions.

ploston workflows show NAME

`ploston tools`¶

Manage tools on the server.

`ploston tools list`¶

List available tools. Tools are listed with their canonical name. Runner-hosted tools appear as <runner>__<mcp>__<tool> (e.g. local__github__create_issue). CP-direct tools appear as their bare name.

ploston tools list [OPTIONS]

Options:

Option	Description
`--source TYPE`	Filter by source: `mcp` or `system`
`--server NAME`	Filter by MCP server name
`--status STATUS`	Filter by status: `available` or `unavailable`

`ploston tools show`¶

Show tool details including input schema and description.

ploston tools show NAME

`ploston tools refresh`¶

Refresh tool schemas from MCP servers.

ploston tools refresh [OPTIONS]

Options:

Option	Description
`--server NAME`	Refresh specific server only

`ploston executions`¶

Inspect workflow execution history. Shows execution history from TelemetryStore (OSS: 7-day rolling retention).

`ploston executions list`¶

List recent executions.

ploston executions list [OPTIONS]

Options:

Option	Default	Description
`--workflow NAME`	—	Filter by workflow name
`--status STATUS`	—	Filter by status: `pending`, `running`, `completed`, `failed`, `cancelled`
`--since DATE`	—	ISO date filter (e.g. `2026-03-01`)
`--limit N`	20	Max results to show

`ploston executions show`¶

Show execution details with step trace, outputs, and errors.

ploston executions show EXECUTION_ID

`ploston runner`¶

Manage runners (local tool execution agents).

`ploston runner list`¶

List all registered runners.

ploston runner list [OPTIONS]

Options:

Option	Description
`--status STATUS`	Filter by status: `connected`, `disconnected`

`ploston runner show`¶

Show runner details including status, available tools, and connection info.

ploston runner show NAME

`ploston runner delete`¶

Delete a runner registration.

ploston runner delete NAME [OPTIONS]

Options:

Option	Description
`--force`	Skip confirmation

`ploston runner get-token`¶

Get a runner's connection token for use with runner start.

ploston runner get-token NAME

`ploston runner regenerate-token`¶

Regenerate a runner's authentication token. The old token is immediately invalidated.

ploston runner regenerate-token NAME [OPTIONS]

Options:

Option	Description
`--force`	Skip confirmation

`ploston runner start`¶

Start the local runner daemon. The runner connects to the Control Plane via WebSocket and executes tools locally using MCP servers defined in the CP configuration.

ploston runner start [OPTIONS]

Options:

Option	Env Var	Description
`--cp URL`	`PLOSTON_RUNNER_CP`	CP WebSocket URL (required)
`--token TOKEN`	`PLOSTON_RUNNER_TOKEN`	Runner authentication token (required)
`--name NAME`	`PLOSTON_RUNNER_NAME`	Runner name / unique identifier (required)
`--daemon / --foreground`	—	Run as daemon (default) or in foreground
`--log-level LEVEL`	—	`debug` / `info` / `warning` / `error`

Examples:

# Start as daemon
ploston runner start --cp wss://ploston:8022/runner --token xxx --name my-laptop

# Start in foreground (for debugging)
ploston runner start --foreground --cp wss://ploston:8022/runner --token xxx --name my-laptop

`ploston runner stop`¶

Stop the local runner daemon.

ploston runner stop

`ploston runner status`¶

Check local runner daemon status (PID, CP connection, available tools).

ploston runner status

`ploston runner logs`¶

View local runner daemon logs.

ploston runner logs [OPTIONS]

Options:

Option	Default	Description
`-f, --follow`	false	Follow log output (like `tail -f`)
`-n, --lines N`	50	Number of lines to show

`ploston config`¶

Manage CLI and server configuration.

`ploston config show`¶

Show configuration. Without --local, fetches the server-side config.

ploston config show [OPTIONS]

Options:

Option	Description
`--section NAME`	Show specific section of server config
`--local`	Show local CLI config only (`~/.ploston/config.yaml`)

Examples:

# Show server config
ploston config show

# Show specific section
ploston config show --section mcp

# Show local CLI config
ploston config show --local

# Output as JSON
ploston --json config show

`ploston config set`¶

Set a CLI configuration value. Writes to ~/.ploston/config.yaml.

ploston config set KEY VALUE

Keys: server, timeout, output_format

Examples:

ploston config set server https://cp.example.com
ploston config set timeout 60
ploston config set output_format json

`ploston config unset`¶

Remove a CLI configuration value.

ploston config unset KEY

Keys: server, timeout, output_format

`ploston config diff`¶

Show diff between current server config and staged changes.

ploston config diff

Exit Codes¶

Code	Meaning
0	Success
1	Error (validation failed, config not found, connection refused, etc.)

CLI Reference¶

Running the CLI¶

Command Groups¶

Global Options¶

Commands¶

ploston bootstrap¶

ploston bridge¶

ploston init¶

ploston inject¶

ploston server¶

ploston server list¶

ploston server add¶

ploston server remove¶

ploston run¶

ploston validate¶

ploston version¶

ploston workflows¶

ploston workflows list¶

ploston workflows show¶

ploston tools¶

ploston tools list¶

ploston tools show¶

ploston tools refresh¶

ploston executions¶

ploston executions list¶

ploston executions show¶

ploston runner¶

ploston runner list¶

ploston runner show¶

ploston runner delete¶

ploston runner get-token¶

ploston runner regenerate-token¶

ploston runner start¶

ploston runner stop¶

ploston runner status¶

ploston runner logs¶

ploston config¶

ploston config show¶

ploston config set¶

ploston config unset¶

ploston config diff¶

Exit Codes¶

`ploston bootstrap`¶

`ploston bridge`¶

`ploston init`¶

`ploston inject`¶

`ploston server`¶

`ploston server list`¶

`ploston server add`¶

`ploston server remove`¶

`ploston run`¶

`ploston validate`¶

`ploston version`¶

`ploston workflows`¶

`ploston workflows list`¶

`ploston workflows show`¶

`ploston tools`¶

`ploston tools list`¶

`ploston tools show`¶

`ploston tools refresh`¶

`ploston executions`¶

`ploston executions list`¶

`ploston executions show`¶

`ploston runner`¶

`ploston runner list`¶

`ploston runner show`¶

`ploston runner delete`¶

`ploston runner get-token`¶

`ploston runner regenerate-token`¶

`ploston runner start`¶

`ploston runner stop`¶

`ploston runner status`¶

`ploston runner logs`¶

`ploston config`¶

`ploston config show`¶

`ploston config set`¶

`ploston config unset`¶

`ploston config diff`¶