CLI Command Reference

Complete reference for all Ploinky CLI commands. Commands are organized by category for easy navigation.

Note on command prefixes: The commands in this documentation are shown without the ploinky prefix, assuming they are run from within the project's interactive shell. For global usage from your system's terminal, prepend each command with ploinky (e.g., ploinky list agents).

Repository Management

add repo

Add a repository to your local environment.

add repo <name> [url]

Parameter	Description
`<name>`	Repository name (basic, cloud, vibe, security, extra, demo) or custom name
`[url]`	Git URL for custom repositories (optional for predefined repos)

Predefined repositories:

basic - Essential tools and shell environments
cloud - AWS, Azure, GCP integrations
vibe - Social media and communication tools
security - Authentication and encryption utilities
extra - Additional utilities and helpers
demo - Example agents and tutorials

# Examples
add repo cloud                                    # Add predefined cloud repository
add repo myrepo https://github.com/user/repo.git  # Add custom repository

enable repo

Enable a repository for agent listings.

enable repo <name>

# Example
enable repo cloud

disable repo

Disable a repository from agent listings.

disable repo <name>

list repos

List all available repositories and their status.

list repos

update repo

Pull latest changes from remote for a repository.

update repo <name>

# Example
update repo basic

Agent Operations

enable agent

Register an agent in workspace registry for management. Supports run location modes.

enable agent <name|repo/name> [global|devel [repoName]]

Mode	Behavior
isolated (omitted)	Agent runs inside a new subfolder named `<agentName>` in the current project directory.
global	Agent runs in the current project directory (legacy behavior).
devel <repoName>	Agent runs inside `.ploinky/repos/<repoName>` (repo must exist).

# Examples
enable agent demo                    # isolated (creates ./demo)
enable agent demo global             # run in current directory
enable agent demo devel simulator    # run inside .ploinky/repos/simulator

Note: Using enable agent is optional. You can enable repo then start <agent> directly; the agent will use the isolated mode and a subfolder <agentName> will be created.

refresh agent

Stops, removes, and re-creates the agent's container. This is a destructive operation that ensures the agent starts from a clean state. This command only has an effect if the agent's container is currently running.

refresh agent <name>
# Example
refresh agent demo  # stop, remove, and re-create the container for the 'demo' agent

list agents

List all available agents from enabled repositories.

list agents

Workspace Commands

start

Start agents from .ploinky/agents and launch Router.

start [staticAgent] [port]

Parameter	Description
`[staticAgent]`	Primary agent to serve static files (required first time)
`[port]`	Router port (default: 8080)

# First time setup
start demo 8080

# Subsequent starts (uses saved configuration)
start

shell

Open interactive shell session in agent container.

shell <agentName>

Attaches to a persistent container with full TTY support. Exit shell by typing "exit" to return to host.

cli

Run the agent's CLI command interactively. The manifest command is launched through the WebChat wrapper for a consistent chat-enabled TTY.

cli <agentName> [args...]

# Examples
cli MyAPI --help
cli PyBot --version

WebTTY Agent Shortcuts

Inside the Web Console/WebTTY, you can prefix a command with an agent name to run it inside that agent’s container via its CLI.

# In WebTTY shell
demo whoami     # opens 'cli demo', runs 'whoami', exits; shows only the command output
demo ls /       # same: runs 'ls /' inside the demo container and prints only its output

# Notes
- Output is trimmed to the subcommand’s result (not the intermediate 'cli demo'/'exit' steps).
- Requires the agent to define a cli command in its manifest; otherwise an error is shown.
- Works in WebTTY/WebConsole sessions that use bash (default). If bash is unavailable, the fallback shell may not support this shortcut.
- Equivalent to: open cli <agent>, run the subcommand, then exit.

status

Show workspace status including agents, router, and web services.

status

list routes

List configured routes from .ploinky/routing.json.

list routes

# Example output
Routing configuration (.ploinky/routing.json):
- Port: 8088
- Static: agent=demo root=/path/to/demo/agent
Configured routes:
- demo: hostPort=7001 container=ploinky_project_service_demo

restart

Restarts services. If an agent name is provided, it performs a non-destructive stop and start of that agent's container, preserving the container ID. This only affects running containers. If no agent name is provided, it restarts all agents and the router.

restart [agentName]

# Examples
restart          # Restart all agents and the router
restart MyAPI    # Stop and then start the existing container for MyAPI

Variables & Environment

var

Set a workspace variable (stored in .ploinky/.secrets).

var <VAR> <value>

Variable	Description	Default
`WEBTTY_TOKEN`	WebConsole authentication token	(randomly generated)
`WEBCHAT_TOKEN`	WebChat authentication token	(randomly generated)
`WEBDASHBOARD_TOKEN`	Dashboard authentication token	(randomly generated)
`WEBMEET_TOKEN`	WebMeet authentication token	(randomly generated)

# Examples
var API_KEY sk-123456789
var WEBTTY_TOKEN deadbeef
var WEBTTY_PORT 9000

vars

List all workspace variables.

vars

echo

Print the resolved value of a variable.

echo <VAR|$VAR>

# Examples
echo API_KEY      # Show raw value
echo $PROD_KEY    # Show resolved alias

expose

Expose variable to agent environment.

expose <ENV_NAME> <$VAR|value> [agent]

# Examples
expose DATABASE_URL $DB_URL myAgent
expose API_KEY $PROD_KEY            # Uses static agent

