Configuration reference — .commission.json

.commission.json is the canonical, git-committable configuration for a project. It lives at the repository root; every Commission command walks up from the working directory to find it, so agents never have to name the project.

JSON rather than YAML on purpose: commission’s whole agent-facing surface is already JSON — apply documents, --json output, the MCP contract — and the one file an agent writes should not be the odd shape out.

A minimal config is two keys:

{
  "version": 1,
  "project": "myapp"
}

Everything else is optional. Blocks you do not write behave as the defaults below, so a solo founder’s config stays two keys while an enterprise repo can declare actors, approval routing, workspace providers, and tracked context.

Rules

• Strict. Unknown keys are refused, never ignored — a typo that silently does nothing is the failure this file exists to prevent. Refusals name the path, list the allowed keys, and suggest the nearest declared key.
• Versioned. version is required. A file declaring a version this binary does not speak is refused with the upgrade command, never partially applied. A file with no version is the pre-versioned shape and is read as such: project, integrations, and notices only, with a notice.
• Deterministic. No inference beyond the precedence chain below.

Notices

A pre-versioned file still loads, and says so once per process on stderr, naming the command that ends it:

warning: .commission.json predates config versioning — add "version": 1 to use the full configuration surface
  fix: commission config migrate --write

It is never printed under --json: stderr is part of a machine’s stream, so a pipeline sees byte-identical output whether or not the repo has migrated.

A repo that has deliberately not migrated turns it off in the file it already has — notices is one of the keys a pre-versioned file may carry, precisely so that declining to migrate does not require migrating:

{
  "project": "myapp",
  "notices": { "deprecations": false }
}

Self-documenting files

JSON has no comments, so point $schema at the generated JSON Schema and your editor supplies completion, hover documentation, and inline validation:

{
  "$schema": "https://commission.sh/schema/commission-config.schema.json",
  "version": 1,
  "project": "myapp"
}

Commission ignores $schema entirely — it is there for the editor.

Precedence

Lowest to highest — the last layer to set a key wins, and commission config explain <key> reports which one did:

1. defaults
2. db
3. file
4. local
5. env
6. flags

Objects merge key by key. Arrays replace wholesale and scalars replace — array merging is where config systems become unpredictable, so Commission does not do it.

.commission.local.json (the local layer) is for one machine and must not be committed; it may refine any setting but cannot declare project.

Environment overrides

An explicit table rather than a general convention:

COMMISSION_CONFIG names a config file directly and skips the upward search.

Fields

Related commands