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.

Run help [command] to show general help or detailed help for a specific command.

help [command]

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 [folderPath]

Runs the full update workflow from the current directory or an explicit folder path. It updates the Ploinky checkout, the runtime node_modules/achillesAgentLib checkout, managed repositories under .ploinky/repos/, and recursively discovered project repositories. Missing or unreachable project remotes are logged and skipped.

update all [folderPath]

Runs the same full workflow as update with an explicit all-repository scope. Inside a Ploinky box, the read-only /opt/ploinky self-pull is skipped while writable runtime dependencies, managed repositories, workspace repositories, and skills continue to update.

update repos

Updates the installed repositories under .ploinky/repos/, refreshes the runtime Achilles checkout, and refreshes managed-repository achillesAgentLib dependencies.

update repo <name>

Updates one named repository, repairs it by recloning when its direct git metadata is missing but its source URL is known, refreshes its achillesAgentLib dependencies, and applies the default skills to that repository.

All update commands refresh AchillesCopilotBasicSkills, DocumentationSkills, and PloinkySkills in each eligible installed .ploinky/repos/ entry through the default-skills behavior. Each source repository is skipped when it is itself the target, as are skills-only repositories; refreshed project repositories also receive the managed .gitignore block.

Agent Operations

enable agent

Start one agent for the workspace. The command selects its run location and can assign an alias when a separate instance is required.

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

Stop one running agent and remove its workspace entry. Use this command when a single agent must no longer run in the workspace.

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. 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 an agent's CLI command interactively. The agent manifest must define a cli entry; that entry specifies the actual command Ploinky launches in the agent runtime.

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/. The default skill repositories are AchillesCopilotBasicSkills, DocumentationSkills, and PloinkySkills. 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
default-skills DocumentationSkills
default-skills PloinkySkills

Web Interfaces

Ploinky serves browser interfaces through the authenticated Router on the selected loopback port. The CLI does not publish an agent container port directly.

See Interfaces for the complete route families and authentication boundaries.

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

In the Ploinky REPL, stop stops the router and all agent runtimes without removing reusable runtime state or the outer box. From a host terminal, ploinky stop stops the same core services and then stops the managed 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

In the Ploinky REPL, destroy removes workspace runtimes and regenerated dependencies while leaving the outer Box and .data/ homes in place. From a host terminal, ploinky destroy removes the exact managed outer Box and discards its nested runtime layer and inner volumes. Workspace files and persistent agent homes remain; regenerated dependency and image caches are removed only when the corresponding cache-deletion option selects them.

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]