Skip to content

CLI-SPEC.md

Latest commit

 

History

History
161 lines (114 loc) · 5.02 KB

CLI-SPEC.md

File metadata and controls

161 lines (114 loc) · 5.02 KB
Raw

git-blinder — CLI specification

CLI interface aligned with the current implementation. Behavioral contracts live in features/cli/.

Version 0.4 · Date 2026-08-11

Principles

  • One command does one thing.
  • Operator commands talk to a running server via --url (default http://127.0.0.1:7400).
  • Operator API calls send Authorization: Bearer <ops-token> — same secret as serve (--token or GITHUB_TOKEN).
  • Errors are clear, actionable, and written to stderr.
  • The token never appears in config files or logs.

serve

git-blinder serve --token <GITHUB_TOKEN> [--port <PORT>] [--config <PATH>]
Flag Required Default Description
--token yes* — GitHub PAT (* or GITHUB_TOKEN) ; also becomes the ops Bearer for /api/*
--port no 7400 Listen port
--config no config.yaml Optional perimeter preload

Behaviour:

  1. Missing token → exit with a clear error.
  2. Validate token against GitHub ; print identity / scopes.
  3. Listen on 127.0.0.1:<port>.
  4. Expose health /mcp, ops /mcp/root, perimeter /mcp/<id>[/<branch>], and Bearer-protected /api/* (see SPEC §9).

tools

git-blinder tools

Prints the built-in catalogue (all tools git-blinder knows how to handle).

Shared flags (operator commands)

Commands that hit /api/* accept:

Flag Required Default Description
--token yes* — Ops Bearer (* or GITHUB_TOKEN)
--url no http://127.0.0.1:7400 Running server base URL

Missing ops token → clear stderr error (do not call the API unauthenticated).

repos list

git-blinder repos list [--url <url>] [--token <TOKEN>]

Lists repositories visible to the server token (GET /api/repos).

branches list

git-blinder branches list --repo <owner/repo> [--url <url>] [--token <TOKEN>]

Lists GitHub branches for a repository (operator discovery).
Not the agent surface — agents do not get list_branches on perimeter MCP.

perimeter

git-blinder perimeter create <id> --repo <owner/repo> --read <glob> [--write <glob>] [--tools a,b,c] [--url <url>] [--token <TOKEN>]
git-blinder perimeter list [--url <url>] [--token <TOKEN>]
git-blinder perimeter show <id> [--url <url>] [--token <TOKEN>]
git-blinder perimeter delete <id> [--url <url>] [--token <TOKEN>]
  • Id must be URL-safe ([a-z0-9-]+).
  • Id root is reserved (ops MCP at /mcp/root) → create fails with a clear error.
  • Create resolves the repo default branch and seeds branches = [default].
  • Delete unbinds /mcp/<id> (and branch bindings).

perimeter branch

git-blinder perimeter branch list <id> [--url <url>] [--token <TOKEN>]
git-blinder perimeter branch add <id> <branch> [--url <url>] [--token <TOKEN>]
git-blinder perimeter branch remove <id> <branch> [--url <url>] [--token <TOKEN>]
  • add verifies the branch exists on GitHub ; otherwise error telling the operator to create it first.
  • remove cannot remove the default branch.

perimeter commits

git-blinder perimeter commits list <id> [--branch <name>] [--url <url>] [--token <TOKEN>]
git-blinder perimeter commits show <id> <sha> [--branch <name>] [--url <url>] [--token <TOKEN>]

Same filtering rules as MCP list_commits / get_commit (path prefixes from read, opaque omitted_count).
--branch must be allowlisted ; default = perimeter default branch.

Endpoints (operator cheat-sheet)

Path Role
GET /mcp Health + perimeter ids (no tools)
POST /mcp 405 — no MCP tools here
GET/POST /mcp/root Unfiltered ops MCP (not for agents)
GET/POST /mcp/<id>[/<branch>] Scoped agent MCP
/api/* Bearer required (same token as serve)

Tool catalogue

Tool Verb Ops /mcp/root Perimeter agent
get_tree read yes yes
get_file read yes yes
get_files read yes yes
push_files write yes yes (atomic commit on bound branch)
list_commits read yes yes (path-filtered)
get_commit read yes yes (files filtered + omitted_count)
list_branches read yes no
compare read yes no

Features

Feature Contract
features/cli/01_serve.feature serve ; GET /mcp health ; POST /mcp → 405 ; /mcp/root tools/list
features/cli/02_perimeter.feature create / list / show / id validation
features/cli/03_perimeter_mcp.feature /mcp/<id> binding + tool subsets ; ops root stays unfiltered
features/cli/04_branches.feature branches list
features/cli/05_repos.feature repos list
features/cli/06_perimeter_branches.feature allowlist add/list/remove
features/cli/07_mcp_branch_binding.feature /mcp/<id>/<branch> + forced ref
features/cli/08_commit_history.feature filtered commits CLI (+ MCP tools present)
features/support/01_api_perimeters.feature /api CRUD + 401 without Bearer + reserved root