CLI reference

Last updated October 19, 2026

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

Import a dotenv file into a specific Ploy environment with:

ploy env set --env production --env-file .env.production

For prerendered Astro routes, variables are read at build time through import.meta.env. Astro's framework prefix rules still apply, including the PUBLIC_ prefix for values exposed to client code. Publish again after changing a build-time variable.

Variable	Meaning
`PLOY_API_TOKEN`	Workspace-scoped credential for headless authentication. Takes precedence over stored login credentials.
`PLOY_WORKSPACE_ID`	Workspace override below `--workspace` and above the API token pin.
`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 organization, workspace, and site IDs.

Workspace and site resolution

--workspace <id>
PLOY_WORKSPACE_ID
The workspace pinned to PLOY_API_TOKEN
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.

If you selected an organization with ploy organization use, the API rejects a workspace outside it.

The token pin is enforced by the API, not by local precedence. If --workspace or PLOY_WORKSPACE_ID selects a different workspace, the request exits 1 with This API token is scoped to a different workspace.

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`	Plan upgrade required after an API `402` response.
`5`	site publish --wait, ploy chat --wait, or ploy chat wait timed out; the work is still running.
`6`	`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
Domains	Supported	No	Uses the selected site; no `--site` option
Routing rules	Supported	`routing set`	`set --file -` reads stdin
Code Sync	No	No	Human-readable output
Variables, Secrets, dotenv	No	Set/import only	Prompt used when stdin/body omitted
Databases	Supported	CSV import	Row values and CSV imports can read stdin
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

Every list command accepts --json.

Command index

CLI lifecycle

ploy update
ploy help [command]
ploy --version
ploy completions zsh|bash|fish

Authentication

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

Workspaces, sites, domains, and routing

ploy workspace list|use|current|create
ploy organization list|use|create
ploy site list|use|init|status|publish|delete
ploy site init --from <path> creates a new site from a compatible Astro repository; see Bring your own repo.
ploy site visitors
ploy site publish-status <operation-id>
ploy domain list|add|status|remove|move
ploy site routing get|set
ploy site code-sync init|sync
ploy site git clone|sync

Integrations

ploy integrations mcp add|list|inspect|update|enable|disable|remove|reconnect
ploy integrations mcp auth-status|auth-cancel
ploy integrations mcp tools list|refresh|allow|deny

Configuration

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

Databases

ploy database list|create|rename|archive|copy|delete|operation
ploy database table list|create|duplicate|rename|delete
ploy database column list|add|rename|retype|secret|delete
ploy database row list|add|upsert|update|delete
ploy database import

Assets and forms

ploy asset list|copy
ploy form list|copy|delete
ploy form notifications get|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
ploy chat start|send|answer|questions|stop|list|read|wait|get|rename|delete|mark-read|upload

Local development

ploy skills init|sync
ploy design-system list-components|get-theme-colors

Look up identified visitors with `ploy site visitors`

Authenticate, have access to the workspace, and select a site unless you supply its ID explicitly. An authorized workspace member can read these results.

This read-only command lists identified people and companies, not necessarily all site traffic. It does not start a Ploy. See Visitor Identification for what identified visitors represent.

ploy site visitors

Read the first page, then use the printed next offset to continue. An empty list is not an error. Keep the same filters and sort when paging through results.

ploy site visitors --offset <next-offset>

Option	Purpose
`--id <site-id>`	Read visitors for an explicit site instead of the selected site.
`--type person\|company`	Show named people or company-level matches.
`--search <text>`	Find a case-insensitive substring in name, company, domain, or job title.
`--sort lastSeen\|visits`	Order by last activity or visit count. The default is `lastSeen`.
`--limit <n>`	Choose rows per page, from 1 to 100. The default is 25.
`--offset <n>`	Skip rows to continue pagination. Start at 0 and follow the printed next offset.
`--json`	Print machine-readable JSON.

ploy site visitors --type company --search acme --sort visits --limit 25

ploy site visitors --id <site-id> --limit 25 --offset 0 --json

Check ploy --version and ploy site visitors --help on your machine. If the command is missing, follow Installation and updates.

Push code with Git using `ploy site git`

Use ploy site git to clone a site's code and push your changes back with plain Git. It is available on paid plans only and does not need GitHub. You need the CLI installed, to be signed in, and the Member role or higher in the workspace.

Command	Purpose
`ploy site git clone <directory>`	Clone the selected site's code into a directory. The clone has a Git remote named `ployspace`.
`ploy site git sync`	Bring the commits you pushed to `ployspace` into the site in Ploy.

ploy site init --wait
ploy site git clone my-site
cd my-site
git pull --rebase ployspace main
# make and commit your changes
git push ployspace HEAD:main
ploy site git sync

Ploy's Agent can edit the same code. Pull with git pull --rebase ployspace main before you push so you don't overwrite its changes. Syncing does not publish. Publish as a separate step when you're ready.

Custom MCP servers with `ploy integrations mcp`

Available in CLI 0.15.0 and later. Signing in with OAuth needs 0.16.0 or later. Run ploy update to get the latest version. These commands manage the MCP servers you connect so Ploy's Agent can use their tools. Ploy only calls tools you allow. See Connect your own MCP server for how this works in the app.

ploy integrations mcp add <name> --url <url> [--auth auto|oauth|bearer] [--token-stdin] [--no-browser] [--json]

Command	Purpose
`add <name> --url <url>`	Add a server. Ploy saves it turned off until you approve tools and enable it. Use `--auth` to choose how to sign in: `auto` (the default) detects what the server supports, `oauth` signs in through your browser, and `bearer` uses a token. Use `--token-stdin` to read a bearer token from standard input, for example in a script. Use `--no-browser` to get an authorization link to open yourself instead of opening a browser. Use `--json` to print one receipt without prompts.
`list`	List your MCP servers.
`inspect <conn>`	Show one server's details.
`update <conn> --name <name>`	Rename a server.
`enable <conn>`	Turn a server on. Approve at least one tool first.
`disable <conn>`	Turn a server off without removing it.
`remove <conn>`	Delete a server and its stored token.
`reconnect <conn>`	Sign in again or replace the token. This clears tool approvals and turns the server off, so approve its tools and enable it again.
`auth-status <operation-id>`	Check an OAuth sign-in using the operation ID from the add or reconnect receipt.
`auth-cancel <operation-id>`	Cancel a pending OAuth sign-in.
`tools list <conn>`	List a server's tools.
`tools refresh <conn>`	Check the server for new or changed tools.
`tools allow <conn> <tool> --revision <revision>`	Approve one tool. Get the revision from inspect.
`tools deny <conn> <tool> --revision <revision>`	Remove approval for one tool. Get the current revision from inspect.

Shell completions

Turn on tab completion for ploy commands in your shell, then open a new terminal.

echo 'source <(ploy completions zsh)' >> ~/.zshrc

echo 'eval "$(ploy completions bash)"' >> ~/.bashrc

ploy completions fish > ~/.config/fish/completions/ploy.fish

Workspace transfer commands in CLI 0.12.0

These commands use explicit source and destination workspace context. Cross-workspace copy and delete operations require browser-backed ploy login, not a workspace API token.

Command	Purpose
`asset list --from-workspace <id> --limit <n> --offset <n> --json`	Inventory public-library assets. Follow pagination.
`asset copy <id> --from-workspace <source> --to-workspace <destination> --json`	Copy an asset without removing the source.
`database copy <id> --from-workspace <source> --to-workspace <destination> --operation-key <uuid> --json`	Start an independent database copy. Poll its operation in the destination workspace.
`database delete <id> --from-workspace <id> --confirm-database <id> --json`	Archive the database and revoke its tokens.
`env copy --from-workspace <source> --to-workspace <destination> --from-site <source-site> --to-site <destination-site> --env production --json`	Copy environment values. Replace source-dependent credentials before publishing.
`form list --from-workspace <id> --site <id> --json`	Inspect captured submissions. Add `--include-data` to include submitted fields.
`form copy --from-workspace <source> --to-workspace <destination> --from-site <source-site> --to-site <destination-site> --json`	Copy history without mail. Add `--copy-settings` to include notification settings.
`form notifications get\|set --from-workspace <id> --site <id> --json`	Inspect or configure recipients. `set --emails '[]'` disables mail. `set --owner-default` restores the workspace owner default.
`form delete <id> --from-workspace <id> --site <id> --json`	Delete the specified captured submission.
`domain move <hostname> --from-workspace <source> --to-workspace <destination> --from-site <source-site> --to-site <destination-site> --json`	Move a domain and its apex or WWW companion after destination verification.
`site delete <id> --from-workspace <id> --confirm-site <id> --json`	Delete a site while retaining shared library assets and databases.

See Move a site between Ploy workspaces for prerequisites, dependency handling, verification, cutover, and cleanup.