@empresscli/cli
v0.34.1
Published
Command-line client for Empress: pull/push tenant theme source, deploy builds, and manage engine versions.
Maintainers
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 unscopedempressname 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/cliAfter install, the binary is **empress** on your PATH:
empress --version
empress --helpRequires 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 --helpThings to know about the name
- The npm package is
**@empresscli/cli**(scoped). The unscoped nameempressis taken on the registry, sonpm i empresswill not get you this CLI. - The binary the package installs is
empress— that's what you type at the prompt. Do not runempresscliorcli; 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@latestempress --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 arm -rf/branch switch). Node can't readprocess.cwd(), sonpmitself crashes before doing anything. Fix withcd ~(or any real path), then re-run.**403 Forbidden – PUT https://registry.npmjs.org/@empresscli%2fcliwhile publishing — your npm account requires 2FA. Re-run withnpm publish --otp=<6-digit-code>.**empress: command not foundafter global install — your global npm bin directory is not onPATH. Runnpm bin -gto see where global binaries land and add that directory to your shellPATH. 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-defaultCheat 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 isskill://theme-brief/<site>. A pulled theme carries a shortAGENTS.mdthat points at both.
Development
pnpm install # also runs `pnpm prepare` → builds dist/
pnpm dev # tsup watcher
pnpm typecheck
pnpm lint
pnpm testThe 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).
