Local development

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 requires a Pro plan or higher. 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 Pro or higher, then rerun the command.

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

3. Install Ploy agent skills

From the repository root, install Ploy's published agent skills:

Manage Ploy agent 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.

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.
  • 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, pages, 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 and pages

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

--cwd changes the checkout and defaults to the current directory. List commands support --limit 1..200, --cursor, --path, and --include-deprecated.

Read theme colors

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

Find a reusable pattern

Query the design system
ploy design-system query --query 'pricing card'

Plan a page build

Create a reuse-aware page plan
ploy design-system plan-page-build \
  --page-kind landing \
  --target-audience "growth teams" \
  --requested-sections "hero, proof, pricing, FAQ" \
  --requested-path /growth-teams

--requested-path must be a site route beginning with /. Add --cwd or --include-deprecated when needed.

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