CLI

Use packagepass for local setup, publishing, access grants, and release operations.

The CLI is the main operator workflow. It stores local configuration, validates packages before publish, wraps npm pack, creates install config, and exposes the same access-control model as the API.

install and inspect

npm install -g @packagepass/cli

packagepass --help
packagepass doctor

Configuration and environment

The CLI reads ~/.packagepass/config.json after login. Environment variables override saved config, which is useful in CI and scripted releases.

Setting	Purpose
`PACKAGEPASS_API_KEY`	Bearer token for the control API.
`PACKAGEPASS_TENANT`	Tenant slug or ID used when requests do not include a tenantId.
`PACKAGEPASS_API_URL`	Control API base URL. Default in the app is https://api.preview.packagepass.dev/v1.
`PACKAGEPASS_REGISTRY_URL`	npm-compatible registry URL. Default in the app is https://registry.preview.packagepass.dev/npm/.

interactive browser approval

packagepass login

packagepass login \
  --tenant acme \
  --api-url https://api.preview.packagepass.dev/v1 \
  --registry-url https://registry.preview.packagepass.dev/npm/

packagepass whoami

api key or automation

packagepass login \
  --api-key $PACKAGEPASS_API_KEY \
  --tenant acme \
  --api-url https://api.preview.packagepass.dev/v1 \
  --registry-url https://registry.preview.packagepass.dev/npm/

Browser-approved login creates a revocable API token named CLI login token. The intended default lifetime is 30 days, and the exact expiration is shown before approval and in Dashboard > Tokens. Existing browser-approved tokens keep their original expiration; revoke them and run packagepass login again to shorten local CLI access. Browser-approved login stores the organization slug when available; --tenant and PACKAGEPASS_TENANT also accept an organization ID for existing configs and automation.

Publishing

Create packages and publish releases

first release

packagepass package create @acme/payments \
  --description "Customer payments SDK"

packagepass publish ./packages/payments --tag latest

packagepass version list @acme/payments
packagepass dist-tag list @acme/payments

dry run

packagepass publish ./packages/payments \
  --tag next \
  --dry-run

Publish policy

Package names must be scoped, versions must be semver-compatible, and generated TypeScript libraries should publish ESM entrypoints, declaration files, and a package.json files list.

Preview packages

publish a preview

packagepass preview publish ./packages/auth \
  --channel pr-482

npm install @acme/auth@preview-pr-482

How preview versions work

The CLI creates a generated version like 0.0.0-preview.pr-482... and moves the dist-tag preview-pr-482 to that version.

Access control

Grant access and mint install tokens

A grant decides what a subject is allowed to do. A token is the credential the subject or automation uses to call the API or install from the registry.

grant package install

packagepass grant add @acme/payments \
  --subject customer:globex \
  --action install

packagepass grant list --package @acme/payments

create install token

packagepass token create install \
  --package @acme/payments \
  --subject customer:globex \
  --ttl 30d

packagepass setup @acme --manager npm --write

Subject syntax

Subject	Use
`user:alice@example.com`	A person identified by email.
`customer:globex`	A customer account or tenant in your product.
`agent:code-reviewer`	A non-human actor such as an AI agent, service, or CI job.
`group:platform`	A team or group.

Action names

package:read

package:install

package:publish

package:deprecate

package:yank

package:manage_dist_tags

grant:manage

token:mint

audit:read

Diagnostics

Debug installs and policy decisions

Use doctor for local config, control API auth, and registry install checks. A registry 404 can mean the current token can read the package record but lacks package:install access for npm, pnpm, Bun, or Yarn.

doctor

packagepass doctor @acme/payments

PACKAGEPASS_TOKEN=<install-token> \
  packagepass doctor @acme/payments

policy explain

packagepass policy explain @acme/payments \
  --subject user:alice@example.com \
  --action install

Command reference

Area	Command	Purpose
Auth	`packagepass login`	Start browser-approved CLI login; the resulting CLI login token expires after 30 days and can be revoked from Dashboard > Tokens. Existing browser-approved tokens keep their original expiry; revoke them and log in again to shorten them.
Auth	`packagepass login --api-key <token> --tenant <slug-or-id>`	Noninteractive API-key login for CI, scripts, and automation; the tenant may be an organization slug or ID.
Auth	`packagepass logout`	Remove the saved CLI config.
Auth	`packagepass whoami`	Print the current principal resolved by the API.
Tenant	`packagepass tenant create <slug> --name <name>`	Create a tenant. In the MVP this requires the bootstrap admin token.
Tenant	`packagepass tenant list`	List tenants visible to the current API token.
Package	`packagepass package create @scope/name`	Create package metadata before the first publish.
Package	`packagepass package list --scope @scope`	List packages, optionally filtered by scope or search query.
Package	`packagepass package get @scope/name`	Inspect one package record.
Package	`packagepass package archive @scope/name`	Archive package metadata.
Publish	`packagepass publish [dir] --tag latest`	Validate package.json, run npm pack, upload the tarball, and update the dist-tag.
Publish	`packagepass preview publish [dir] --channel pr-123`	Publish a generated preview version and attach it to preview-pr-123.
Install	`packagepass setup @scope --manager npm --write`	Generate npm, pnpm, Yarn, or Bun registry config for a scope.
Access	`packagepass grant add @scope/name --subject customer:globex --action install`	Allow a subject to read, install, publish, manage grants, or mint tokens.
Access	`packagepass grant list --package @scope/name`	Review grant records, optionally filtered by package.
Access	`packagepass grant revoke <grant-id>`	Remove a grant record.
Tokens	`packagepass token create install --package @scope/name --agent code-reviewer --ttl 30d`	Create a short-lived install token scoped to a subject and package.
Tokens	`packagepass token list`	Audit tokens.
Tokens	`packagepass token revoke <token-id>`	Revoke a token.
Release	`packagepass dist-tag list @scope/name`	Inspect package dist-tags.
Release	`packagepass dist-tag set @scope/name <tag> <version>`	Point a dist-tag at a version.
Release	`packagepass dist-tag rm @scope/name <tag>`	Remove a dist-tag.
Release	`packagepass version list\|get`	List or inspect package versions.
Release	`packagepass deprecate @scope/name@1.2.3 "message"`	Mark a version as deprecated with an install warning.
Release	`packagepass yank @scope/name@1.2.3`	Mark a version as yanked and remove dist-tags pointing to it.
Policy	`packagepass policy explain @scope/name --subject user:alice@example.com --action install`	Explain why a subject can or cannot perform an action.
Audit	`packagepass audit events --package @scope/name --limit 50`	Read package, grant, token, policy, and registry audit events.
CI	`packagepass ci exchange --provider github --id-token <token>`	Exchange a CI identity token for a PackagePass token.
Troubleshooting	`packagepass doctor [@scope/name]`	Check local config, API auth, registry metadata, and install-token policy diagnostics.

The same package, grant, token, policy, and audit operations are available from the TypeScript SDK and API.