Web Interfaces

webconsole / webtty

Prepare access for the Web Console (synonyms). Prints URL with token. Use --rotate to mint a new token.

webconsole [shell] [--rotate]
webtty [shell] [--rotate]

# Examples
webconsole
webconsole --rotate
webtty sh
webtty /bin/zsh

Access at: http://127.0.0.1:8080/webtty?token=<WEBTTY_TOKEN>

Shell options: sh, zsh, dash, ksh, csh, tcsh, fish, or absolute path. When a shell is provided, the router is restarted (if previously configured) so changes apply immediately; otherwise changes take effect on next start.

webchat

Prepare access for the WebChat interface. Prints URL with token. You can pass either an agent name or a local script/program. If an agent name is provided, WebChat runs that agent's CLI (as ploinky cli <agentName>) when sessions start. If a local script/program is provided (relative or absolute path to an existing file), WebChat runs it directly. The configuration is saved as WEBCHAT_COMMAND.

Detection rules: if the first argument resolves to an existing file on disk (relative or absolute path), it is treated as a local script/program; otherwise, with a single token it is treated as an agent name; with multiple tokens and the first not a file, the entire string is saved as a raw command.

webchat [agentName|localScript [args...]|command...] [--rotate]

# Examples
webchat                          # ensure token and show URL
webchat demo                     # bind WebChat to run: ploinky cli demo
webchat ./scripts/menu.sh        # bind WebChat to a local script
webchat /abs/tool --flag         # bind WebChat to an absolute program path with args
webchat --rotate                # mint a new token
webchat "python bot.py"        # bind WebChat to a custom command string

Access at: http://127.0.0.1:8080/webchat?token=<WEBCHAT_TOKEN>

dashboard

Prepare access for the Dashboard. Prints URL with token. Use --rotate to mint a new token.

dashboard [--rotate]

Access at: http://127.0.0.1:8080/dashboard?token=<WEBDASHBOARD_TOKEN>

webmeet

Prepare access for WebMeet and optionally set a moderator agent. Prints URL with token.

webmeet [moderatorAgent] [--rotate]

Parameter	Description
`[moderatorAgent]`	Agent to use as moderator
`--rotate`	Generate a new token

Access at: http://localhost:8080/webmeet (proxied by the router)

Client Operations

client tool

Invoke any MCP tool exposed by your agents. RouterServer aggregates every registered MCP endpoint and routes the call to the agent that implements the requested tool.

client tool <toolName> [--agent <agent>] [--parameters <params> | -p <params>] [-key value ...]

Arguments

Parameter	Description
`<toolName>`	Name of the MCP tool to execute. Must be unique across agents unless `--agent` is provided.
`[--agent <agent>]`	Optional agent to target when multiple agents expose the same tool.
`[--parameters <params> \| -p <params>]`	Comma-separated list parsed into structured values (supports nested keys and arrays, e.g., `user.name=Jane,hobbies[]=read,write`).
`[-key value ...]`	Additional flag-style parameters appended individually. Flags without a value become booleans.

Examples

# Simple text echo
client tool echo -text "hello from cli"

# Disambiguate when multiple agents share a tool name
client tool plan --agent demo -p steps[]=research,build,ship

# Mix comma parameters with flag-style overrides
client tool process -p "config.level=high,filters[]=active" --dry-run

client list tools

List every MCP tool exposed by the agents managed by the router. The output is formatted as a readable bullet list.

client list tools

Example output:

- [demo] echo - Echo back provided text
- [demo] list_things - List example items for a given category
- [simulator] echo - Echo back provided text

If one of the agents fails to respond, the command prints a Warnings section listing the affected agents.

client list resources

List every MCP resource (e.g., health://status) exposed by registered agents.

client list resources

Example output:

- [demo] health://status - Health probe result
- [simulator] health://status - Health probe result

client status

Check the health status of a specific agent.

client status <agent>

System Management

stop

Stop all containers and services (preserves containers).

stop

shutdown

Stop and remove all workspace containers.

shutdown

clean / destroy

Remove all Ploinky containers from workspace.

clean
destroy

Warning: These commands are irreversible. All container data will be lost.

Logging & Monitoring

logs tail

Follow router logs in real-time.

logs tail [router]

# Examples
logs tail router    # Follow router logs

logs last

Show last N router log lines.

logs last <N>

# Examples
logs last 100           # Last 100 lines from router

Help System

help

Show general help or detailed help for specific commands.

help [command]

# Examples
help           # General help
help add       # Help for add command
help cli       # Help for cli command

Configuration Files

Workspace Directory Structure

.ploinky/
├── agents/           # Agent registry
├── repos/            # Downloaded repositories
├── routing.json      # Router configuration
├── .secrets          # Environment variables
└── running/          # PID files
    ├── router.pid
    ├── webtty.pid
    ├── webchat.pid
    └── dashboard.pid
logs/                 # Application logs
└── router.log

Agent Manifest (manifest.json)

{
  "container": "node:18-alpine",     // Container image
  "install": "npm install",          // Installation command
  "update": "npm update",            // Update command
  "cli": "node repl.js",            // CLI command for 'ploinky cli'
  "agent": "node server.js",        // Service command
  "about": "Description",           // Agent description
  "env": ["API_KEY", "DB_URL"],    // Required environment variables
  "enable": ["other-agent"],       // Auto-enable other agents
  "repos": {                       // Auto-add repositories
    "repo1": "https://..."
  }
}