---
title: Agents
description: Practical patterns for coding agents that publish static output with wgw-deploy.
---

# 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.

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

Parse stdout as a single JSON object:

```json
{
  "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.

```bash
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.

```bash
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:

```bash
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:

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

```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:

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

## Cleanup

Remove only the assigned custom domain:

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

Delete the project:

```bash
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`.