The pckg CLI

Informative guide. This Book page explains Beskid but does not define the standard. For normative requirements, use the Beskid Standard.

import { Aside } from ‘@astrojs/starlight/components’;

beskid pckg is the toolchain entry for registry operations: credential configuration, artifact packing, upload, and related workflows implemented in the beskid_pckg crate and the pckg registry service.

Scaffolding templates use **`beskid new`**, not `pckg`. There is no `beskid pkg` command: `pckg` is the canonical spelling in every context.

Commands you will actually use

beskid pckg configure --api-key "$BESKID_PCKG_API_KEY"
beskid pckg whoami
beskid pckg pack --package acme.math --source . --output acme.math.bpk
beskid pckg upload acme.math --artifact acme.math.bpk

What happens during upload

1. beskid pckg pack: collects source, generates API docs for library packages, selects an exact semantic version, and assembles the .bpk artifact
2. beskid pckg upload: reads that version from artifact-root package.json and streams version, checksum, and artifact bytes to POST /api/packages/<name>/versions
3. Server-side validation: manifest integrity, checksum match, review/moderation policy enforcement
4. Catalog update: version appears in search and listing endpoints; project fetch/lock flows can resolve it

sequenceDiagram
  accTitle: Pack and upload to the registry
  accDescr: The author packs a bpk artifact with the CLI, the CLI uploads it to the registry, the registry validates and adds it to the catalog, and the CLI reports the result.
  actor Author
  participant CLI as beskid pckg
  participant Reg as pckg registry
  Author->>CLI: pack
  CLI-->>Author: .bpk artifact with exact version
  Author->>CLI: upload
  CLI->>Reg: POST /api/packages/name/versions
  Reg->>Reg: validate manifest, checksum, policy
  Reg-->>CLI: version published
  CLI-->>Author: Published name@version

Text equivalent: pack produces the artifact with its exact version. upload posts version, checksum and bytes to the registry, which validates them and adds the version to the catalog.

The registry does not assign a different version during upload. Package/version coordinates are immutable: publish a new artifact version instead of replacing existing bytes.

Authentication

beskid pckg loads credentials from, in order:

1. --bearer-token / --api-key CLI flags (highest priority)
2. BESKID_PCKG_TOKEN / BESKID_PCKG_API_KEY environment variables
3. .beskid/pckg/repositories.json (written by beskid pckg configure)

Publisher operations (upload, yank, unyank) require a valid publish-scoped credential.

See also

• pckg command reference: full subcommand and flag reference
• Publish a package: verified procedure with expected results and recovery
• Packages without npm trauma: chapter overview
• Doc and api.json: automatic doc generation during pack
• Registry client
• pckg client contract