Publish a website
publish_sitePublish files as a live website, served over HTTPS at its own URL. Use it when a report, essay, slide-like narrative, dashboard, marketing surface, or other static artifact reads better at a live URL than as conversation text. Honor an artifact form the user requests. Otherwise choose the artifact form and treatment from its audience, job, and material. A request for a live URL chooses delivery, not one long scrolling page.
Apply the governance skill before calling: get_skill with governance says what the organization expects of a published page and names the design-system skill, which supplies identity, not structure. Follow each wherever it speaks.
title and description are required on every publish of files, and a call missing either is refused: title names the site for a person, and description says in one sentence what it holds. A site's name becomes part of its URL, so those two are what a reader has to go on wherever the site is listed. Write them for the person who will come back to this page in a month.
Content is text written here: HTML, CSS, JavaScript, Markdown, JSON, SVG. Images, PDFs, video, and other binary assets are not supported in files — publish those with the Valet CLI, or with push.
Send the site one of two ways. files carries the text of the pages in the call, which suits a few small pages and works from any client. push: {id, commit} publishes a commit you pushed with git: call create_push, run the recipe it returns, then pass the push_id and the commit sha it prints. Use push when you can run git with network access, when the site is large or holds binary files, or when you changed a clone of its source; it needs a site that exists and an account, not anonymous. Pass files or push, not both.
Publishing uses a connected Valet account by default and changes a permanent, private site that already exists: create it first with create_service (kind: site), then publish to its name. A name that holds no site is refused. Pass anonymous: true only when the user explicitly wants a temporary public site, which needs no create_service. It is public to anyone who has the link, and it may be removed 36 hours after it is created, unless it is claimed. The result carries a claim URL that moves the site into a Valet account and makes it permanent, and a site_token that updates the same site on a later call. Give that token back to revise the site instead of publishing a second copy of it; with an account, give the site's name instead.
In an organization with release policies, an account publish may answer with evaluation instead of a version: the release is built and waits for its policies, and get_evaluation with wait_seconds 20 follows it.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | The site's name, which is the first label of its URL, https://<name>.<org>.valet.run. The site must exist: create it first with create_service. Publishing to it replaces its files. Required with a connected Valet account; leave it out for an anonymous publish. | |
| push | No | Publish a Git push instead of files: the id create_push returned and the commit you pushed to its branch. Use it when you can run git with network access, because it sends only what changed. Pass files or push, not both; every other argument keeps its meaning. | |
| files | No | Required unless push is given. The site's files. One file named index.html is the minimum; add more for stylesheets, scripts, or further pages. | |
| title | No | Required with files. What the site is called, written for a person: 'Q3 Migration Audit', not a hostname. It labels the site wherever it is listed, so write the same thing the page's own <title> says. | |
| org_name | No | The Valet organization to publish into. Omit to use the organization the account joined first. | |
| anonymous | No | Set true only when the user explicitly wants a temporary public site without account ownership. Omit for the account-first path, which connects a Valet account when needed. | |
| site_token | No | The token an earlier anonymous publish returned. Give it back to update that same site instead of creating another. | |
| description | No | Required with files. One sentence saying what the site holds, for a person deciding whether to open it. It is shown beside the title wherever the site is listed. | |
| idempotency_key | No | An opaque key of your choosing. Repeating a call with the same key returns the first call's result instead of publishing again, which makes a retry safe. |