CLI Commands
The zena CLI includes all package manager commands alongside the compiler, test runner, formatter, and linter.
Starting a package ​
zena pkg init ​
zena pkg init [<dir>] [--name <name>] [--scope <scope>]
Makes the current directory, or <dir>, a package by writing its zena-package.json. It creates <dir> if it does not exist yet.
--name <name>: The package's name. Defaults to the directory's name, which must then be a valid package name: lowercase letters, digits and-, starting with a letter.--scope <scope>: The scope the package is published in, which goes before its name:--scope acmenames itacme:<name>.
The version starts at 0.1.0. zena pkg init never overwrites an existing zena-package.json.
Dependency management ​
zena pkg add ​
zena pkg add <package>[@<version>] [--name <local-name>]
Adds a published package to the current package's zena-package.json, selects versions across the workspace, updates zena-lock.json, and fetches the resolved archives into the package cache.
<package>:scope:name, a handle (router.acme.pkg.zena-lang.dev), or a DID (did:plc:...,did:web:...).@<version>: Optional version to start the range from; the manifest gets^<version>. Without it,zena pkg addtakes the package's latest release that is neither retracted nor a pre-release, or, when it has no such release, its latest pre-release that is not retracted, and says so.--name <local-name>: Local import alias inzena-package.json(defaults to the name in the package's profile).
zena pkg update ​
zena pkg update [<local-name>...]
Selects versions again for the specified dependencies (or all dependencies when none are named), taking the latest non-retracted version their ranges allow instead of the version zena-lock.json pins, updates zena-lock.json, and fetches any new archives. The manifests do not change.
zena pkg add and zena pkg update both take --duplicates allow|warn|error: what to do when no one version of a package is in every range that asks for it, so that two are installed. allow, the default, lists them; warn prints a warning; error refuses and writes nothing. "duplicates" in the workspace root's zena-package.json sets the default.
zena pkg fetch ​
zena pkg fetch
Downloads and unpacks every package archive pinned in zena-lock.json into the local package cache, verifying every release record and source archive against its pinned CID. Modifies no workspace files.
Authentication ​
zena pkg login ​
zena pkg login <handle-or-did> [--no-browser] [--password-stdin]
Signs in to an AT Protocol account with OAuth. It opens the browser at the account's PDS, where you approve, and the registry's sign-in page hands the answer back to zena. With --no-browser, or where there is no browser to open, as over SSH, it prints the address to open, and reads the line the page shows from the terminal. With --password-stdin or ZENA_APP_PASSWORD, it signs in with an app password instead. Saves the session to $ZENA_CONFIG_DIR/session.json.
zena pkg logout ​
zena pkg logout
Revokes the current session at the PDS and removes $ZENA_CONFIG_DIR/session.json.
Publishing & releases ​
zena pkg publish ​
zena pkg publish [--scope <name>] [--registry <url>] [--yes]
Packs and publishes the package in the current directory at the version in zena-package.json. Creates the package account on first publish when zena-package.json has no did, in the scope its name gives (acme:router), or --scope, which it then writes into the name.
zena pkg create ​
zena pkg create [--scope <name>] [--registry <url>] [--yes]
Creates the package's account on the registry and writes its did into zena-package.json without publishing a release.
zena pkg approve ​
zena pkg approve [<package>@]<version> | <scope> | <package> [--yes]
Without --yes, shows the release, or the changes to who belongs and to settings, waiting for approval. With --yes, writes your attestation record to your repository and submits it to the registry.
zena pkg retract ​
zena pkg retract <version> [--reason <text>]
Publishes a dev.zena-lang.package.retraction record for <version> so version selection skips it.
zena pkg ci create ​
zena pkg ci create <scope>/<name>
Creates an automation account in <scope> for CI pipelines to publish as, and prints its token once. CI keeps the token as the secret ZENA_REGISTRY_TOKEN and runs zena pkg publish, signed in to nothing.
zena pkg ci token ​
zena pkg ci token <scope>/<name>
Gives the automation account a new token, for one that leaked or was lost. The old token stops working.
zena pkg ci retire ​
zena pkg ci retire <scope>/<name>
Retires the automation account, for CI that no longer runs: its token stops working, and it gets no other. The registry refuses while a package's maintainers name it.
Scopes, organizations, teams & maintainers ​
zena pkg scope ​
zena pkg scope create <scope> [--yes]
zena pkg scope info <scope>
zena pkg scope profile <scope> [--name <text>] [--description <text>] [--website <url>]
zena pkg scope maintainers <scope>
zena pkg scope add <scope> <person> [--role <publisher|owner>]
zena pkg scope add <scope> --team <org>/<team> [--role <publisher|owner>]
zena pkg scope remove <scope> <person>
zena pkg scope remove <scope> --team <org>/<team>
zena pkg scope settings <scope> [--owner-threshold <n>]
zena pkg scope policy <scope> [--minimum-threshold <n>] [--minimum-humans <n>] [--default-teams <org>/<team>:<role>,...] [--default-threshold <n>] [--default-owner-threshold <n>] [--default-humans <n>]
zena pkg scope upgrade <scope> --yes
zena pkg scope join <scope> <org>
zena pkg scope leave <scope>
Creates scopes and manages their profile, their maintainers (publisher and owner), how many owners must approve a change, and their policy for their packages. upgrade makes a scope an organization; join and leave put a scope in an organization and take it out. See Scopes, Orgs & Teams.
zena pkg org ​
zena pkg org add <org> <person>
zena pkg org remove <org> <person>
zena pkg org members <org>
Manages an organization's members, the people its teams can have.
zena pkg team ​
zena pkg team create <org>/<team>
zena pkg team delete <org>/<team>
zena pkg team members <org>/<team>
zena pkg team add <org>/<team> <person> [--role <member|maintainer>]
zena pkg team remove <org>/<team> <person>
zena pkg team settings <org>/<team> [--threshold <n>]
Creates and manages an organization's teams.
zena pkg owner ​
zena pkg owner list [--package <package>]
zena pkg owner add <person> [--role <publisher|owner>] [--automation] [--package <package>]
zena pkg owner add --team <org>/<team> [--role <publisher|owner>] [--package <package>]
zena pkg owner remove <person> [--package <package>]
zena pkg owner remove --team <org>/<team> [--package <package>]
zena pkg owner settings [--threshold <n>] [--owner-threshold <n>] [--humans <n>] [--package <package>]
Lists and changes a package's maintainers (publisher and owner) and its approval thresholds: the package in the current directory, or the one --package names by scope:name, handle or DID. --automation marks an automation account from zena pkg ci create.
Environment variables ​
| Variable | Default | Description |
|---|---|---|
ZENA_REGISTRY |
https://pkg.zena-lang.dev |
The registry publish, scope, org, team and owner call |
ZENA_CONFIG_DIR |
~/.config/zena |
Directory where session.json is stored |
ZENA_CACHE_DIR |
~/.cache/zena |
Base directory for the unpacked package cache (packages/sources/<cid>) |
ZENA_PROJECT_CACHE |
(unset) | When set, stores the package cache in .zena/packages inside the workspace |
ZENA_APP_PASSWORD |
(unset) | An app password, which zena pkg login signs in with instead of OAuth |
BROWSER |
the system's | The command zena pkg login opens the sign-in address with |
ZENA_REGISTRY_TOKEN |
(unset) | An automation account's token, which zena pkg publish uses in CI |
ZENA_PLC_DIRECTORY |
https://plc.directory |
PLC directory URL used to resolve did:plc: identities |
ZENA_DNS_OVER_HTTPS |
https://cloudflare-dns.com/dns-query |
DNS-over-HTTPS endpoint used to resolve _atproto.<handle> TXT records |