Local development

Last updated

Connect a Ploy site to your preferred coding agent without losing the site's design system or Ploy-native workflow.

Complete local development workflow
ploy site use
ploy site code-sync init
# Follow the printed setup and clone instructions
ploy skills init
# Let your agent work, review its changes, and push them to GitHub main
ploy site code-sync sync
ploy site publish --wait

Code Sync is included with every paid plan. If setup is not available for the selected site, the CLI provides a link to finish setup in Ploy.

1. Select the site

Choose the workspace and site you want to work on. Interactive selection requires a terminal.

Select and confirm the site
ploy workspace use
ploy site use
ploy site status

2. Initialize Code Sync

Prepare a GitHub repository for the selected site:

Initialize Code Sync
ploy site code-sync init

The CLI prints the connection status, setup links, and HTTPS and SSH clone commands. If prompted, open the setup link and upgrade the workspace to a paid plan, then rerun the command.

Use one of the printed clone commands and keep your work on main.

3. Install Ploy agent skills

Ploy's public agent skills are maintained in the Ploy-AI/ploy-tools repository. The repository includes the ploy-site skill for migrating an existing GitHub or local website into Ploy with Codex, Claude Code, or Cursor.

Install the migration skill

The recommended installer adds the Ploy CLI and bootstraps the public skills for your user, so they are available from any project:

Install the CLI and public skills
curl -fsSL https://ploy.ai/install.sh | sh

To install the skill directly into the repository you are working in instead:

Install from the public repository
npx skills add Ploy-AI/ploy-tools

You can also review or download the ploy-site skill from GitHub. Keep the complete skill folder, including its references directory.

After installation, open the site repository in your coding agent and ask:

Use the ploy-site skill to migrate this site into Ploy.

Install skills in an existing Ploy site

From the repository root, install the skills published for that Ploy site:

Manage Ploy site skills
ploy skills init
ploy skills sync
ploy skills sync --check

The project defaults to the current directory. It must be a Ploy site with a regular, non-symlink package.json whose name is exactly ploy-web. If that name differs, ploy skills init fails with Run this command from a Ploy site.

Where skills are installed

Installed skill paths
.agents/skills/<id>/SKILL.md
.claude/skills/<id>/SKILL.md
  • skills init installs the published catalog without overwriting existing files.
  • The catalog includes a Migrate Site skill. Ask your coding agent to use it to move an existing website, including a WordPress site, into your Ploy site with the Ploy CLI. It works in a local copy of your Ploy site, so it needs Code Sync, which is available on paid plans.
  • skills sync replaces edited Ploy-managed files and removes managed skills no longer in the catalog.
  • skills sync --check makes no changes and exits 1 when managed content has drifted.
  • Unmanaged files and skill directories remain untouched.

Ownership is recorded in .ploy/skills.json. The lock file .ploy/.skills.lock serializes runs. Symlinks and unmanaged same-ID collisions fail closed. Skills commands do not support --dry-run.

4. Inspect the design system

Design-system commands give your agent concrete information about the checked-out site's theme and reusable components. They do not require login or a selected workspace.

The checkout must contain src/pages. The local inspection runtime requires bash and either node or bun on PATH.

Explore components

Inspect the component graph
ploy design-system list-components
ploy design-system list-components --path "src/components/sections/**/*.tsx" --limit 50

--cwd changes the checkout and defaults to the current directory. list-components supports --limit 1..200, --cursor, --path, and --include-deprecated.

Read theme colors

Inspect active theme tokens
ploy design-system get-theme-colors

5. Let your agent work

Ask your agent to make the change in the cloned repository. It should follow the installed Ploy skills, reuse the site's registered components, and preserve the active theme tokens.

Review and test the changes locally, then commit and push them to GitHub main.

6. Sync changes back to Ploy

Import GitHub main into Ploy
ploy site code-sync sync

Ploy imports the latest GitHub commit into the selected site's workspace. If the import reports a conflict, resolve it in the editor and retry the sync.

7. Publish when ready

After reviewing the synced site in Ploy, publish it and wait for production to reach a final state:

Publish to production
ploy site publish --wait

The command exits 0 only when production reaches ready. A timeout or lost API connection can mean the publish is still running; use the printed operation ID with ploy site publish-status to check it.

Keep going