CLI Command Reference

Complete reference for the managed host supervisor and the in-box Ploinky core CLI. 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/; inside a Ploinky box, the read-only /opt/ploinky self-pull is skipped while the writable runtime Achilles dependency, managed repositories, workspace repositories, and skills continue to update. 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. In the managed box, Router always owns inner port 8080. The canonical host form puts --port before start; it selects only the physical-host loopback side of the fixed mapping. The public wrapper also accepts the documented positional host-port shorthand and converts it to the same outer selection before forwarding fixed inner 8080.

# Ploinky REPL / core
start [staticAgent] [8080] [--branch <branch>] [--repo-branch <repo=branch>]... [--branch-fallback default|fail] [--reset-repos]

# Host supervisor (canonical)
ploinky [--port <hostPort>] start [staticAgent] [branch-options...]

# 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 through the public wrapper; host loopback 8097, inner 8080
ploinky --port 8097 start AchillesIDE/explorer --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

Print the staged candidate from .ploinky/routing.json. This command does not inspect, prove, or activate the current immutable authorization generation.

list routes

# Example output
Routing configuration (.ploinky/routing.json):
- Port: 8080
- Static agent: demo
- Routes:
  demo -> agent=demo method=- hostPort=-

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

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

Workspace Path Autocomplete

Typing @ opens a generic file and folder menu rooted at the workspace-confined dir supplied when WebChat was opened. Continue typing to filter the current folder, select a folder to drill into it, and select a file to insert a cwd-relative token such as @src/index.js. The menu returns at most 30 entries per folder and does not depend on the selected agent.

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.

/status

This is a local-control read-only surface, not a token-minting CLI command. It requires a real router-authenticated local-admin session on an exact local-control Host; assertions, invitations, media credentials, and localhost provenance do not grant administrator access.

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

This unprefixed REPL command stops the router and all agent runtimes without removing reusable runtime state or the outer box. 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

This unprefixed REPL command stops the Router, removes workspace Ploinky runtimes, and clears the regenerated dependency cache under .ploinky/deps/. Persistent agent home data under .data/<agent-or-alias>/ and the outer box are preserved. Host-sandboxed agents receive the graceful signal together, then any remaining process groups are force-killed after the shared timeout.

destroy

clean

This unprefixed REPL command runs the same workspace-runtime removal and dependency-cache cleanup without explicitly stopping the Router first. Use destroy when the Router must also be stopped.

clean

Logging & Monitoring

logs tail

Follow Router logs by default, or one enabled agent in real-time.

logs tail [router|<agent>] [--startup]

# Examples
logs tail            # Follow Router logs
logs tail myAgent    # Follow one agent

logs last

Show the last N Router lines by default, or the last N lines for one enabled agent.

logs last [<N>] [router|<agent>] [--startup]

# Examples
logs last 100           # Last 100 Router lines
logs last 100 myAgent   # Last 100 agent lines

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      # Staged candidate; inert until coordinated apply
├── edge-generations/ # Immutable validated route-and-policy generations
├── topology/         # Box-owned non-secret topology generations
├── 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" }
    }
  }
}