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 pulls the Ploinky checkout, refreshes the runtime node_modules/achillesAgentLib checkout, and then pulls repositories under .ploinky/repos/; if an installed repository is missing direct git metadata but has a known source URL, Ploinky reclones it on the recorded branch through a temporary sibling path and replaces the broken installed directory in place. It then recursively discovers git repositories from the provided folder path, pulls each one when its remote is reachable, logs and skips project repositories with missing or unreachable remotes, refreshes Achilles default skills in each discovered project repository, and updates each project repository's managed .gitignore block. The update repos form refreshes the runtime Achilles checkout plus installed .ploinky/repos/ entries and their Achilles dependencies.

update [folderPath]
update all [folderPath]
update repos
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

disable agents-all

Attempt to disable every enabled agent in .ploinky/agents.json without destroying containers.

disable agents-all

Workspace Commands

start

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

start [staticAgent] [port] [--branch <branch>] [--repo-branch <repo=branch>]... [--branch-fallback default|fail] [--reset-repos]

# First time setup
start demo 8080

# Subsequent starts (uses saved configuration)
start

# Branch-aware fresh workspace
start AchillesIDE/explorer 8080 --branch feature-branch

# Per-repo branch override
start AchillesIDE/explorer 8080 --branch feature-branch --repo-branch webmeetInfra=main

# Strict CI/deploy mode
start AchillesIDE/explorer 8097 --branch feature-branch --branch-fallback fail --reset-repos

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

Refresh every skill directory from a skills repository under .agents/skills/. Re-running the command replaces only same-named source skill folders so removed upstream files do not remain, preserves unrelated existing skills, migrates legacy .claude/skills/ skills into .agents/skills/, and keeps a managed .gitignore block up to date.

default-skills <repoName>

# Examples
default-skills AchillesCopilotBasicSkills

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

When opening WebChat with an explicit agent selection such as /webchat?agent=achilles-cli&path=/absolute/path, the router forwards every additional query parameter except its internal session parameters to ploinky cli achilles-cli as single-token long-form CLI arguments such as --path=/absolute/path.

Slash Command Autocomplete

Inside WebChat, typing / opens a command suggestion menu populated from the agent's MCP tool catalog. Navigate with Arrow Up/Down, insert with Enter or Tab. The menu filters as you continue typing. If the agent exposes no MCP tools, the menu stays silent (no error).

Cancel Button

While the agent is processing, the Send button is replaced by a Cancel button. Clicking Cancel sends an interrupt signal (ESC) to the agent's TTY session, aborting the current operation. The Send button returns when the agent produces output or the session closes.

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 runtimes without removing reusable runtime state. Containers can be restarted later. Host-sandboxed agents are signaled in a batch before Ploinky waits for exits.

stop

shutdown

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

shutdown

destroy

Stop the router and remove ALL Ploinky runtimes in the workspace. clean is an alias for destroy. Host-sandboxed agents receive the graceful signal together, then any remaining process groups are force-killed after the shared timeout.

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 target runtime's install backend.

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" }
    }
  }
}