Install commission

You will be able to get a working commission command on your machine today, know exactly which of the four distribution paths exist yet and which do not, and verify the install with one command that tells you the truth rather than a version string.

No release has been published

Read this before you copy anything.

The repository has carried the placeholder version 0.1.0 since its first commit and no tag has ever been cut. The ## Unreleased section of CHANGELOG.md CHANGELOG.md is therefore the entire history to date; it closes as 1.0.0-rc.1 when the release candidate is cut, following the release checklist.

The practical consequence: of the four ways Commission will be delivered, exactly one works right now, and it is building from source. The other three are written up below so you can see how Commission will arrive, and every one of them is marked as not yet publishing artifacts. None of those commands resolves today, and a page that pretended otherwise would waste your afternoon.

Build from source — the path that works

Requires Bun 1.1 or newer, and access to the repository, which is private while the open- versus closed-source decision is still open.

git clone https://github.com/Row-Labs/commission.git
cd commission
bun install
bun link

bun link puts commission on your PATH from the bin entry in package.json. Nothing is compiled and nothing is installed globally beyond that symlink, so git pull && bun install is the whole upgrade procedure.

To produce a standalone binary instead — no Bun on the target machine, one file to copy:

bun run build

That writes dist/commission. It is the same code the release workflow will eventually publish; building it yourself is not a downgrade.

Verify the install

commission --version
commission doctor

commission --version prints the semver the binary reports on every surface — the CLI, GET /v1/version, the MCP server, and package.json are checked against each other by tests/version.test.ts, so the number cannot disagree with itself. Until a release is cut it will say 0.1.0.

commission doctor is the real check. It opens the database, runs the migration guard, validates any .commission.json it can find, and reports on the dependency graph, claims, bindings, and the search index. It exits 0 when everything it looked at is fine and 2 when something needs your attention — a refusal, in commission’s own vocabulary, with the fixing command attached. See exit codes.

The licence

Commission is licensed from the first command. A licence is a signed statement the machine verifies by itself — no network call, ever — so an air-gapped box, a container with no egress, or a laptop on a plane runs the entire product.

commission login stores it in the OS keyring. A file would be readable by every process running as you, which on a machine with agents on it means every agent — including ones you never meant to hand a credential to.

Four sources, in this order:

COMMISSION_STRICT_AUTH=1 stops after (2), so a CI job cannot silently inherit a developer’s stored credential.

A failing helper is a refusal, never a fall-through to the next source — falling back would leave a machine quietly running on a credential the operator believed they had replaced.

Keyring visibility follows HOME, because the platform keeps keychains under the user’s home directory. A process running with a different one — sudo, some CI images — will not see an entry written by the logged-in user; it falls through to the file, and then to a refusal naming COMMISSION_LICENCE, which is the right answer in those environments.

What an agent sees when there is no licence

A refusal, never a prompt. An agent cannot sign up, accept terms, or reason about a quota, and blocking on input nobody will type is a hang rather than a gate:

Commission is licensed, and this machine is not
  missing: no licence on this machine
hint: a person installs a licence on this machine — set COMMISSION_LICENCE to
      the licence token, or write it to ~/.commission/licence. An agent cannot
      do this part.

Exit code 2, like every other refusal. The hint names the human’s command and says outright that the agent is not the one who can act on it — otherwise an agent reads a refusal as a task and goes looking for a way to authenticate itself.

When it lapses

commission licence warns for the last thirty days, on stderr, so a renewal is never a surprise on a Monday morning. A lapsed licence stops the software; it never touches your data. Export stays unconditional — commission dump works on a lapsed licence, because a licence governs use of the program and never access to what you recorded with it.

Where the database lives

Commission is a binary and a SQLite file. There is no server to run and nothing to host. It is licensed: a person signs in once per machine, and every agent on that machine inherits it.

Point COMMISSION_DB at a scratch file whenever you want to try something without touching your real work:

COMMISSION_DB=/tmp/scratch.db commission init sandbox
COMMISSION_DB=/tmp/scratch.db commission board

Both commands read the same override, so the sandbox and your real database never see each other.

The four paths, when RC1 is cut

All four verify a SHA-256 checksum before installing anything, and all four fetch from commission.sh rather than from GitHub. That is not a preference: the repository is private, so release assets are 404 for anyone without access to it — including every customer.

Distributing the binary openly gives nothing away. It does not run without a licence, which is checked on the machine at runtime. That is what the licence gate is for, and it is why installation can be this ordinary.

The install script picks a directory already on your PATH and already writable, so it needs no sudo; set COMMISSION_BIN_DIR to override it, or COMMISSION_VERSION to pin a release. Running it twice replaces the binary and tells you what changed, rather than failing.

Set your actor name

Every claim, note, transition, and approval is attributed. Commission reads the actor from COMMISSION_ACTOR:

export COMMISSION_ACTOR=blaze

Agents get their own names — claude:api, claude:docs — and that is what makes parallel work legible afterwards.

Setting COMMISSION_ACTOR names you, but it does not tell commission you are a person. Nothing can: a process can set an environment variable as easily as you can, and Commission will not guess, because an actor wrongly taken for a human could approve its own work. So declare yourself once, in the repo:

commission actors add blaze --human

That writes you into .commission.json as an owner and approver. Without it, commission approve, commission verify, and commission answer all refuse — correctly, but it is the kind of correct that reads like a bug when it happens to you. Commission says so at commission init for the same reason.

Declaring actors is also what turns “who may approve this” into a checkable fact rather than a convention; see Guides → execution policies.

Next

• Your first task — a project, a graph, a claim, a refusal, a close.
• Your first agent — hand the loop to a coding agent.
• Reference → config — every .commission.json key.

Part of Start here.