Skip to main content
Publishing takes a built facet to the registry. Sign in, build, publish. You need a facet project with a valid facet.json (see Create a Facet) and a registry account at agentfacets.io.

​
Authenticate

Follow the verification page and finish account setup if requested. For Windows or personal access token entry, see facet login. facet whoami confirms the identity you will publish as.
In CI, skip interactive login and set FACET_TOKEN. See credential precedence if a saved token shadows browser sign-in.

​
Build, then publish

facet build writes dist/<name>-<version>.facet. facet publish validates the manifest, finds that archive, re-verifies its integrity, and uploads it under the name and version embedded in the artifact. It publishes what is in dist/, which is why you build first.

​
When the build and source disagree

If dist/ was built from a different facet.json than the one on disk, publish detects the drift and asks what to do:
  • Identity drift: a different name or version, usually because you bumped the version without rebuilding. Build and publish current source, publish the existing artifact, or cancel.
  • Content drift: same name and version, different content. Rebuild and publish, or publish the existing artifact unchanged.
See drift semantics.
Without a terminal, both cases warn on stderr and ship the existing artifact. Run facet build and facet publish as separate commands in CI so a stale dist/ cannot publish silently.

​
Publish outcomes

A publish goes live, is queued for review (still a success, and it appears once approved), or is rejected because the version already exists. See publish outcomes.

​
Ship a new version

A published name and version pair is immutable, so every change ships as a new version:
If you forget to rebuild, publish catches the identity drift and offers to build for you.

​
Changing visibility

The private flag is manifest content, so changing it needs a new version:
Omitting private keeps a facet public. Who can see or download a private facet is enforced by the registry. See Private Facets for scopes and access.

​
Sign out

See facet logout for browser session revocation, offline local cleanup, and personal access token removal. If your shell supplies FACET_TOKEN, unset it separately.FACET_TOKEN and FACET_REGISTRY_URL are documented in the environment reference.