@bettercms-ai/pull

Put the live BetterCMS build in a directory on a machine you own.

npx @bettercms-ai/pull --token bcms_dt_… --dir /var/www/mysite

It fetches the current live release, checks it against the checksum BetterCMS recorded at build time, unpacks it into a staging directory beside --dir, and swaps it in. Then it exits.

Get the token from Project → Settings → Custom hosting → Add target → Local machine. It is shown once. Losing it means creating a new target; that is also how you rotate it.

Options

| Flag | Env | | |---|---|---| | --token | BCMS_PULL_TOKEN | the deploy token | | --dir | BCMS_DIR | directory to unpack into | | --api | BCMS_API | API base URL (default https://api.bettercms.ai) | | --quiet | | only print on error |

Exit code is 0 when it deployed or when the directory already held that build, and 1 otherwise. Running it twice is safe and cheap: the second run reads the .bcms-release stamp, sees the same sha, and does nothing.

Deploying on every publish

bcms-pull runs once and exits — scheduling belongs to whatever already supervises this machine.

cron — every five minutes:

*/5 * * * * /usr/local/bin/bcms-pull --quiet --token bcms_dt_… --dir /var/www/mysite

systemd — a oneshot service plus a timer:

# /etc/systemd/system/bcms-pull.service
[Service]
Type=oneshot
Environment=BCMS_PULL_TOKEN=bcms_dt_…
Environment=BCMS_DIR=/var/www/mysite
ExecStart=/usr/local/bin/bcms-pull --quiet

# /etc/systemd/system/bcms-pull.timer
[Timer]
OnBootSec=1min
OnUnitActiveSec=5min
[Install]
WantedBy=timers.target

systemctl enable --now bcms-pull.timer

Windows — Task Scheduler:

schtasks /create /sc minute /mo 5 /tn bcms-pull ^
  /tr "npx @bettercms-ai/pull --quiet --token bcms_dt_… --dir C:\inetpub\mysite"

Serving the directory

--dir should be the web root, and it should belong to the agent. Point nginx/Caddy/IIS at it:

root /var/www/mysite;
try_files $uri $uri/ /index.html;

The directory is replaced by rename, so a request is served either entirely by the old build or entirely by the new one — never a mixture.

Windows caveat. A rename fails while another process holds a file under the directory open. When that happens the agent falls back to copying files over the old ones and deleting what is no longer in the build, prints a warning, and the site is briefly a mix of two builds. Give the agent a directory of its own rather than sharing one with something that keeps handles open.

What lands in the directory

The exact bytes the hosted site serves — the same artifact the BetterCMS pipeline unpacks, and the same one a Vercel or Netlify target receives. .git/, node_modules/, .gitignore and .DS_Store are excluded, and an archive containing a path that escapes --dir is refused rather than rewritten.

One extra file is written: .bcms-release, holding the sha and checksum of what is deployed. That is what makes re-running a no-op. Deleting it forces the next run to redeploy.

No token? Download it instead

Every project has Hosting → Download build, which hands back the same .tgz over a signed link. Unpack it yourself if this machine cannot run Node.