The command line of apps built from the cella template: a testbed and the tools that run on it (load tests, an accessibility audit, a security scan, the marketing screenshots), the style check, and upgrades from upstream cella that keep your customizations.
From the app's root, run pnpm cella for a menu of commands, or name one:
pnpm testbed
pnpm cella bench
pnpm cella a11y
pnpm cella analyze
pnpm cella upgrade
pnpm cella auditThe CLI runs on macOS and Linux with Node 26 or later, and calls git and pnpm from the PATH. Every command needs a
git repository except audit, which runs in any folder. The upstream commands, style and i18n unused read
cella/cella.config.ts; the other commands run without it.
pnpm cella <command> --help lists a command's jobs and options.
| Group | Command | What it does |
|---|---|---|
| Develop | testbed |
A throwaway copy of the app on its own seeded database and ports, beside pnpm dev |
bench |
Load-test the running app and check what the stack did with the load | |
a11y |
Audit the app against WCAG 2.2 AA on a testbed and keep the conformance ledger | |
shoot |
Shoot the marketing screenshots on a testbed | |
i18n |
Translation status, unused keys and renames across the locale files and the code | |
stats |
Count files by kind, in the repository or in what a branch changed | |
| Security | audit |
Outdated packages, runtime pins and the security overrides a fresh audit asks for; audit fix updates them |
pentest |
Scan a throwaway testbed: a cross-tenant access probe, then Nuclei and ZAP | |
| Upstream | analyze |
A dry run of the next upgrade |
upgrade |
Merge upstream onto a fresh branch and open a squash-merge PR | |
align |
The upstream alignments this app has not handled yet: list, read, run their codemods, record them | |
adopt |
Pull and adopt changes from local forks | |
| Gate | style |
The style check: terminology, docs, comments and frontend code |
The menu leaves out testbed, which pnpm testbed runs, and style, which scripts and CI run. It shows adopt only
when cella.config.ts lists forks.
Across 1.x releases these stay as they are, and a change to one waits for 2.0:
- the command names and what each does, and their flags
- the keys of
cella/cella.config.tsand of the adapter files incella/ - the package's subpaths (
config,bench,style,drive,a11y,screenshots,pentest) and the names they export - the
--jsonpayloads - the exit codes
- the files the upgrade keeps in the app,
cella/cella.manifest.jsonandcella/cella.alignments.json, and the refrefs/cella/last-upgrade
Every command exits 0 when its run is done or a plain rerun advances it, 1 when a check failed or a person must act before it can go on, and 2 on a usage or runtime error. A run stopped by ctrl-c exits 130, and one stopped by SIGTERM 143, after its cleanup ran.
Until 1.0 two older shapes still load, each with a warning that says what to move: a cella.config.ts in the 0.7 shape,
with settings and overrides blocks, and the style exceptions in shared/config/vocabulary-allowlist.ts.
pnpm testbed starts a copy of the app on a database of its own and on ports beside the ones pnpm dev uses: the
backend, the workers, the relay and a built frontend. A new database is seeded once and kept, and every start migrates
it: a branch with migrations works too. The testbed holds until ctrl-c, which stops its servers and its database
container.
pnpm testbed -- <command> runs a command against a testbed: the one this checkout holds, or one started for the
command and stopped after. The command gets the testbed's ports (DEV_PORT_OFFSET) and database URLs in its
environment. pnpm testbed stop stops a testbed, or the servers one left behind after a crash.
One testbed runs per app on a machine, since every checkout of the app shares its database: a second start, from another
worktree too, says which checkout holds it. A start that fails prints the end of the servers' log, testbed.log in
.git/cella-testbed/. The testbed needs Docker and a db_testbed service in the app's backend/compose.yaml.
The database holds either the app's seed or its showcase, the curated backend/scripts/seeds/showcase.json that the
screenshots shoot. A start that asks for the other one seeds a new database, and so does every showcase start, since the
showcase's times are relative to its seed. A running testbed serves only commands that want what it holds.
A tool's engine ships in this package, and what is app-specific sits in the app's cella/ folder as adapters: a base
cella/<tool>.ts that each upgrade brings from the template, and an optional cella/<tool>.app.ts that no upgrade
touches. The app file holds only the app's delta: its lists join the base's, remove drops base entries, and an entry
with a base id replaces that entry. Without it the base runs alone.
Each file default-exports its tool's define helper, such as defineA11yBase or defineA11yApp from
@cellajs/cli/a11y, which types it. Both are checked at load: an adapter that does not fit the installed CLI fails in
seconds, naming the key. Adapters import the app's SDK and run under the app's own tsx.
The tools that open the app's pages, a11y and shoot, sign in as a seeded user with a minted session and sign it out
when they end, on ctrl-c too. Both of their adapter files may set prepare (steps before the first page),
placeholders (the value of each {name} in a path, read as the signed-in user) and suppress (alerts and hints
marked seen before the first page).
Heavy runtimes come from the app: Playwright from frontend, with its Chromium installed once through
pnpm --filter frontend exec playwright install chromium. Results stay in the git directory, out of git status:
.git/cella-<tool>/ in the main checkout and the worktree's own in a linked one.
pnpm cella bench load-tests the app with the scenarios in backend/bench/scenarios/. New virtual users arrive on
schedule whether or not earlier ones are done, a live line shows what the last interval did, and the summary ends in
checks: the responses the stack rejected, failed users, latency thresholds, the scenario's own counters, and the app's
checks of what the stack recorded. A passing full run is saved as the scenario's baseline, and the next run at the
same emulated round trip (--rtt) compares with it.
A run measures the stack this checkout runs with pnpm dev, or a testbed with --isolated, and one run at
a time holds it. Baselines, logs and locks live in cella-bench/ in the git directory every worktree shares.
The app's side is backend/bench/run.ts, run with the backend's tsx so it imports backend modules: it calls
runBench from @cellajs/cli/bench with the app's preflight, seed and checks around each scenario. A scenario is a
module that default-exports defineScenario({...}) from the same import; counter and histogram names are typed, so a
misspelled one fails the typecheck.
pnpm cella a11y audits the app against WCAG 2.2 Level A and AA and fills the conformance ledger,
cella/a11y-ledger.json. On a testbed, signed in as the seeded admin (ADMIN_EMAIL of .env), it visits every state
of cella/a11y.ts in light mode for every check and in dark mode for contrast: an axe scan, browser checks that axe
cannot do, and a review of the code for the rest.
Only a complete run replaces the ledger. A run of some states (--states), or one with a failed visit (a page that
redirects, a check that cannot run), writes ledger-partial.json in the results folder, and a failed visit fails the
run. It leaves a screenshot and a JSON file under review/: what the page showed, its console errors and the steps that
ran before.
The ledger. One row per criterion, committed, with its status, the remarks for the report, the evidence and the checks still open. It carries the product's name (the root package name), and another product never reads it: a new app starts its own with its first full run. Raw findings for fixing, the draft VPAT and the checklist stay in the results folder.
How a row is decided. Each criterion names its checks: axe, a browser probe, a code check or a manual one. Any failure makes the row Partially Supports. A row becomes Supports or Not Applicable only when all its checks ran and none of them is manual; everything else stays open until a reviewer decides it.
Reviewers. Every full run leaves a packet per state under review/: a screenshot, the accessibility tree, facts
about the page and the Tab order. A reviewer judges the open criteria from those and records each decision with
a11y decide; an agent's decision stays provisional until a person confirms it. A later failure on a row a reviewer
called Supports puts it back to Partially Supports, and the checklist lists decided rows whose evidence names a file
changed since.
The report. a11y report renders the ledger as a draft VPAT and the checklist for the manual pass. With --publish
it puts the report where the app serves it and prints what the statement needs; it refuses while rows are open or
decided by an agent only, unless --draft publishes them as provisional. The cella template's a11y-review skill is
the procedure around this loop.
The states. cella/a11y.ts lists the template's pages and states, following steps 2 and 3 of W3C's WCAG-EM: every
page type, plus overlays such as dialogs, sheets and menus. A state that exists only at one width carries its own
browser settings, and forms marks the states whose form the form probes submit. cella/a11y.app.ts adds the app's
own.
A short script can open one state, signed in, to check a fix: openState('<id>') from @cellajs/cli/a11y returns its
page, its context and close. Run the script from the app's root through pnpm testbed -- node <script>.
pnpm cella shoot shoots the app's marketing screenshots on a testbed, a light and a dark file each, over the files the
app ships, and prints each file's pixel and byte size. Ids pick some shots (pnpm cella shoot settings), and
--out <dir> writes a trial run elsewhere.
An app with a backend/scripts/seeds/showcase.json is shot on a testbed that holds the showcase, as its admin; without
one the testbed holds the app's seed. A page that shows an earlier shot's file, such as a composition of screenshots,
gets the copy this run wrote.
A shot with a mode is written in that mode alone and without the -dark suffix, for a file the app serves in one
mode, such as its link preview image. A shot's format overrides the list's: WebP is written lossless by the system
cwebp encoder, which the run checks before the testbed starts, and JPEG by the browser.
cella/screenshots.ts lists the template's shots and devices, and cella/screenshots.app.ts the app's own. The cella
template's screenshots skill is the rubric for judging them.
@cellajs/cli/drive is the browser layer the tools share, for an app's own scripts and skill drivers.
loadPlaywright() loads the app's frontend copy of Playwright. mintSession(email) signs in any seeded user through
the backend's mint script and returns a Session: the app's URLs, the cookie a browser context adds and the header a
request sends. signOut(session) ends it. A script run through pnpm testbed -- node <script> mints its sessions on
the testbed's database and gets its URLs.
pnpm cella i18n reads shared/locales/<language>/<file>.json the way the app loads them: namespaces.json there
names the runtime namespaces that merge several files (c is common.json with app.json over it), and every other
file is a namespace of its own. English holds every key, and each other language is measured against it.
pnpm cella i18nreports per namespace and language: missing keys, keys English lacks, translations equal to English, interpolations and tags that differ from English, plural forms a language lacks or never uses, and the keys a later file of a namespace overrides. It exits 1 on a key English lacks or a mismatch; a missing translation falls back to English and only counts.pnpm cella i18n unusedlists the keys no code names, in this app and in theforksofcella.config.tsthat exist on this machine. A template key that only an app uses stays.pnpm cella i18n rename <ns:old> <ns:new>renames a key and its plural forms in every language and every'ns:old'literal in the code, then sorts the changed locale files with the app's own Biome. A key moves to another namespace too, unless that namespace merges several files.
A key built from a value whose type is a union of literals, such as t(`c:${role}`), counts as a use of each key it
can build. A template whose values are open, such as an index, is reported by its pattern (about:why.title_*) as
unverified, and the keys it may build are never listed as unused. A rename lists those templates and every key passed to
t() without its namespace, which no literal rewrite reaches.
pnpm cella pentest is a security check to run before a release, against a copy of your own app on this machine and
nothing else. It starts a testbed on a new database, signs in as seeded users, runs three checks and removes the
database after, since the scans write rows and run into the rate limits. It refuses to start while a testbed runs.
| Check | What it does |
|---|---|
probe |
Calls every read route scoped to a tenant, an organization or a user with the ids of an organization, once as its admin and once as an outsider with no membership in its tenant. Any answer to the outsider other than 403 or 404 is a finding |
nuclei |
Nuclei's templates for misconfigurations and exposures against the testbed's origin, signed in |
zap |
ZAP's API scan from the app's OpenAPI spec: passive rules, then a capped active scan, signed in |
A run fails on a finding of high or critical severity, and every read the probe lets through to the outsider is one. A
scanner that failed or timed out fails it too. pnpm cella pentest report prints the last run's findings.
The scanners run as Docker images pinned by digest, on the host network, where they reach the testbed by its own origin.
Results stay in .git/cella-pentest/, out of the repository, because the scanners' output can hold the sessions, which
the run signs out at the end.
cella/pentest.ts describes the app: the query that picks the seeded users, the operations a scan must skip because
they end its session or delete what it needs, the guards that mark a route as scoped, and what fills each route's ids.
cella/pentest.app.ts adds the app's own skips, guards and ids, and its remove drops base entries the app does not
have. A route whose ids nothing fills is listed as not probed: the report says what the probe did not reach.
pnpm cella style is the style check an app runs as a gate: pnpm lint:fix and pnpm check call it, and CI runs it on
every PR. It reads every file git lists, untracked ones it does not ignore included, prints each finding to stdout as
file:line:column [rule] "term": message and exits 1 on any. Paths limit the files the in-file rules read:
pnpm cella style frontend/src. It compiles classes with the frontend's own Tailwind.
An app lists its exceptions in shared/config/style-exceptions.ts. They join the exceptions of the template's own code,
and an id that names no rule fails the run:
import type { StyleExceptions } from '@cellajs/cli/style';
export const styleExceptions: StyleExceptions = {
// The files and folders each rule skips, by rule id
exempt: { 'long-paragraph': ['docs/reference/'] },
// Class names kept as hooks with no Tailwind utility or stylesheet rule behind them
markerClasses: ['is-dragging'],
};Two rules read only what the template has. alignment checks the shape of every folder in cella/alignments/, which
cella align reads and an app never has. In a repository with cella/alignments/_TEMPLATE.md and no upgrade manifest,
owed-alignment asks a branch that changes an app-owned path template code reads from for an alignment, or for an
Alignment: none, <reason> line in a commit message.
| Rule | Fails on | Where |
|---|---|---|
em-dash |
an em dash | source and config files, strings, JSON values and .env* files included; Markdown and MDX prose |
contrast-phrase |
instead, rather than, as opposed to |
comments |
change-history |
previously, formerly, used to, originally |
comments |
review-conversation |
maybe, perhaps, we should, we could, we might, was considered |
comments |
concrete-language |
invariant |
comments, Markdown and MDX prose |
load-bearing, authoritative |
the word the rule is named after | comments, Markdown and MDX prose, outside infra/ and cella/alignments/ |
detached-long-comment |
a comment of more than three prose lines outside a statement and not directly above a declaration; a licence header passes | source and config files |
code-in-link |
inline code in a link label | Markdown and MDX |
long-paragraph |
a prose paragraph of more than 80 words, inline code and link targets uncounted | Markdown and MDX, outside cella/alignments/ and cella/skills/ |
consequence-tail |
, so joining a reason and its consequence |
comments, Markdown and MDX prose, on the lines the branch changed since its merge base with origin/main, in an app outside the lines upstream's copy of the file holds; alignments and migration notes exempt |
source-control-term |
the CLI's source-control term | file paths and text, outside the fork: markers and the exempt files |
product-name |
cella_*, Cella*, _cella-*, cellajs.com |
backend/src, shared/src and frontend/src, outside tests, marketing and content |
component-declaration |
a component declared as an arrow function, or a helper such as memo wrapping an unnamed render function |
frontend .tsx sources |
store-selector |
a zustand store called without a selector | frontend sources |
route-context-selector |
useRouteContext() without select |
frontend sources |
button-press-cancel |
active:translate-y-0 on a Button, which leaves the press nudge in place |
frontend sources |
form-no-validate |
a form react-hook-form validates without noValidate |
frontend sources |
reorder-grip |
a lucide grip icon in a file that imports no ReorderHandle or reorderColumn |
frontend sources outside drag previews and the editor's side menu |
memo-dependency-unread |
a useMemo or useCallback dependency its callback never reads |
frontend sources |
product-cache-write |
a query-cache call that clears the refetch mark where synced product rows live; the keepers in ~/query/basic/cache-mutations replace it |
frontend/src/query/, product modules and range-fetch registrars |
tailwind-class |
a class that compiles to no CSS and that nothing selects, a variant on a plain CSS class, a stylesheet Tailwind cannot load | frontend/src scripts outside tests, and the Tailwind entry stylesheet |
text-color |
a text token with an opacity modifier outside disabled:, a palette gray |
frontend sources; palette grays pass in the syntax colors the template exempts |
token-contrast |
a token pair below its WCAG ratio, a theme without --background or --edge-raised |
frontend/src/styling/tailwind.css |
stamp-clock |
new Date().toISOString() |
backend/src, outside tests, mock builders and the two stamp helpers |
stamp-pair |
an object that writes updatedAt with updatedBy, or deletedAt with deletedBy, from a moment written by hand |
backend/src, outside tests, mock builders and the two stamp helpers |
alignment |
an alignment folder off its shape | cella/alignments/ |
owed-alignment |
a change to an ignored or pinned path template code reads from, on a branch with no alignment or waiver |
the template: the files its branch changed since origin/main, outside Markdown |
path-argument |
a path argument that matches no file | the paths pnpm cella style takes |
A checkout without a merge base with origin/main cannot tell which lines a branch changed: the gate then names the
checks it skipped on stderr.
@cellajs/cli/style also exports the helpers the template's skill scripts read class strings with.
Upgrade behavior lives in cella/cella.config.ts, which a new app gets from the template and no upgrade merges. Every
key sits at the top level, and your editor shows what each one does:
import { defineConfig } from '@cellajs/cli/config';
export default defineConfig({
upstreamUrl: 'https://github.com/cellajs/cella.git',
trunk: 'main', // your main branch: upgrade branches are cut from it and their PRs go into it
packageJsonKeys: ['dependencies', 'devDependencies', 'scripts'],
ignored: ['README.md', 'shared/config'],
pinned: ['backend/src/modules.ts'],
});To deviate files or folders from the template:
ignored: files excluded from upgrades, existing and new. An entry may name a path your app does not have, to keep it from arriving.pinned: files your app controls whole; existing, modified and deleted files are kept as the app has them.
Every run warns about an entry that does nothing: an ignored path neither your app nor upstream has, and a pinned
entry inside an ignored path, one upstream does not have (the file is your app's own), or one identical to upstream,
which only drops upstream's next change to it.
upstreamTrack sets how the CLI follows upstream cella. release, the default for most apps, upgrades to the latest
cella release tag, and each bump maps to a changelog. branch follows the tip of upstreamBranch, for cella
maintainers and active development.
--track overrides the mode for one run, and --ref pins one upstream point: a commit sha, a release tag or an
upstream branch name, resolved on the upstream remote (main is upstream's main). The ref must be on upstreamBranch
or in an upstream release; a release tag upgrades as that release, anything else is recorded like branch tracking.
pnpm cella upgrade --track branch
pnpm cella upgrade --ref 4f7d87cA run never upgrades to a point behind the last upgrade. When an earlier --ref or --track branch run went past the
latest release, release tracking says nothing to upgrade until a newer release exists, and a --ref behind the last
upgrade is refused. Either way the run changes nothing and leaves you on the branch you started from.
pnpm cella upgrade never commits to the trunk directly:
main ──▶ cella/upgrade/<stamp> ──(3-way merge)──▶ PR ──(squash)──▶ main
It runs a real git three-way merge, in stages: each run advances the upgrade one stage, and the run that commits never
ships. The pause on the committed branch is where drift triage (pnpm cella analyze reads the committed HEAD) and
follow-up commits happen.
- The first run cuts the branch and merges. A clean merge is committed right away, after
pnpm installandpnpm checkreconcile the dependencies, and the run stops on the branch. A conflicted merge stops before the commit: resolve it in your editor,git addthe files and rerun to commit. - The next run ships the committed branch: it pushes to
origin, opens a PR into the trunk withgh, titled like the upgrade commit, and switches you back to the trunk.
Before it merges, the first run prints upstream's range and checks that it can go ahead. It stops without changing
anything when upstream needs a newer @cellajs/cli than the one running, or changed its own CLI config in ways yours
does not follow (see Upstream changes that never merge): the temporary branch is
removed and you are back where you started. After the merge it prints the package.json merge, then the merge summary and
next steps.
The upgrade commit has a single parent (chore: upgrade cella to <sha>): the PR holds the incremental diff alone. Let
the rerun commit: a manual git commit records a merge commit, whose PR lists upstream's whole history. Ancestry lives
in the committed cella/cella.manifest.json and the local refs/cella/last-upgrade. Each upgrade branch is safe to
delete once its PR merges.
upgrade also runs from a linked git worktree while another worktree has the trunk checked out: it never switches to
the trunk, cuts from origin/<trunk> when the local trunk is behind, and detaches at the trunk after shipping. When
HEAD builds on that start point, as a branch holding a CLI bump or an alignment's renames does, the upgrade branch is
cut from HEAD and those commits ride in the upgrade PR.
A rerun with conflicts left lists them and stops. When pnpm check, the push or gh fails, the run reports it and
prints the steps left to do by hand.
pnpm cella analyze leaves your files and branches alone: it fetches upstream and records the upgrade point in git
(refs/cella/last-upgrade and a local graft). It prints its file sections in the order they need you: what merges on
its own first (behind, diverged), then pinned files, drifted files, and the upstream changes the upgrade leaves out.
Large groups collapse into a row per folder or kind, and --all lists every path.
Analyze and upgrade both end with next steps, numbered in the order you take them: the review page, the command to run
next, and the alignments the upgrade brings or that are still open.
next steps
────────────────────────────────────────────────────────────
1 review file:///Users/you/app/.git/cella-diff/analyze-review.html
22 diffs in 3 sections · 42 listed without a diff
2 upgrade pnpm cella upgrade
commits on a fresh branch, a rerun opens the PR · 36 update, 2 merge
3 align 1 alignment arrives with this upgrade
○ Migration notes become alignments · manual · not breaking
after the upgrade: pnpm cella align
Without a terminal (piped, or read by an agent) each alignment row also gets its id, for pnpm cella align show <id>.
Upstream ships an alignment for every change that app code has to follow, in cella/alignments/<id>/: a README
(frontmatter, title, summary, then the steps) and sometimes a codemod. Alignments stay upstream. The upgrade never
brings that folder into the app and removes a copy it finds; align reads them from the upstream commit the app last
upgraded to.
The frontmatter says what the change asks of the app: breaking, clientCacheBump, caughtBy (compiler, tests or
nothing: what catches app code the change leaves behind), generate (the change needs pnpm generate), grep (terms
app code may still use) and, beside a codemod, its roots. A grep term that starts and ends with a letter or digit
matches as a whole word; any other term, such as .results, matches anywhere in a line.
The app keeps one small record, cella/cella.alignments.json, listing the alignments it has not handled yet. The
upgrade adds the ones that arrive with it, align mark removes them, and the file is deleted once the list is empty. No
file means nothing is pending, so a new app starts without one.
Alignments are information, never a gate. analyze and each upgrade run list them under next steps; in analyze the
ones in the upgrade range arrive with this upgrade and become open once the upgrade lands. The upgrade PR lists the
open alignments with links. Handle them in the upgrade PR or later; they stay listed until marked.
pnpm cella align # open alignments, with summary and links
pnpm cella align --all # every upstream alignment, handled or not
pnpm cella align show <id> # one alignment's README and what git tells about it
pnpm cella align run <id> # run its codemod, report only
pnpm cella align run <id> -- rewrite frontend/src # run it with your own arguments
pnpm cella align mark <id> [...] # record alignments as handledNext to its README, align show shows what git can tell: the upstream commit and PR that added the alignment, the other
alignments of that commit, the files of that commit the app pins, ignores or changed, and the lines of app code that
hold one of its grep terms. Only files that differ from the upstream commit of the last upgrade count.
align show also works before the upgrade that brings an alignment: it reads one the last upgrade does not have from
the fetched upstream branch.
align run extracts the alignment to node_modules/.cache/cella/alignments/<id>/ and runs its codemod with tsx from
your app root. Everything after -- goes to the codemod as given; without it the codemod gets inventory and the
alignment's roots, the report-only run.
A file identical to upstream is the way upstream wants it, and a rewrite there only creates drift. So after the codemod runs, each file that was byte-identical to the upstream commit of the last upgrade gets its upstream content back, and the run prints how many it restored. Files your app changed keep the codemod's rewrite. A codemod run by hand from the extracted folder has no such protection.
For each file, upgrade compares app and upstream content and resolves it per the table below. Unconfigured files
converge on upstream; ignored and pinned let you opt out:
| Scenario | ignored |
pinned |
Default |
|---|---|---|---|
| Content identical | ✅ Keep | ✅ Keep | ✅ Keep |
| Content differs | ⏭️ Skip | ✅ Keep yours | ⬇️ Take upstream |
| New upstream file | ⏭️ Skip | ✅ Keep (respect deletion) | ➕ Add file |
| Deleted in upstream | ✅ Keep | ✅ Keep | 🗑️ Delete |
| Only in your app | ✅ Keep | ✅ Keep | ✅ Keep |
Choosing an override: ignored means the file never merges and is fully hidden (app-specific docs, assets, config
you own). pinned means your version always wins but stays visible (files you customize). Run pnpm cella analyze
first to preview.
During analysis and upgrade, files are displayed with status indicators:
| Symbol | Label | Meaning | Action |
|---|---|---|---|
| ◇ | managed |
Package/config file changed | Handled separately by cella |
| ⨂ | ignored |
Protected by ignored config | Excluded from upgrades |
| ✓ | identical |
App matches upstream | No action needed |
| ↑ | ahead |
App changed (pinned), upstream did not | Protected, keeping app |
| ! | drifted |
App changed, not protected | At risk, consider pinning |
| ↓ | behind |
Upstream changed, app did not | Will update from upstream; a pinned file keeps the app copy (masking pin) |
| ⇅ | diverged |
Both sides changed | Will merge from upstream |
| ⨀ | pinned |
Pinned and both changed (a deletion counts), moved upstream from a protected path, or edited by the app and moved into one | Protected, keeping app: review, see below |
| → | renamed |
Upstream moved a file the app left unchanged from an unprotected path | Takes upstream's copy at the new path |
| ✗ | deleted |
App deleted it | Stays deleted |
| + | local |
Only in app, never in upstream | No action needed |
A pinned or ignored file wins whole-file: when upstream also changed it since the last upgrade, upstream's hunks are dropped, not merged. That is easy to miss, as with a pinned stylesheet missing new upstream utilities that merged components rely on. Both commands call it out:
analyzelists them in a⚠ protected but behind upstreamsection with the number of lines upstream changed, together with the ignored files only upstream changed. Generated output the app regenerates itself (sdk/gen,*.gen.*files) is left out.--listand--jsoninclude them in--scope alland--scope protected.upgradeprints the same list at the end of its summary, right when the drop happens.
⚠ 5 protected files kept the app version, dropping upstream changes:
⨀ frontend/src/styling/tailwind.css · 21 lines changed upstream
⨂ shared/config/default.ts · 4 lines changed upstream
⨂ shared/config/staging.ts · 2 lines changed upstream
⨂ 2 ignored binary files, such as frontend/public/static/marketing/app-1.webp
pinned/ignored files where upstream also changed since the last upgrade; the app side wins on conflict, so review what upstream changed and adopt what you need.
The check is relative to the last upgrade: a drop in an earlier upgrade shows as plain ahead afterwards. For that case
the ↑ protected in app section counts the upstream lines absent from each pinned file: upstream content the app
never received, deliberately or not. The review page shows both differences.
To pull upstream into every pinned file at once, run upgrade --unpinned: pins are lifted for that run (managed files
stay pinned) and the merge uses the full upstream history: changes earlier upgrades dropped come back too. Review the
staged merge in your editor and keep what you want; analyze --unpinned previews it.
Two more kinds of upstream change never reach the app on their own, and both commands report them:
- Ignored paths changed upstream. Upstream changed, added or deleted a file under an
ignoredentry (app-owned module folders included) that the app left untouched or does not have. No conflict marks it. This is where new config keys and version bumps undershared/configshow up. - Upstream CLI config changes. Entries upstream adds to its own
pinned,ignoredorpackageJsonKeysnever arrive, becausecella/cella.config.tsnever merges. The report names each entry upstream added that your config lacks (+), each entry upstream dropped that your config still has (−), and each entry of yours upstream renamed (~). It reads upstream's config without running it.
upgrade stops before a new merge when it finds such config entries. The merge runs on your config: with a list that is
behind, a path upstream now ignores or pins would arrive as an ordinary merged file. Add or drop the entries that fit
your app, commit and rerun, or pass --keep-config to merge with your config as it stands. A rename into a path your
config or an app-owned module already protects is no stop: drop the old entry. The rerun that commits an
already staged merge never stops for this.
The terminal lists files; the review page shows their diffs, side by side and highlighted, on one page in your browser
under the same section titles. analyze and upgrade write it whenever a list has files, and list it first under
next steps. A diff shows what upstream changed since the last upgrade, except in two sections only analyze has:
protected in app compares the app with upstream as both are now, and drifted shows what the app changed.
upgrade opens the page in your browser when it runs in a terminal: the files on it are upstream changes the merge did
not bring in, and the committed upgrade branch is where you adopt them. analyze only lists it. The page lives in the
git directory, out of git status, and each run overwrites it. A page with too many diffs lists the rest by path, as it
does files without a text diff.
packageJsonKeys names the package.json sections that merge from upstream, and false merges no package.json at all.
Each section merges three-way against the package.json of your last upgrade:
- An entry your app never touched follows upstream: it is added, updated or removed.
- An entry your app added or changed stays; only a strictly higher upstream version still bumps it, never in
scripts. - An entry your app removed is not re-added.
- A dependency or script upstream dropped stays while your own code still uses it, and the upgrade warns about each one it kept.
exportsare add-only and merge only when both sides are subpath maps ({ ".": …, "./config": … }).- A workspace upstream added since your last upgrade arrives with its package.json as upstream has it.
- A merged section is sorted alphabetically, except
scripts: they keep upstream's order, and a script only your app has stays after the one it follows.
type always merges, whatever packageJsonKeys lists: it follows upstream where your app kept the previous value, and
a package.json without type gets upstream's. Set it yourself (for example "commonjs") to keep your own.
pnpm cella audit reports the outdated packages, the runtime pins and the security plan, with no prompts, and writes
nothing. Outside a git repository it finds no Dockerfile, and only the image pins go unread. pnpm cella audit fix
works in two layers, in this order:
- Updates. It lists the outdated packages and runtime pins in one table and asks once which to update. Rows with a high or critical advisory start ticked; submitting with nothing ticked skips this layer.
- Security. It audits the workspace as the picked updates leave it and brings three settings in
pnpm-workspace.yamlin line with that audit.
Nothing is written until the end: the updates and the security settings land together, with a single pnpm install.
Cancelling any prompt leaves the workspace as it was.
The audit also checks the runtimes the workspace pins to an exact version, which pnpm audit never sees, against their
own release feeds:
| Pin | Feed | Dot |
|---|---|---|
root engines.node |
nodejs.org release index | red when a newer release in the line is a security release |
root packageManager (pnpm) |
npm registry and its advisory database | red when the newer version fixes an advisory on yours |
FROM image:2.8-suffix in tracked Dockerfiles |
Docker Hub tags | yellow when your tag has gone stale while a newer one is pushed |
A pin moves within its major, to the newest version older than minimumReleaseAge. A Node bump waits until Docker Hub
has the node:<version><suffix> images the Dockerfiles build from, and the audit prints what is left to do on your
machine: switching its Node, and building each changed image.
The pins say what the workspace should run; the tools on your machine can still miss security fixes. Below the table the audit shows, for each one, what it misses:
| Tool | Which one | Feed |
|---|---|---|
| Node | the one running the audit, which also runs the workspace | nodejs.org release index |
| pnpm | the one your terminal starts, before it switches to packageManager |
npm advisory database |
| gh | the one on your PATH | OSV |
A tool that misses a fix gets a dot and the command to fix it, for the way it was installed (Volta, Homebrew, or pnpm's
own self-update), naming the newest version that has every fix and is older than minimumReleaseAge. The audit does
not change these tools itself.
To keep a package off the update list, use pnpm's own setting, with the reason as a comment. pnpm outdated skips it,
so the audit does too, and pnpm audit still checks it:
updateConfig:
ignoreDependencies:
- typescript # 7 drops the JS compiler API that SDK codegen needsThe security layer treats its overrides as output, not as configuration. Every run it drops them, resolves the workspace without them in a temporary copy, and puts back only the ones a current advisory still needs. An override whose package now resolves to a fixed version is gone after the next run. The workspace changes once, at the end, and only when the outcome differs from what is there.
| Setting | What the audit owns | What it leaves alone |
|---|---|---|
overrides |
keys with a version selector: pkg@<1.2.3 |
keys without one (pkg) and parent-scoped keys (parent>pkg) |
minimumReleaseAgeExclude |
pkg@1.2.3 entries, removed once that version is older than minimumReleaseAge |
name-only entries |
auditConfig.ignoreGhsas |
every entry, removed when the advisory no longer applies or a fix arrives |
To keep an override whatever the audit finds, write it without a version selector. For each advisory the audit looks up the published versions itself; it does not trust the patched version an advisory claims. Most outcomes need no answer from you:
- A fix that fits. The audit writes an override. When the fix lies inside the range the parents ask for, the lockfile holds the fixed version on its own, and the following run drops the override.
- A breaking fix (another major, or another minor below 1.0), or a fix for a package you depend on directly: you choose between leaving it open, applying the override and ignoring the advisory. An override that was in place before the run is applied again without asking.
- A fix younger than
minimumReleaseAge: you choose between waiting and installing it now with an exclude. - No fix published: you are asked whether to ignore the advisory until one is.
Upstream can pull modifications from local forks and adopt them file by file. List your local forks in
cella.config.ts:
forks: [
{ name: 'raak', localPath: '../raak', pullBranch: 'main' },
],pnpm cella adopt asks for a fork, fetches its pullBranch and builds a clean local contrib/<fork> branch with only
that fork's contributed files. Press d on a file to open its diff in your browser. Accepted files are checked out from
the contrib branch and staged for review.
pnpm cella stats counts the whole repository. With --since <ref> it counts what the current branch changed since it
left that ref, by kind of file, which is what a pull request into the ref shows. Only committed work counts. It reads
git alone and runs in any repository: one that is no app runs the published CLI with pnpm dlx @cellajs/cli stats.
pnpm cella stats --since origin/main # tables in the terminal, -V lists every file
pnpm cella stats --since origin/main --md # a markdown table on stdout, for a PR description files added removed net
8 +438 -6 +432 tests
14 +229 -109 +120 source
1 +44 0 +44 docs
2 +11 -6 +5 json
25 +722 -121 +601 total
source lines by content
+152 -87 +65 code
+49 -9 +40 comments
+28 -13 +15 blank
| Kind | Files it holds |
|---|---|
| source | Code and styles that are none of the kinds below |
| tests | *.test.*, *.spec.* and anything under a tests/, test/ or __tests__/ folder |
| stories | *.stories.* |
| generated | *.gen.*, gen/ folders, drizzle/, *.d.ts and lock files |
| json | *.json and *.jsonc that are not generated: config and translations |
| docs | *.md and *.mdx |
| other | Everything else, such as workflows and Dockerfiles |
Source lines are also split by what they hold. A diff shows changed lines only. A comment is recognized by how the line
starts (//, /*, *, {/*), and a line of a template literal that starts that way counts as a comment too.
A change to a tool reaches apps with a CLI release. To try one on an app first, run pnpm build here and put this
checkout in place of the app's package:
rm -rf <app>/node_modules/@cellajs/cli && ln -s "$PWD" <app>/node_modules/@cellajs/cli. An install in the app puts the
published package back, so link again after every pnpm install.