Agents

Agents

Agents should treat wgw-deploy as a command that turns a local static output folder into two URLs: one mutable live URL and one pinned revision URL.

Use --json for automation.

npx -y wgw-deploy --cwd /workspace/app --dir dist --json

Parse stdout as a single JSON object:

{
  "projectSlug": "bright-field-mqstr7zz",
  "productionUrl": "https://bright-field-mqstr7zz.wgw.lol/",
  "revisionUrl": "https://bright-field-mqstr7zz--26704cb219eb67f3.wgw.lol/",
  "projectHash": "4d0c...",
  "revisionId": "26704cb219eb67f3",
  "files": 18,
  "bytes": 428911,
  "uploadedAssets": 18
}

Return productionUrl when the user wants the latest preview. Return revisionUrl when the user needs an immutable artifact for review, debugging, reports, or evals.

Recommended flow

1. Build or generate static output.
2. Deploy the exact output path with explicit --cwd and --dir.
3. Use --json and parse stdout.
4. Report the live URL and pinned revision URL.
5. Use --list --json if you need to find existing local project state later.

npm run build
npx -y wgw-deploy --cwd /workspace/app --dir dist --json
npx -y wgw-deploy --list --json

The project key is local and deterministic for the resolved --cwd plus --dir. If an agent changes either value, it is targeting a different project.

Read the skill

Use --skill when the agent needs the packaged deployment instructions at runtime.

npx -y wgw-deploy --skill

--skill only prints markdown. It does not create, deploy, list, or delete anything.

Domains from agents

WGW subdomains are useful for named previews:

npx -y wgw-deploy --cwd /workspace/app --dir dist --domain review-123 --json

review-123 normalizes to review-123.wgw.lol.

External domains return a CNAME target in the dns object:

npx -y wgw-deploy --cwd /workspace/app --dir dist --domain docs.example.com --json

{
  "projectSlug": "bright-field-mqstr7zz",
  "productionUrl": "https://docs.example.com/",
  "projectHash": "4d0c...",
  "dns": {
    "type": "CNAME",
    "name": "docs.example.com",
    "value": "cname.wgw.lol"
  }
}

Agents should present the DNS record exactly:

CNAME docs.example.com -> cname.wgw.lol

Cleanup

Remove only the assigned custom domain:

npx -y wgw-deploy --cwd /workspace/app --dir dist --delete-domain --json

Delete the project:

npx -y wgw-deploy --cwd /workspace/app --dir dist --delete --json

Both commands use the same local project key as deploys. If the folder no longer exists, the CLI can still target the project from --cwd and --dir because delete and domain-delete do not require the deploy target to exist.

Error handling

Success JSON is printed to stdout. Errors are printed to stderr as text and the process exits non-zero.

Common errors agents should handle:

• no deploy target found: build output is missing. Run the build or pass the right --dir.
• not a file or directory: the explicit --dir path does not exist.
• could not reach the deploy API: network problem or invalid WGW_API_URL.
• bad project domain: invalid domain syntax.
• domain already assigned: requested WGW subdomain is already serving something.
• project ownership mismatch: the local project state does not match the remote project. Reuse the original --cwd and --dir.