packdog

CLI for the Packdog package registry — push, promote, and manage versioned web component packages. A product by Jetbit AS — contact: [email protected].

Installation

npm install -g packdog

To update to the latest version:

npm install -g packdog@latest

Setup

Sign in via the browser:

packdog login

This opens a WorkOS sign-in page in your browser and waits — the CLI runs a local loopback server, catches the redirect once you finish signing in, and saves your session to ~/.config/packdog/config.json. Works from any directory afterwards; the session's short-lived access token is refreshed for you transparently until you packdog logout.

packdog login gives you a signed-in WorkOS session — the human tier. For CI / automation, skip login entirely: create a CI token (ci_*) in the panel under Create CI token, put it in your secrets manager as PACKDOG_TOKEN, and the CLI uses it directly. Humans sign in, machines use the env var.

Note: the config file is created with mode 0600 on Unix. On Windows the chmod call is a no-op, so rely on standard filesystem permissions for the config directory.

Usage

packdog login                                # Sign in via browser (WorkOS)
packdog whoami                               # Show who you are logged in as
packdog list                                 # List packages you can act on
packdog init --id=<packageId>                # Write packdog.json (the package identity) here
packdog info                                 # Show package name, versions and channels
packdog push --channel=test --dist=dist      # Upload a build directory as a new version AND publish it
packdog promote --to=prod --from=test        # Point a channel at the version another channel holds
packdog promote --to=test --version=<id>     # Publish a specific version to a channel
packdog promote --to=test --version=latest   # Publish the newest uploaded version to a channel
packdog rollback --channel=prod              # Roll back a channel to its previous version
packdog versions                             # List all versions (uploader + active channels)
packdog channels                             # List all channels
packdog channels lock <pkg> <channel>        # Lock — publish/rollback 409 until unlocked
packdog channels unlock <pkg> <channel>      # Remove the lock
packdog history --channel=prod               # A channel's publish log, newest first
packdog audit                                # The package's audit log — who did what, when
packdog logout                               # Remove saved session
packdog --version                            # Show CLI version

push requires both --channel=<name> and --dist=<path> — no defaults, nothing read from packdog.json, so the command means the same thing in every directory. promote requires --to=<channel> plus exactly one source — --from, --version=<id>, or --version=latest. Every package command also accepts --package=<id> to override the directory's packdog.json.

The target channel must already exist — push and promote never create channels, and return 404 if the channel is unknown. Channels are created by an organization admin (packdog channels create, or packdog packages create --channels=...) or the operator. packdog channels shows a created-but-not-yet-published channel with its version as (empty).

Organization commands (require a signed-in session)

Signed in (not a ci_* CI token), you get lifecycle ops the CI token tier doesn't have. There's no admin namespace — every command is top-level, gated by the credential. With a ci_* CI token loaded, these refuse with a clear message naming the command and pointing at packdog login; no request is fired.

packdog ci-tokens list                          # List your CI tokens
packdog ci-tokens add "checkout-widget CI"      # Create a ci_ token (auto-scoped to the org's sole project; shown once)
packdog ci-tokens rename <id> <newName>         # Rename a CI token (audit-log label only)
packdog ci-tokens delete <id> --confirm=<name>  # Permanently delete a CI token (name-echo)

packdog channels create <packageId> <channel> [--protected]   # Create a channel on a package you own
packdog channels delete <packageId> <channel>                 # Delete a channel (versions kept)
packdog channels protect <packageId> <channel>                # Require protected access on the caller to publish/rollback
packdog channels unprotect <packageId> <channel>              # Reopen the channel

packdog packages create <name> [--project=<name|id>] [--channels=stage,test,prod]   # Create a package within a project (+ channels), within quota
packdog packages delete <packageId> --confirm=<name>          # Delete a package you own (name echo required)
packdog rename <packageId> <newName>             # Rename a package

packdog versions cleanup --package=<id> [--keep=N]            # Bulk-delete old unprotected versions
packdog versions delete <versionId> --package=<id>            # Delete one version (protected → 409)

packdog usage [--days=30]                        # Per-package load counts
packdog rotate-key                               # Rotate the org's load_ load key

Signed in, you can also push/promote/rollback packages your org owns directly — ownership is the authorization, protected channels included. Same commands as the CI token tier, with the package named by --package=<id>:

packdog push     --package=<id> --channel=test --dist=dist
packdog promote  --package=<id> --to=prod --from=test
packdog rollback --package=<id> --channel=prod
packdog versions --package=<id>
packdog channels --package=<id>
packdog history  --package=<id> --channel=prod
packdog audit    --package=<id>
packdog info     --package=<id>

Project setup

A packdog.json in the package root is an optional convenience — it holds only the package identity:

{ "packageId": "pkg_..." }

Run packdog init --id=<packageId> to generate it. It lets package commands resolve the package without an explicit --package=<id>; it is never required and carries nothing else — channel and build directory are always explicit flags, so a command behaves the same in every directory.

Workflow

# Build your package (project-specific — use your own build command)
packdog push --channel=test --dist=dist  # Upload the build directory and publish to the test channel
# test on the test channel...
packdog promote --to=prod --from=test    # Promote that version to prod when ready

Environment

Token resolution order:

1. PACKDOG_TOKEN environment variable
2. ~/.config/packdog/config.json (set by packdog login)

The package id resolves --package=<id> → PACKDOG_PACKAGE_ID → packdog.json. The CLI reads real environment variables only — it does not scan for .env files. To load one, use your shell, direnv, or dotenv-cli.

Exit codes

| Code | Meaning | |------|---------| | 0 | Success | | 1 | Usage error (missing argument or required flag, build directory not found, etc.) | | 2 | Client error from the API (4xx other than 429) | | 3 | Network error after retries exhausted | | 4 | push uploaded the version but the publish step failed — the version id is still in the output, retry with packdog promote --to=<channel> --version=<id> | | 5 | Server error after retries (5xx) or unparseable response |

Network errors and 5xx/429 responses are retried up to 3 times with exponential backoff before the CLI gives up.