Publishing Packages
To publish, sign in, create a scope for your packages, describe the package in its manifest (Defining a Package), and run zena pkg publish. There is no registry account to make: you sign in with the account you already have on Bluesky or another AT Protocol service.
1. Sign in to the CLI ​
Sign in with zena pkg login and your handle:
zena pkg login alice.bsky.social
It opens your browser at your account's PDS, where you approve zena. Your PDS sends the browser on to this site, which hands the sign-in back to zena. On a machine with no browser, as over SSH, or with --no-browser, zena pkg login prints the address to open in a browser elsewhere, and you paste the line the page then shows into the terminal.
zena asks to write release attestations to your repository and to call the registry as you, and nothing else. A session lasts up to two weeks; then zena asks you to sign in again.
For scripts, sign in with an app password instead (on Bluesky, Settings → Privacy and security → App passwords), over standard input or in ZENA_APP_PASSWORD:
echo "$APP_PASSWORD" | zena pkg login alice.bsky.social --password-stdin
zena pkg login stores the session in $ZENA_CONFIG_DIR/session.json (default ~/.config/zena/session.json) with owner-only file permissions (0600). Run zena pkg logout at any time to revoke the session and remove the file.
2. Create a scope ​
Every package hosted on pkg.zena-lang.dev belongs to a scope, such as acme. A scope is an account of its own on the registry (acme.pkg.zena-lang.dev), whose maintainers decide who creates packages in it.
Create a scope before publishing your first package to it:
zena pkg scope create acme
You can also set a display name, description, and website for the scope's public page:
zena pkg scope profile acme \
--display-name "Acme Corp" \
--description "HTTP and routing libraries for Zena" \
--website "https://acme.example.com"
3. Prepare zena-package.json ​
To be published, a package's zena-package.json must include name, version, description, and license (an SPDX license expression such as MIT or Apache-2.0):
{
"name": "acme:router",
"version": "1.0.0",
"description": "HTTP request router for Zena",
"license": "MIT",
"exports": {
"server": {}
}
}
The library server is src/server.zena: a package's libraries are in src/ unless its source says otherwise.
Closed exports
Defining exports makes the package closed: dependents can only import the library names listed in exports, keeping internal helper files private to your package. See Package Manifests for details.
4. Publish a release ​
From the package directory, run zena pkg publish:
zena pkg publish
The name is the package's name after its scope, acme:router. If the name has no scope, pass --scope <name> on the command line, and the CLI writes it into the name:
zena pkg publish --scope acme
When zena pkg publish runs:
- Account creation (first publish only): When
zena-package.jsonhas nodidfield, the CLI asks the registry to create a new package account (router.acme.pkg.zena-lang.dev) and writes the resultingdidintozena-package.json. Commit this updatedzena-package.jsonso future releases publish to the same DID. - Archive packing and upload: The CLI packs the package's source files and manifest into a deterministic IPLD CAR archive and uploads it as a blob to the registry.
- Attestation: The CLI writes a signed
dev.zena-lang.package.attestationrecord into your own atproto repository, attesting to the release record's AT-URI and CID. - Release commit: Once the package's required number of maintainers (
threshold) have attested the release, the registry commits thedev.zena-lang.package.releaserecord into the package's repository.
5. Approving multi-maintainer releases ​
When a package is configured to require more than one maintainer approval (for example, 2 of 3 maintainers, or human approval of a CI publish), zena pkg publish holds the release in a pending state on the registry.
Other maintainers can inspect the pending release and its diff or metadata with zena pkg approve:
# Inspect what is waiting for approval
zena pkg approve router.acme.pkg.zena-lang.dev@1.0.0
# Write your attestation and complete the release once the threshold is met
zena pkg approve router.acme.pkg.zena-lang.dev@1.0.0 --yes
Pending releases also appear on the package's web page and on /me when signed in to pkg.zena-lang.dev.
Retracting a version ​
Published versions are immutable and cannot be overwritten. If a release has a critical bug or security issue, mark it as retracted so version selection skips it:
zena pkg retract 1.0.0 --reason "Broken header parsing on empty values; upgrade to 1.0.1"
Existing workspaces that already pinned 1.0.0 in zena-lock.json continue to build reproducibly, while zena pkg add and zena pkg update skip retracted versions and the web UI marks the version as retracted.