Skip to main content
Publishing takes a built facet to the registry so others can install it. The flow is: sign in, build, publish. This guide covers each step and the outcomes you might hit. Before you start: a facet project with a valid facet.json and at least one asset (see Create Your First Facet), and a registry account with a — sign up at agentfacets.io and create a PAT in your account settings.

​
Authenticate the CLI

1

Login

facet login shows an interactive menu — choose “Paste a personal access token” and paste your PAT. The token is verified against the registry before it’s saved, so a typo or expired token fails immediately instead of surfacing later at publish time.
For CI, skip facet login and set FACET_TOKEN in the environment instead. It takes precedence over the saved credentials file.
2

Confirm your identity

facet whoami prints your username, email, and tier — and notes when the credential came from FACET_TOKEN rather than the saved file.

​
Build, then publish

1

Build the artifact

facet build writes dist/<name>-<version>.facet (a scoped name renders as a nested path, e.g. dist/@acme/cowsay-1.0.0.facet). Rebuild whenever your source has changed since the last build.
2

Publish it

facet publish resolves your credential, validates the manifest, finds the .facet in dist/, re-verifies its integrity, and uploads it under the artifact’s embedded name and version. It publishes what’s in dist/ — which is why the build step comes first.

​
When the build and source disagree

If dist/ was built from a different facet.json than what’s on disk now, publish detects the drift and asks what to do (in an interactive terminal):
  • Identity drift — different name or version. The usual case: you bumped version but didn’t rebuild. You can build and publish the current source, publish the existing artifact as-is, or cancel.
  • Content drift — same name and version, different content (an edited description or the private flag). You can rebuild and publish, or publish the existing artifact unchanged.
The full drift semantics are specified in Publish — drift.
In a non-interactive context (CI or piped stdin), both drift cases warn to stderr and ship the existing artifact unchanged. For strict CI, run facet build && facet publish as two separate commands so a stale dist/ can never be published silently.

​
Publish outcomes

A publish either goes live immediately, is queued for review (still a success — the version appears once approved), or is rejected because the version already exists. The full status table lives at facet publish.

​
Ship a new version

A published (name, version) is immutable, so every change ships as a new version:
1

Bump the version

facet modify updates facet.json for you (or edit the version field by hand).
2

Rebuild and republish

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 is a content change — and a published version can’t be changed. To flip visibility, set the flag, bump the version, rebuild, and republish:
Omitting private (or setting it false) keeps a facet public; true declares private publish intent. Who can see or download a private facet is enforced by the registry, not the CLI.

​
Sign out

facet logout deletes ~/.facet/credentials. It makes no server call — revoke PATs in the web UI.
If FACET_TOKEN is set, it keeps authenticating every command after logout. Run unset FACET_TOKEN to fully sign out of the current shell.

​
Environment variables

FACET_TOKEN (a registry PAT that takes precedence over the credentials file — use it for CI) and FACET_REGISTRY_URL (override the registry base URL) are documented in the environment variables reference.