> Source: https://vitna.ai/docs/cli/access
> Raw Markdown: https://vitna.ai/docs/cli/access.md
> Corpus index: https://vitna.ai/llms.txt

# Access commands

Which orgs exist, who may read them at `/console`, and how a session is opened
or revoked.

```bash
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.

```bash
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

```bash
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.
