CLI reference

Stable contracts for people, automations, and AI agents using ploy.

Syntax

ploy [global options] <command> [command options]

Global option	Meaning
`-v, --version`	Print the CLI version and exit `0`.
`-h, --help`	Show help and exit `0`.
`--dry-run`	Preview supported mutations. Not every command accepts it.
`--workspace <id>`	Override the effective workspace for one invocation.

Environment variables

Variable	Meaning
`PLOY_WORKSPACE_ID`	Workspace override below `--workspace` and above saved selection.
`PLOY_NO_UPDATE_CHECK=1`	Disable the best-effort daily update notice.
`XDG_CONFIG_HOME`	Change the parent directory used for CLI configuration.

Saved state

Config is stored at ~/.config/ploy/config.json, or $XDG_CONFIG_HOME/ploy/config.json when XDG_CONFIG_HOME is set. It is written with mode 0600 and may contain credentials plus selected workspace and site IDs.

Workspace and site resolution

--workspace <id>
PLOY_WORKSPACE_ID
The workspace saved by ploy workspace use
No workspace

Flags and environment variables do not update saved selection. Saving a different workspace clears the saved site. Commands that act on a selected site use the site stored by ploy site use.

Exit codes

Code	Meaning
`0`	Success. Without `--wait`, asynchronous work was accepted or rejoined.
`1`	Runtime, API, service validation, or terminal-operation failure.
`2`	CLI usage error.
`3`	Authentication required or credentials expired.
`4`	`site publish --wait` timed out; the publish is still running.
`5`	`site publish --wait` lost API contact; the publish is still running.

For asynchronous commands, use the returned operation or resource ID to inspect progress instead of starting duplicate work.

Agent and automation support

Area	`--json`	`--dry-run`	TTY notes
Workspace/site selection	Command-specific	Supported with explicit IDs	Selector requires a TTY
Site init/status/publish	Supported	Publish only	Not required with explicit context
Code Sync	No	No	Human-readable output
Variables, Secrets, dotenv	No	Set/import only	Prompt used when stdin/body omitted
Documents	Supported	No	`set` reads stdin
Ploybooks and schedules	JSON by default	Mutations	Files or inline content
Skills/design-system inspection	Command-specific	No	Local checkout required

Command index

CLI lifecycle

ploy update
ploy help [command]
ploy --version

Authentication

ploy login
ploy logout
ploy whoami
ploy tokens
ploy token revoke <target>

Workspaces and sites

ploy workspace list|use|current
ploy site list|use|init|status|publish
ploy site publish-status <operation-id>
ploy site code-sync init|sync

Configuration

ploy variable set|get
ploy secret set|get
ploy env set

Content and workflows

ploy documents list|get|set
ploy ploybooks list
ploy ploybook get|read|outline|read-section
ploy ploybook create|update|edit|delete
ploy ploybook schedule list|create|update|delete

Local development

ploy skills init|sync
ploy design-system list-components|list-pages
ploy design-system get-page-components|get-theme-colors
ploy design-system plan-page-build|query