Command line#

AI Generated, Human Reviewed at: 2026-11-18T15:58:59Z

Every tool is also a command: bowerbird-mcp <tool> ... (or uvx bowerbird-mcp, or uv run bowerbird_mcp.py from a checkout). The command line has all the tools; an MCP server offers only the ones its roles allow. For CI see the guide, and for connecting an assistant see getting started.

Finding your way#

bowerbird-mcp help            # the everyday commands for this collection's format, grouped
bowerbird-mcp help all        # every command, one line each
bowerbird-mcp help seal       # one tool: what it does, its arguments, examples
bowerbird-mcp seal -h         # the same, as flags
bowerbird-mcp --version

help shows only what the collection's format uses. An unknown command prints the help and exits 2.

Two ways to pass arguments#

bowerbird-mcp lint scope=okf output=github      # name=value: the stable form, for scripts and agents
bowerbird-mcp lint -s okf -O github             # flags: the same call, for people
bowerbird-mcp seal '{"file": "db.md"}'          # or one JSON object

Flags are turned into the same name=value words, so both behave alike. Lists are a,b or JSON. Bare words fill the required arguments in order (move a.md b.md); on set, any other key=value is frontmatter (set a.md status=deprecated tags=[x,y]).

  • Long flags are the argument's name (--due-days) and are never abbreviated: --app is not --apply.
  • The everyday commands have pinned short flags that never change, and -B is bundle on all of them:
Command Short flags
init -A apply, -a about, -t holds, -B bundle, -u user
seal -f file, -b by, -p promote, -d decision, -c check, -s since, -B bundle
lint -s scope, -l limit, -b baseline, -S since, -a all, -f file, -i ignore, -B bundle
search, passages -q query, -t type, -g tag, -d dir, -l limit, -B bundle
list -t type, -g tag, -s status, -T tier, -S stale, -l limit, -B bundle
status -d due-days, -B bundle
get, links -f file, -B bundle (get also -l limit)
  • Every other command takes the first free letter of each argument, in order. Those can shift, so use long flags in scripts.
  • -h and -O/-F are reserved: -h is help, -O (or -F, or output=) chooses the output.

Serve#

bowerbird serve opens the collection in a browser at http://127.0.0.1:26937/, as a front end to the same tools, for a person: browse, search four ways, edit, create, move, delete, tag, lint and seal, with no AI in it. The full guide is on the Serve page.

bowerbird serve status      # information only: is it running? exit 0 if so, 1 if not. A bare `serve` does this
bowerbird serve start       # in the background; a no-op if ours is already on the port
bowerbird serve start -f    # in the foreground (ctrl-c stops)
bowerbird serve stop        # end it; nothing running is not an error
bowerbird serve restart     # stop what is found, then start: always ends with a running server
bowerbird serve start 8080  # another port (any verb takes one; 26937 when left out)

It needs the serve extra: pip install 'bowerbird-mcp[serve]', or uvx --from 'bowerbird-mcp[serve]' bowerbird-mcp serve.

Output#

At a terminal the output is text. Piped, in CI or in a script it is JSON. -O json|text|github|sarif overrides either (github and sarif are for lint). Text prints diffs as they are.

Exit codes#

Code Meaning
0 done, or nothing found
1 findings: lint errors, or seal check=true has unsigned, stale or claimed-accepted files
2 a usage error: unknown flag, missing argument, or --attest without a terminal

Changing things safely#

Tools that touch many files default to apply=false: they print the plan and the diff and write nothing. Read it, then repeat with --apply (or apply=true).

bowerbird-mcp rename new-name --bundle old-name            # the plan and diff
bowerbird-mcp rename new-name --bundle old-name --apply    # write it

Lint, then fix#

lint only reports: it never changes a file. fix is its repair half, for what needs no judgment (generated index lists, tag spelling, log.md order, index.md frontmatter). It follows the same rule: no --apply, a diff.

bowerbird-mcp lint                # what is wrong (exit 1 on errors)
bowerbird-mcp fix                 # the repairs as a diff (exit 1 if there is work)
bowerbird-mcp fix --apply         # write them, re-lint, report what remains

Sealing as a person#

--attest records you as a human, as human:<KB_USER> (else your git user.email). It works only on the command line, needs a terminal (stdin a TTY), and no MCP call can pass it. It applies to seal, create, provenance and recheck_apply.

bowerbird-mcp seal deploy.md --attest
bowerbird-mcp ratify docs/adr/0001-queue.md --attest decision=accepted   # ratify and verify are names for seal
bowerbird-mcp seal check=true since=origin/main                          # what lacks a review (exits 1 if any)

Settings#

kbmcp.yaml at the collection root sets the defaults, .env and KB_* variables override it, and the flags --config <path> and --role <role> pick a collection and a role for the server. The guide lists every key.