[dir] defaults to . on every platform verb, so run them from the
project root and omit it.
Every write verb takes --origin. It records who authored the change
(person vs agent) on the op-log entry, not which wire carried it. Resolution
order: --origin → MAXSTACK_ORIGIN → agent-environment detection
(CLAUDECODE, CLAUDE_CODE_ENTRYPOINT) → human.
--accept skips the review queue. Without it a spec change lands as a
suggestion awaiting accept/reject in /workbench; with it the row lands
already accepted.
--gen regenerates after landing. Spec-ops change the spec; code appears
when the tree is regenerated (a running maxstack dev does it for you).
Exit codes are binary: 0 on success, 1 with a ✖ <message> line on
stderr for any failure. There are no other codes to branch on.
start is the one-command entry: a description in, a populated app serving on localhost out. init is the same scaffold without the starting spec, the sample rows, or the server. After that it is the everyday loop: regenerate, serve, and check.
Run the platform web app over the project data dir
shell
maxstack dev [options] [dir]
Argument
Required
Default
Meaning
dir
no
.
project directory
Option
Meaning
Default
--owned
force the owned-code dev server (auto-selected when owned modules exist): vendors + installs the runtime source once, then runs its dev server (needs pnpm)
—
--port <port>
port to serve on (default: PORT env, then 3000)
—
--preflight-json
emit the preflight diagnostics as JSON (for agents) instead of the human report
Every one of these lands a typed spec-op. op takes the raw JSON; the rest are terminal-native sugar that compile to exactly the same thing, so anything you can do here you can also do over MCP.
Add a data entity — sugar that compiles to a data.addEntity op
shell
maxstack add-entity [options] <slug> [dir]
Argument
Required
Default
Meaning
slug
yes
—
entity id slug (lowercase, e.g. task -> e-task)
dir
no
.
project directory
Option
Meaning
Default
--field <spec>
a field as name:type[!] (repeatable): title:text!, done:bool, 'priority:enum(low,high)', author:ref:e-user — quote any spec with ( or -> , they are shell syntax
—
--name <name>
display name (default: title-cased slug)
—
--with-page
also land a default list page for the entity in one shot
—
--route <route>
route for --with-page (default: /)
—
--page-id <id>
page id for --with-page (default: pg-)
—
--page-name <name>
page display name for --with-page (default: the entity name)
—
--accept
auto-accept the change (clear the review queue)
—
--gen
regenerate the app tree after landing
—
--origin <who>
who authored this change: ai | human (default: detected, see MAXSTACK_ORIGIN)
—
--agent <name>
which agent authored it, for the audit trail (default: detected, see MAXSTACK_AGENT)
The lower rungs of the change ladder — see ownership.md for what the manifest guarantees. slots comes before eject: it lists every region you can take over without owning a whole file, so bespoke UI costs one component instead of a surface (see block-slots.md). gen --upgrade regenerates against the current framework generators. drift is the other half of the eject bargain: it reports what you own, what it was derived from, and how far it has fallen behind — and never writes anything (see upgrade-safety.md).
The review loop and its cost, in the terminal rather than only in the workbench. review is the entry point: what needs you, in order, worst first — public exposure that would change, then anything that would stop existing, then proposals that cannot be batched, then drift, then the routine majority as one line. Its --section exposure answers "what of mine is on the internet", and --section blast-radius answers "what does accepting this actually do to the built app" — which tables, routes, forms and REST payloads move (see workbench.md). review prints the queue with a conservative risk classification and clears the safe groups in one action — it will not batch anything touching access, public exposure or a file you own, at any size (see bulk-review.md). review-cost is the human half of the north-star metric: how much attention approving a change actually takes, separated from wall-clock time and reported per proposal rather than per decision (see workbench.md). Opt-in — it is telemetry about your own reviewing, so it measures nothing until you ask it to. regen-cost is the platform half of the same question: how many files a regeneration redraws per op that landed, over time, so a project getting harder to change shows up as a number climbing. It is a proxy and says so — it is deliberately not the platform’s own weightPerSafeChange, which needs a replay of attempted changes that no project records.
What needs you, in order — worst first, with the reason why, plus bulk accept/reject and undo
shell
maxstack review [options] [dir]
Argument
Required
Default
Meaning
dir
no
.
project directory
Option
Meaning
Default
--json
emit the queue + risk assessments as JSON
—
--accept <selector>
accept a group ("field:e-order") or one proposal ("fld-total"), comma-separated
—
--reject <selector>
reject, same selector grammar as --accept
—
--undo <batchId>
return every row that batch settled to undecided
—
--origin <who>
who authored this change: ai | human (default: detected, see MAXSTACK_ORIGIN)
—
--agent <name>
which agent authored it, for the audit trail (default: detected, see MAXSTACK_AGENT)
—
--section <name>
"exposure" (what is publicly reachable, and what is one op away) or "blast-radius" (what accepting everything pending does to the built app); omit for the ordered what-needs-you list