---
title: Concepts
description: How projects, state, domains, and revision URLs work.
---

# Concepts

## Deploy target

The CLI resolves two paths before deploying:

- `cwd`: the project root. It defaults to the process current working directory.
- `dir`: the deploy target. It defaults to `dist`.

Relative `--dir` values are resolved from `cwd`.

```sh
npx wgw-deploy
npx wgw-deploy --dir public
npx wgw-deploy --cwd /path/to/app --dir build
```

The target can be a directory or a single file. Directory deploys walk the target recursively, skip symlinks, and ignore common project/cache directories such as `.git`, `node_modules`, `.cache`, `.turbo`, `.wrangler`, and `coverage`.

## Project hash

The local project identity is a hash of the resolved `cwd` and the deploy directory. The source formula uses:

- the literal namespace `wgw-project-v1`
- the SHA-256 hash of `cwd`
- the SHA-256 hash of the normalized deploy directory

The project hash is not the public project name. It is the local key used to find the matching project state for future commands.

Changing either `cwd` or `dir` changes the project hash. To keep deploying to the same project, use the same working directory and deploy directory, or pass the same `--cwd` and `--dir` values every time.

## Project state

The CLI stores project state on the local machine. The config root is resolved in this order:

1. `WGW_DEPLOY_CONFIG_DIR`
2. `$XDG_CONFIG_HOME/wgw-deploy`
3. `~/.config/wgw-deploy`

Project state is written to:

```txt
<config-root>/projects/<projectHash>/state.json
```

That file stores the public project metadata, API token, resolved `cwd`, deploy directory, and update time. `wgw-deploy --list` reads the local state directory and prints the tracked projects.

Deploy replay state is stored separately in the cache root, under `deploys/<projectSlug>/`. It is used to detect unchanged local files and report cached deploys.

## Project slug and default domain

When the CLI creates a new remote project, the service assigns a generated project slug. The default domain is:

```txt
https://<projectSlug>.wgw.lol/
```

The project metadata tracks the current domain, the latest revision ID, previous revision IDs, creation time, and expiration when applicable.

## Live URL

The live URL always points at the latest revision for the current domain.

```txt
https://<domain>/
```

After a new deploy finalizes, the service updates the project manifest so the live URL serves the new latest revision.

## Revision ID

A revision ID is derived from the deploy manifest. The service hashes the manifest JSON and uses the first 16 hex characters as the revision ID.

If the manifest does not change, the revision ID stays the same. If the deployed files change, the manifest changes and the next deploy gets a new revision ID.

## Pinned revision URL

Pinned revision URLs keep serving a specific revision.

For generated `wgw.lol` project domains and assigned `wgw.lol` subdomains, the pinned URL uses a revision subdomain:

```txt
https://<project-or-domain-prefix>--<revisionId>.wgw.lol/
```

For custom domains, the pinned URL uses the `_rev` path segment:

```txt
https://<custom-domain>/_rev/<revisionId>/
```

The CLI prints the pinned URL as `pinned` in text output and as `revisionUrl` in JSON output.

## Domains

The `--domain` flag assigns a domain to the locally tracked project. A domain can be:

- a `wgw.lol` subdomain
- a custom hostname

For a custom hostname, the CLI returns a CNAME record. Create that DNS record before relying on the custom domain. For a `wgw.lol` subdomain, the service can serve it directly.

Domain assignment is separate from deploying files. After changing the domain, run `npx wgw-deploy` to publish a new file revision if the output changed.

## Limits

The current deploy limits are:

- maximum files: 5,000
- maximum file size: 10 MB