Access commands
Which orgs exist, who may read them at /console, and how a session is opened or revoked.
npm run org:create -- --id <slug> --name "<name>"
npm run org:agree -- --org <id> --note "<invoice or agreement reference>"
npm run org:member:add -- --org <id> --github <login> [--role member]
npm run org:member:remove -- --org <id> --github <login>
npm run auth:session:create -- --github <login> [--github-id <n>]An org that arrived by agreement is created, not opened
Two doors make an org. /console/signup opens one for the account that submits the form, records that account as its opener, and the register meters it against its plan's allowance. org:create is the other: an operator at the prompt, as the migrate role, creating an org somebody agreed terms for.
npm run org:create -- --id acme --name "Acme Ltd"It leaves aperture.org.opened_by_user_id null and has no flag that could set it, and that null is what makes the org unmetered: the register refuses it no workload, the sixth or the fifty-first, so the number it may hold is the agreement's and nothing in the code enforces it. There is no plan id and no subscription row, because an agreement is not a subscription.
/console/billing shows such an org as on agreement terms: no plan, no allowance count and no checkout, and a sentence saying the register does not meter it. /console/checkout refuses a checkout for it.
It writes the org and nothing else. The first owner has to sign in once before a membership can be keyed on their account, so the command prints the org:member:add line to run when they have, with only the login to fill in.
An id that already exists is refused (exit 3) and nothing is written, including the name, which org:create never changes. The refusal says which door made the org: an operator's needs only a member added, and a self-service org cannot be put on agreement terms by creating it again, so its refusal names org:agree. A malformed or reserved id is refused before the database is asked (exit 2), by the same rules the signup form uses.
A self-service org that signs an agreement is moved, not re-created
npm run org:agree -- --org acme --note "Invoice INV-2026-014"org:agree records two facts on an org that was opened at /console/signup: when it moved onto agreement terms (aperture.org.agreement_recorded_at, the database's clock) and the invoice or agreement reference (agreement_note). It runs as the migrate role, and no web role can write either column. The org keeps its opener, so its account still cannot open a second org.
The register meters an org only where it has an opener and no recorded agreement, so from that instant the org is unmetered in both directions: the register no longer refuses the workload its plan would have, and it will not refuse the fifty-first either. The report prints what changed, column by column, and says so. /console/billing then shows the org on agreement terms since that date, with the note.
It cancels nothing at the processor. If the org still holds a plan, the report names it, and the billing page keeps its owner's button to the processor's own page so it can be cancelled.
Exit 2 is flags refused before the database is asked: a missing --org or --note, a malformed id, or a note over 200 characters or carrying a control character. Exit 3 is an org the record refuses, with nothing written: one that does not exist, one an operator created (already on agreement terms), or one already moved, whose date and note stay as they were. There is no flag to backdate the date or amend the note.
Signing in is not being allowed in
/console is behind GitHub OAuth, and authentication only establishes who someone is. An account with no membership sees a page saying so, and the data of no org.
A membership is keyed on the account id
org:member:add refuses a login that has never signed in.
GitHub logins are renameable and reusable. Keying a grant on a name would mean a renamed account keeps access it was not given, and a freed name inherits access somebody else had. So the account must have signed in once, which is what gives Vitna the immutable id to key the membership on.
Removal applies on the next page load
org:member:remove takes the access away and leaves the session alone. The session stays valid; it now belongs to somebody who is a member of nothing.
Revoking the session too is a separate act, which is the right shape: losing access to one org is not the same as being signed out everywhere.
Sessions from the box
auth:session:create opens a session and prints its token once, for operating and for checking the console without a browser.
It runs as the migrate role, so it grants nothing that shell access on the box does not already grant. That is the test for whether an operator command is safe to exist.
