CLI Command Reference

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

Repository Management

install / add

Install a repository checkout into your local environment. The URL is required, the repository name is optional, and the optional repo token is accepted for compatibility.

install [repo] <url> [repoName] [branch]
add [repo] <url> [repoName] [branch]

# Examples
install https://github.com/AssistOS-AI/demo.git demo
add repo https://github.com/user/repo.git myrepo main

uninstall / remove

Uninstall a repository checkout by name or URL. Ploinky disables enabled agents from that repository, removes their runtime containers, removes the repository checkout, and preserves source metadata for reinstall.

uninstall [repo] <repoName|url>
remove [repo] <repoName|url>

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. The update, update all, update repos, and update repo <name> forms refresh AchillesCopilotBasicSkills into eligible installed .ploinky/repos/ entries through the same default-skills behavior, skipping the AchillesCopilotBasicSkills source repo and skills-only repos. The all-repository form 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 also refreshes the runtime Achilles checkout and managed-repo 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 .data/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 installed 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 proxies=main

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

shell

Open an interactive shell session inside an agent runtime. For containerized agents this enters the agent container with full TTY support and the same mounted home directory the agent uses.

shell <agentName>

# Examples
shell codexAgent
ploinky shell codexAgent

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
ploinky cli codexAgent

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 WEBDASHBOARD_TOKEN deadbeef

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

webchat

Print the WebChat router login URL. WebChat does not use a surface-specific token.

webchat [--rotate]

# Examples
webchat              # show the router login URL
webchat --rotate     # accepted for compatibility; still uses router login

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]

Ploinky Shell

Ploinky Shell is an LLM-only helper mode for quick command recommendations without initializing the full workspace. It does not create a .ploinky folder, clone repositories, or start agents, and regular Ploinky workspace commands are rejected in this mode.

ploinky -shell            # interactive shell
ploinky --shell           # same as -shell
ploinky sh                # alias for Ploinky Shell
psh                       # alias for Ploinky Shell
ploinky -shell <text>     # single-shot suggestion and exit

• Single-command suggestions ask Execute? (y/n) before running.
• API keys are read from .env found upward from the current directory and from your environment variables.
• Startup logs show the .env path used and available LLM model names.
• Use /settings inside the shell to configure LLM model and provider preferences interactively.

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, remove ALL Ploinky runtimes in the workspace, and clear the regenerated dependency cache under .ploinky/deps/. clean is an alias for destroy. Persistent agent home data under .data/<agent-or-alias>/ is preserved and mounted again on the next start. 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
├── 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
└── deps/             # Dependency caches
    ├── global/
    └── agents/

.data/
└── <agent-or-alias>/ # Persistent agent home mounted at /root

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