npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@empresscli/cli

v0.34.1

Published

Command-line client for Empress: pull/push tenant theme source, deploy builds, and manage engine versions.

Readme

@empresscli/cli

Command-line client for Empress — a multi-tenant CMS platform built on Cloudflare Workers + Em-Dash.

Installs the binary as **empress** (the npm package is scoped because the unscoped empress name is taken).

This CLI handles the operator-side workflow:

  • Authenticate against your Empress control plane.
  • Pull and push tenant theme source (Astro project) to/from a real git repo hosted on T0 Artifacts.
  • Trigger tenant builds, tail logs, manage engine versions.
  • A fast static import-resolution preflight so broken relative imports fail locally in milliseconds instead of after a 20-minute build.

Install

npm  i -g @empresscli/cli
# or
pnpm add -g @empresscli/cli
# or
yarn global add @empresscli/cli
# or
bun  add -g @empresscli/cli

After install, the binary is **empress** on your PATH:

empress --version
empress --help

Requires Node.js ≥ 22.15 (the theme dev seed path uses node:sqlite, which is unflagged from 22.15).

Without a global install

If you prefer not to install globally (e.g. in a sandbox or CI), run it ad-hoc with npx:

npx -p @empresscli/cli empress --help

Things to know about the name

  • The npm package is **@empresscli/cli** (scoped). The unscoped name empress is taken on the registry, so npm i empress will not get you this CLI.
  • The binary the package installs is empress — that's what you type at the prompt. Do not run empresscli or cli; both will say "command not found".
  • All examples in this repo use empress ….

Updating

npm  i -g @empresscli/cli@latest
pnpm add -g @empresscli/cli@latest

empress --version reports the version baked into the published bundle.

Troubleshooting install

  • **Error: ENOENT: no such file or directory, uv_cwd** — your shell's current directory was deleted/renamed under it (common after a rm -rf/branch switch). Node can't read process.cwd(), so npm itself crashes before doing anything. Fix with cd ~ (or any real path), then re-run.
  • **403 Forbidden – PUT https://registry.npmjs.org/@empresscli%2fcli while publishing — your npm account requires 2FA. Re-run with npm publish --otp=<6-digit-code>.
  • **empress: command not found after global install — your global npm bin directory is not on PATH. Run npm bin -g to see where global binaries land and add that directory to your shell PATH. With Homebrew Node this is usually already wired up; with nvm/asdf/volta the bin path is per-version and is added when you select the version.

Quick start

empress login --base-url https://empress.example.workers.dev   # asks for the token, masked (or pipe it on stdin)
empress sites
empress pull --site my-tenant --to ./my-tenant-theme
cd my-tenant-theme
# … edit …
empress theme check                  # static preflight (also runs before push)
empress deploy                       # push, build, put it live — waits, prints the live URL
empress rollback                     # put the previous version back (same waiting, same URL)
empress status                       # is it live - and what to run next
empress theme merge-upstream       # merge in the latest platform template
empress theme catalog                # list templates/themes available to fork
empress theme create my-new-theme --from _default --group acme  # fork-by-default

Cheat sheet

