Deploying stoop sites from a folder
stoop hosts static sites: plain HTML/CSS/JS in a folder, no build step
required and no site-side backend. npx @stoop/cli is the only tool you
need.
Writing any platform.* call? Load the stoop-platform skill first — it
is the full SDK surface, and guessing at this API produces a page that looks
right and silently loses data.
No folder and no terminal — a server-side app, bot, or CI job publishing at
runtime? That is the stoop-api skill, not this one.
Deploy
npx @stoop/cli deploy <dir>
- No login needed: the first deploy creates a public site with a generated URL that stays live for 24 hours. The CLI remembers which site this folder deploys to, so re-running the same command updates the same site.
- Every deploy ends with a smoke test of the live site (root page, SDK,
every collection the code uses) and exits non-zero if the deploy is live
but broken. Treat that exit code as the result;
--no-smokeskips the probe when you only need the upload. - The output includes the site URL and, for anonymous sites, a claim link. Always relay both to the user and mention the 24-hour expiry — opening the claim link in a browser signs the site over to their account so it is kept permanently.
- Deploy validates the folder first and refuses on errors (for example, no
root
index.html). Fix the findings instead of reaching for--force. - Never run
stoop loginyourself — it needs a human approving in a browser. If the user wants to keep sites or deploy to a named project, ask them to runnpx @stoop/cli loginthemselves. Once logged in, pass-p <slug>once per folder: a project that doesn't exist yet is created automatically (public, so anyone can visit — pass--visibility privatefor an org-members-only site), and the folder→project mapping is remembered from then on. - Deployed something by mistake? There is no
stoop delete. An unclaimed anonymous site expires on its own within 24 hours; a named project is removed from the dashboard, so ask the user. Never deploy a blank page over a site to "undo" it — that leaves the URL live and empty.
To validate without deploying: npx @stoop/cli check <dir>.
Constraints
- The deploy folder must have
index.htmlat its root. - Dotfiles,
node_modules, agent instruction files (AGENTS.md,CLAUDE.md), andskills-lock.jsonare never uploaded, so deploying the project root is safe.
The platform's own constraints — reserved URL paths, static-only, what the
SDK can and cannot do — are in the stoop-platform skill.
Keeping these skills current
npx @stoop/cli init installs the newest version of the stoop skills from
the skills.sh registry (npx skills add mislavjc/stoop) into
.agents/skills/ and points AGENTS.md at
.agents/skills/stoop/SKILL.md. If this copy looks stale, re-run init (or
npx skills update) — new platform features are documented there first.