enji-guard-cli

Python 3.14 CLI and MCP bridge for Enji Guard.

This repository is an early prototype. It supports a shared core, a Typer CLI, and a FastMCP server that can expose Enji Guard access and compact report metadata to local tools.

Mental Model

Enji Guard groups GitHub repositories into projects. Most workflows should use the GitHub owner/name repository selector; add --project NAME_OR_ID only when the account has ambiguous repositories or when a batch operation must be scoped to one project.

Mutating batch commands require explicit scope. Use a REPO argument for one repository, --all-repos with --project NAME_OR_ID for every repository in one project, or --all-projects for every repository in every project.

Project admin commands are direct domain actions: create, rename, delete, and move repositories between projects. project delete is destructive and requires --yes.

Recon is baseline discovery. Report audits are separate, slow jobs that produce readable reports and scores. Scores are triage hints: use them to sort and prioritize repositories, then read the reports before changing code. When a report exposes commit hashes, compare them with the current checkout before treating the report as fresh.

CLI output is human text and tables by default. Use --json only when another tool needs structured output.

Related MCP server: MCP HTTP Proxy

Agent Workflow

The service runtime is Docker. Agents should call the CLI inside the running container instead of installing or running this Python package on the host:

docker exec -i enji-guard-cli enji-guard --help

Application logs are persisted outside the container at:

~/.config/enji-guard/logs/enji-guard.jsonl

CLI stdout/stderr are reserved for command results, progress, and CLI errors. Use the log file for HTTP/auth/runtime telemetry.

When working on another repository, pass the repository as OWNER/NAME. If an agent is already in a GitHub checkout and wants to derive it from origin, it can do that in the host shell and still pass an explicit selector to the container:

REPO=$(git config --get remote.origin.url | sed -E 's#^git@github.com:##; s#^https://github.com/##; s#\.git$##')

docker exec -i enji-guard-cli enji-guard auth status
docker exec -i enji-guard-cli enji-guard repo resolve "$REPO"
docker exec -i enji-guard-cli enji-guard status "$REPO"

If the repository is absent from Enji:

docker exec -i enji-guard-cli enji-guard repo connect "$REPO"

For triage across all visible repositories:

docker exec -i enji-guard-cli enji-guard status --sort weakest
docker exec -i enji-guard-cli enji-guard repo list --sort latest-report

For reports:

docker exec -i enji-guard-cli enji-guard audit start "$REPO" --all
docker exec -i enji-guard-cli enji-guard wait "$REPO"
docker exec -i enji-guard-cli enji-guard report read "$REPO"

Recon and report audits can take tens of minutes. Use status for a snapshot, wait until all report audits have results, and report read after reports are ready. wait reports stale audited commit hashes but does not fail only because Enji has not caught up to the current HEAD. Prefer reading reports through CLI/MCP instead of relying on email; disable noisy scheduled mail when it is not part of the workflow.

Requirements

• Docker

• uv, only for repository development and QA

Runtime

mkdir -p ~/.config/enji-guard/logs
chown -R 1000:1000 ~/.config/enji-guard
chmod 700 ~/.config/enji-guard

docker compose up -d --force-recreate --remove-orphans --wait
docker exec -i enji-guard-cli enji-guard --help

Compose binds MCP to loopback, defines the service healthcheck, and limits the container to 512 MiB memory.

Authentication

Preferred future path is an Enji API token:

printf '%s' "$ENJI_API_TOKEN" | docker exec -i enji-guard-cli enji-guard auth import-token --stdin

Until API tokens are available, cookie auth is supported as a temporary compatibility path:

pbpaste | docker exec -i enji-guard-cli enji-guard auth import-cookie --stdin
docker exec -i enji-guard-cli enji-guard auth status

Do not paste credentials directly into shell history. The auth file defaults to ~/.config/enji-guard/auth.json and is written with private file permissions.

CLI

docker exec -i enji-guard-cli enji-guard access
docker exec -i enji-guard-cli enji-guard project list
docker exec -i enji-guard-cli enji-guard project create Pets
docker exec -i enji-guard-cli enji-guard project rename Pets Friends
docker exec -i enji-guard-cli enji-guard project delete Pets --yes
docker exec -i enji-guard-cli enji-guard repo resolve j2h4u/enji-guard-cli
docker exec -i enji-guard-cli enji-guard repo move j2h4u/enji-guard-cli --to-project Friends
docker exec -i enji-guard-cli enji-guard status j2h4u/enji-guard-cli
docker exec -i enji-guard-cli enji-guard audit start j2h4u/enji-guard-cli --all
docker exec -i enji-guard-cli enji-guard wait j2h4u/enji-guard-cli
docker exec -i enji-guard-cli enji-guard report read j2h4u/enji-guard-cli
docker exec -i enji-guard-cli enji-guard --project Pets schedule list
docker exec -i enji-guard-cli enji-guard --project Pets schedule set --all-repos --enabled off
docker exec -i enji-guard-cli enji-guard --project Pets email set --all-repos --auto off
docker exec -i enji-guard-cli enji-guard auth refresh

Pass --json when a command output is consumed by automation.

Use the global --project NAME_OR_ID filter when a command must be scoped to one Enji project. repo move uses global --project as source project or selector disambiguation when needed. --to-project selects the destination project.

schedule controls automatic report-audit runs. It shows one row per repo/report audit and can batch update all report audits for one repo or one explicit batch scope. Use REPO, --project NAME_OR_ID --all-repos, or --all-projects.

MCP

Local HTTP MCP service:

docker compose up -d --force-recreate --remove-orphans --wait

Endpoint:

http://127.0.0.1:8001/mcp

The Docker service starts a background cookie refresh loop. Keep ~/.config/enji-guard writable by the container user.

Development

just verify

The completion gate includes Ruff, basedpyright, import-linter, Vulture, deptry, OpenAPI contract validation, CRAP <= 30 per function, tests, and Docker build.

Security Notes

Cookie auth is temporary and will be removed when API-token support is available from Enji. MCP HTTP transports do not add their own authentication; keep them bound to loopback or behind an explicit trusted boundary.

License

PolyForm Noncommercial License 1.0.0. Commercial use requires separate permission.