| Goal | Command | | -------------------------------------------------- | ------------------------------------------------------------------------- | | Authenticate | empress login --base-url <url> (token at the prompt or on stdin) | | List sites you can access | empress sites | | Show one site | empress site info [--site <slug>] | | Pull tenant theme source (auto-types) | empress pull --site <slug> --to <dir> | | Pull without regenerating types | empress pull --site <slug> --to <dir> --no-types | | Pull and back up dirty files | empress pull --site <slug> --to <dir> --force | | Regenerate .emdash/types.ts | empress theme types | | Validate relative imports (no upload) | empress theme check | | Preview what a push would do | empress theme push --dry-run | | Save to the remote — does not deploy | empress theme push | | Push without the preflight | empress theme push --no-check | | Push, bypassing theme-shape validation errors | empress theme push --force | | Merge the theme's template updates in | empress theme merge-upstream | | Merge a specific upstream tag/branch | empress theme merge-upstream --ref <tag\|branch> | | List templates/themes available to fork from | empress theme catalog | | Fork a template/theme into a new theme | empress theme create <slug> --from <template\|theme> [--ref <tag\|sha>] | | Deploy history + recoverable snapshots | empress theme log <slug> | | Diff local tree (or 2nd snapshot) vs a snapshot | empress theme diff <slug> <run-id> [run-id2] | | Recover a deploy snapshot into the local tree | empress theme restore <slug> <run-id> | | Dev locally, seeded from production content | empress dev | | Dev with the offline seed / a SeedFile path | empress dev --seed starter\|<path> | | Dev against an empty local D1 (no seeding) | empress dev --no-seed | | Build locally against the prod engine (no deploy) | empress theme build | | Run the theme's vitest suite (after a build) | empress theme test [vitest args...] | | Run astro check on the theme (after a build) | empress theme typecheck | | Push, build, put it live; waits, prints the URL | empress deploy (--no-wait for scripts, --yes for a group theme) | | Put the previous version back | empress rollback | | The same deploy for a named site | empress theme deploy | | Build locally, upload artifact (dev loop only) | empress theme deploy --local | | Deploy without pushing (repo can't take a push) | empress theme deploy --force | | Merge the upstream template into a theme | empress theme merge-upstream | | List engine versions | empress engine versions | | Show which engine a site follows | empress engine track [--site <slug>] | | List a tenant site's collections (via the T1) | empress content collections [--json] | | List items in a collection (paged) | empress content list <collection> [--status S] | | Fetch / patch one item by id or item slug | empress content get\|patch <collection> <id> | | Create an item (auto-publishes; --draft to hold) | empress content create <collection> [--data '{…}'] | | Publish / unpublish one item | empress content publish\|unpublish <collection> <id> | | Inspect / edit a collection's field schema | empress content schema list\|get\|add-field\|remove-field … | | Upload / list / delete media (returns id + key) | empress media upload\|list\|get\|delete … | | List / get a nav menu, replace its items (live) | empress content menu list\|get\|set-items … | | Full-text search (title + excerpt) | empress content search <query> [--collection C] | | Distill a SeedFile from production content | empress content distill [--per-collection N] [--out F] | | Show custom-domain state + drift for a site | empress site domain show [--site <slug>] [--json] | | Sync domains (reconcile drift, optional redeploy) | empress site domain sync [--site <slug>] [--hostname H] [--yes] | | Fleet overview: engine drift, deploys, health | empress sites --overview [--json] | | Roll one site to the active engine (waits) | empress engine roll [--site <slug>] [--to <sha>] |

empress engine roll waits for the result by default: fast-forwardable tenants roll, tenants that need a theme merge are held (not failed) and listed at the end with the empress theme merge-upstream follow-up. Use --no-wait for the old fire-and-forget behavior.

Config

Credentials live at ~/.empress/credentials (mode 0600). Format:

{
  "current": "somos",
  "profiles": {
    "somos": { "baseUrl": "https://empress.example.workers.dev", "token": "epat_…" },
    "acme": {
      "baseUrl": "https://acme.example.workers.dev",
      "token": "epat_…",
      "defaultSite": "site-a"
    }
  }
}

One profile per workspace, named by its handle (the workspace name, hyphenated, unless empress login --workspace <handle> says otherwise). login adds or updates one and makes it current; --workspace <handle> on any command (or EMPRESS_WORKSPACE) acts in another for that command only, so empress deploy --workspace somos and empress deploy --workspace acme need no login in between. With more than one profile, the first line on stderr names the workspace. defaultSite (from login --site <slug>) is the site used outside a theme directory when no --site is given. EMPRESS_HOME moves the whole directory (tests use it).

Tokens are issued via your Empress control plane (Operator → CLI Tokens).

Why this CLI exists

A tenant theme is an Astro project that lives in a real git repository hosted on T0 Artifacts. Editing it from the Empress dashboard is fine for small text changes; for real theme work you want a local checkout, an editor, and the ability to push diffs surgically.

The CLI gives you an actual git flow: pull clones the repo the first time and fetches + fast-forwards after, theme push commits any dirty working tree and git pushes it. A diverged branch or a push the remote rejects surfaces as an ordinary git conflict, with the same remediation you'd get from git itself ("pull and merge, then push"). Template updates work the same way: theme merge-upstream fetches the theme's upstream (the platform template it was forked from) and merges it in — fast-forward when possible, an ordinary merge commit otherwise, and a real conflict is left in progress for you to resolve by hand (git add, git commit, theme push) rather than auto-resolved. Auth is a short-lived (1h, capped at 24h server-side), scope-limited token minted fresh per operation — never a durable credential on disk. A canonical .gitignore (build output, .cursor, .dev.vars, .wrangler, node_modules, .env*, etc.) is written on first clone unless the theme already ships its own.

Documentation

  • Agents learn from the platform, not from this package: connect the Empress connector (its address is on the MCP connector card in Settings, and in whoami) and read its skill index, skill://index.json; a site's theme brief is skill://theme-brief/<site>. A pulled theme carries a short AGENTS.md that points at both.

Development

pnpm install           # also runs `pnpm prepare` → builds dist/
pnpm dev               # tsup watcher
pnpm typecheck
pnpm lint
pnpm test

The published bin (bin/empress.mjs) imports the compiled output at dist/cli.js. Run pnpm build (or pnpm prepare) before invoking the bin in a fresh checkout.

License

MIT. See [LICENSE](./LICENSE).