CLI Command Reference

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

Repository Management

add repo

Add a repository to your local environment.

add repo <name> [url]

# 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

Update Ploinky-managed repositories and project repositories. The all-repository form first pulls repositories under .ploinky/repos/, then recursively discovers git repositories from the provided folder path, pulls each one, refreshes Achilles default skills in each discovered project repository, and updates each project repository's managed .gitignore block.

update [folderPath]
update all [folderPath]
update repos [folderPath]
update repo <name>

# Examples
update                    # Search from the current working directory
update /work/projects     # Search from an explicit folder
update all /work/projects # Same as update with an explicit all keyword
update repo basic         # Update one .ploinky/repos entry

Agent Operations

enable agent

Register an agent in workspace registry for management. Supports run location modes and optional aliases for multiple instances.

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

# 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
enable agent demo as demo2           # second container with alias "demo2"

Authentication Options

enable agent <name> [mode] [--auth none|pwd|sso] [--user <name> --password <value>] [as <alias>]

reinstall 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.

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

list agents

List all available agents from enabled repositories.

list agents

disable agent

Remove an enabled agent from the workspace registry. The agent container must be destroyed first.

disable <agentName|repo/name>

# Examples
disable demo               # remove short-named agent (if unambiguous)
disable repoName/demo      # remove agent using repo-qualified name

Workspace Commands

start

Start agents from .ploinky/agents.json and launch Router.

start [staticAgent] [port]

# First time setup
start demo 8080

# Subsequent starts (uses saved configuration)
start

shell

Open interactive shell session in agent container.

shell <agentName>

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>

# 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

/settings (alias: settings)

Interactively configure Achilles env flags used for LLM selection (works in both Ploinky CLI and Ploinky Shell).

/settings
settings

• Arrows: navigate variables and options; Enter: edit/set; Esc/Backspace: exit.
• Variables: ACHILLES_ENABLED_DEEP_MODELS, ACHILLES_ENABLED_FAST_MODELS, ACHILLES_DEFAULT_MODEL_TYPE, ACHILLES_DEBUG.
• Model lists are filtered by available API keys and show provider names; values are applied to the current process env (not persisted to .env).

expose

Expose a workspace variable to an agent. If the value is omitted, the command defaults to using $<ENV_NAME>. When the agent argument is omitted, the static agent configured via start is used.

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

# Examples
expose DATABASE_URL $DB_URL myAgent
expose API_KEY $PROD_KEY            # Uses static agent
expose AUTO_SECRET demo             # Uses value from $AUTO_SECRET

default-skills

Copy every skill directory from a skills repository into .claude/skills/ and .agents/skills/. Re-running the command replaces existing copied skill folders so removed upstream files do not remain, and the command keeps a managed .gitignore block up to date.

default-skills <repoName> [--only agent[,agent...]] [--skip agent[,agent...]]

# Examples
default-skills AchillesCopilotBasicSkills
default-skills AchillesCopilotBasicSkills --only claude-code

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

webchat

Prepare access for the WebChat interface. The command now only manages the access token and prints the router URL.

webchat [--rotate]

# Examples
webchat              # ensure token and show URL
webchat --rotate     # mint a new token

dashboard

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

dashboard [--rotate]

webmeet

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

webmeet [moderatorAgent] [--rotate]

Authentication

sso

Enable or disable an SSO provider agent for OIDC authentication.

sso [enable|disable|status]

# Examples
	sso enable    # Enable the SSO provider agent
	sso disable   # Disable SSO
	sso status    # Show current SSO provider

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

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

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

client list resources

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

client list resources

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

client status

Ping a specific agent over MCP and report whether the session responds.

client status <agent>

simulator: ok=true
MCP ping succeeded.

System Management

stop

Stop the router and all agent containers without removing them. Containers can be restarted later.

stop

shutdown

Stop the router and remove workspace containers listed in agents.json.

shutdown

destroy

Stop the router and remove ALL Ploinky containers in the workspace. clean is an alias for destroy.

destroy
clean

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

Dependency Management

deps prepare

Build dependency caches for agents. Merges globalDeps/package.json with agent package.json and runs npm install in the container.

deps prepare [<repo>/<agent>]

deps status

Show cache validation state for all agents.

deps status

deps clean

Remove dependency caches.

deps clean <repo>/<agent>|--global|--all

Profiles

Profiles control mount modes, environment variables, and lifecycle hooks per deployment stage.

profile show

Show the current active profile.

profile
profile show

profile <name>

Set the active workspace profile.

profile <dev|qa|prod>

profile list

List available profiles for an agent.

profile list [agentName]

profile validate

Validate profile configuration including required secrets.

profile validate <profileName> [agentName]

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.json       # Enabled agents registry
├── .secrets          # Environment variables
├── profile           # Active profile name
├── ploinky_history   # CLI command history
├── repos/            # Cloned repositories
├── agents/           # Per-agent work directories
├── code/             # Symlinks to agent code
├── skills/           # Symlinks to agent skills
├── logs/             # Router and watchdog logs
├── shared/           # Shared data
├── running/          # PID files
├── routing.json      # Router configuration
├── servers.json      # Web surface tokens
├── transcripts/      # Conversation transcripts
└── deps/             # Dependency caches
    ├── global/
    └── agents/

Agent Manifest (manifest.json)

{
  "container": "node:20-bullseye",
  "lite-sandbox": true,
  "runtime": { "resources": {} },
  "start": "/code/start_script.sh",
  "agent": "node server.js",
  "cli": "node repl.js",
  "readiness": { "protocol": "tcp" },
  "enable": ["other-agent global", "dep devel repoName"],
  "repos": { "repo1": "https://..." },
  "volumes": { "data": "/mnt/data" },
	  "ssoProvider": true,
  "profiles": {
    "default": {
      "env": { "NODE_ENV": "development" },
      "install": "npm install",
      "secrets": ["API_KEY"],
      "mounts": { "code": "rw" }
    }
  }
}