Quick Start

This guide gets you from zero to a published version in five minutes, assuming you can already sign in to a Packdog organization. If you can't yet, see Don't have access yet? at the bottom.

1. Install the CLI

npm install -g packdog

2. Sign in

packdog login

This opens your browser to a sign-in page and waits. Sign in there — the CLI catches the result on a local loopback redirect and you're signed in from any directory afterwards.

Confirm:

packdog whoami

packdog login signs you in as a human, with the role (admin or member) you hold in your organization. The session lives at ~/.config/packdog/config.json and works from any directory; the CLI refreshes it transparently. One session slot; running packdog login again replaces it.

For CI, you don't sign in — set a ci_* CI token via the PACKDOG_TOKEN env var instead (see CI usage in the CLI reference).

3. Find your package and link it

packdog packages
# → checkout-widget    pkg_8Kd2mZqR3nT5vWxYbCdE
# → promo-banner       pkg_4Qj7nLpV2sR9...

# In the directory of the package you'll work on (a name or a pkg_ id):
packdog link checkout-widget

This writes a one-field packdog.json — just the package id (link resolves the name to it for you). It is the identity of the directory; package commands read it when you don't pass --package=<id> explicitly. packdog.json is optional, never required.

4. Build and deploy

Build your package to dist/ with whatever toolchain you use (Vite, esbuild, Rollup, plain tsc — Packdog doesn't care). There's no required entry filename: Packdog stores the bundle and serves it from a baseUri, and you load whatever entry your bundle has — index.js, main.js, or an index.html if you embed via an <iframe>.

npm run build                          # produces dist/index.js (project-specific)
packdog deploy --channel=test --dir=dist  # upload dist/ and publish it to the test channel

Output:

Uploaded: ver_7Hq2Np4mR8Kt
Files: 3, Size: 45.2 KB
Published to test: ver_7Hq2Np4mR8Kt

deploy always needs a target channel (--channel) and a directory (--dir) — both explicit flags, no defaults. If you run the same deploy often, pin it in a package.json script.

Prefer a UI? The package page in the web panel (app.packdog.dev) has a Deploy button — drag your build folder in, review the file list, pick the channel. Same upload + publish underneath.

The target channel must already exist — deploy doesn't create channels. If you get a 404 ("Channel '...' does not exist — create it first"), an organization admin needs to create it once (packdog channels create <channel> -p <pkgId>, or via the web panel). A typo in --channel shows up here as a clear error instead of silently creating a junk channel.

5. Test and promote

Test the version on the test channel. When you're ready, promote that version to prod:

packdog promote --to=prod --from=test   # publish test's current version to prod

If something goes wrong:

packdog rollback --channel=prod

That's the loop. deploy to test → verify → promote to prod → rollback if needed.

---

Loading a package in the browser

The browser-side load uses your organization API key (load_...):

const { baseUri } = await fetch(
  'https://api.packdog.dev/v1/packages/PACKAGE_ID/channels/stable',
  { headers: { 'Authorization': 'Bearer load_yourkey' } }
).then(r => r.json());

// Append your bundle's own entry — there's no required filename.
const mod = await import(`${baseUri}/index.js`);
mod.mount(document.getElementById('root'), { baseUri });

baseUri is the root of the version's files. Append your bundle's own entry to load it (index.js here, or whatever you ship), and pass baseUri into the module so it can fetch its own assets. The organization key lives in browser JS by design — it's scoped to read-only loads of packages your organization owns.

---

If you're an organization admin

Signing in as an admin gives you the full CI-token toolset on packages your organization owns plus lifecycle ops a member or CI token doesn't have. There's no separate admin namespace — every command is top-level. The CLI routes to the self-service endpoint family for any signed-in user.

packdog login                                     # browser sign-in; your role comes from your org membership
packdog whoami                                    # confirm which org you're admin for
packdog packages create promo-banner --channels=test,prod   # create a package + its channels (pass --project=<name|id> if you have more than one project)
packdog channels create stage -p <packageId>      # add another channel later
packdog ci-tokens add "Marketing site CI"        # create a ci_ token (shown once); auto-granted to your sole project — manage grants/protected access in the panel
packdog ci-tokens list
packdog ci-tokens rename <id> "release pipeline"  # update the audit-log label
packdog ci-tokens delete <id> --confirm=<name>    # permanently revoke a token (no reactivate)
packdog usage                                     # last 30 days, per-package
packdog keys rotate                               # rotate org's load_ key

Every package lives inside a project — an admin creates the first project from the panel before any packages or CI tokens can be created. If your org has one project, packages create uses it automatically; with more than one, pass --project=<name|id>.

A CI token is scoped to the projects it is granted on — a token can hold grants on multiple projects, with a min-of-one-grant invariant. Each grant independently controls whether the token may publish to / roll back protected channels (can_publish_protected); grants are managed from the panel. Per-package CI grants are intentionally absent — authorization is per-project, the project being the team's unit of work.

An admin can deploy/promote/rollback its own packages directly, with no ci_ token needed — and may operate protected channels (ownership is the authorization, no grant needed):

packdog deploy --package=<id> --channel=test --dir=dist    # upload + publish
packdog promote --package=<id> --to=prod --from=test      # point a channel at a version
packdog rollback --package=<id> --channel=prod            # step a channel back — no checkout needed

Or hit the API directly — see API.md under "Organization-admin self-service (/v1/me/*)".

Or use the web panel — app.packdog.dev

Everything the CLI does as an admin, the web panel does too. It's the same /v1/me/* API behind a UI, authorized straight from your signed-in session. After signing in you land on your organization Overview (or directly in your project, if you have one). The top header carries your org name and a project picker; the sidebar is contextual nav.

At the org level you manage:

• Projects — create the projects your packages live in (an org starts with zero — create your first one here)
• Members — invite humans to the organization by email and set their role (admin or member); remove a member
• CI tokens — create ci_* tokens for machines (paste-once), grant them to projects, rename, delete
• Activity — the audit log across the whole organization
• Settings → Billing — your load key, your plan, and the link to Stripe's hosted billing portal (start on Free, upgrade to Pro when you go commercial)

Inside a project you manage its Packages (create, rename, delete; manage channels — create, publish, roll back, set protection, delete; inspect versions), its CI tokens and Members (per-project grants, each with an optional protected-channel toggle), and its Activity (audit log scoped to the project).

The CLI stays the canonical path for CI/CD and scripting; the panel is the more pleasant path for daily admin work. Both are scoped strictly to your organization — same as the /v1/me/* endpoints.

---

Don't have access yet?

Packdog is in a controlled launch. Two ways in: you're invited to an existing organization (you're emailed an invitation, you accept it and sign in), or you request access at packdog.dev — once approved you sign up, name your workspace, and you're the admin of your own org. Either way you sign in with packdog login (CLI) or the web panel; your role in the org (admin or member) decides what you can do.

The credentials you may also encounter:

• Organization API key (load_*) — loads packages from the browser
• CI token (ci_*) — a CI token an admin creates for a machine/pipeline

Email post@jetbit.no and we'll set up your organization and send the first admin an invitation. That admin can then invite the rest of the team and create CI tokens from the panel.

---

Next steps

• API reference for the full surface
• CLI reference for every command and flag
• Examples for real-world workflows
• Architecture if you want to understand how it works under the hood
• Pricing for the plans and what each includes