Documentation / Start here

CLI reference

The CLI returns JSON, making the same operations usable by people, scripts, and agent hosts. All repository arguments identify the implementation repository root. MapForge resolves the managed planning worktree.

node /absolute/MapForge/dist/cli.js <operation> <development-repo> [arguments]

If the package is installed and its bin is on your PATH, use mapforge in place of node /absolute/MapForge/dist/cli.js.

Read operations

Operation Arguments after repository Purpose
list none List registered Maps
show <id> Read a validated Map and its planning preconditions
validate <id> Inspect and validate a Map
status <id> Inspect graph, evidence, and cached sync state

Status does not fetch from the remote. Cached upstream information alone does not confirm current remote state.

Local mutations

Operation Arguments after repository Purpose
create <id> "<title>" Create a Map and managed planning worktree
update /absolute/request.json Apply exact file replacements with preconditions
test <id> [step-id] Execute ready checks and record their evidence

Map IDs match [a-z][a-z0-9-]{0,79}. Updates require the planning HEAD and fingerprint returned by show. Stale preconditions stop the update; re-read and reconcile the intended change.

test exits nonzero for failures, skipped work, or no runnable checks. It does not stage, commit, or push. Declared check commands are ordinary scripts, so inspect them before running.

Commit and sync

node /absolute/MapForge/dist/cli.js commit /absolute/project /absolute/commit-request.json
{
  "id": "api-release",
  "expectedHead": "<planning HEAD from show>",
  "expectedFingerprint": "<map fingerprint from show>",
  "message": "Document API release checks",
  "remote": "origin"
}

This operation includes publication to the verified matching GitHub repository's map/<id> branch. It does not publish the implementation branch. Review the commit workflow for the validation sequence and interrupted-publication behavior.

General flags

node /absolute/MapForge/dist/cli.js --help
node /absolute/MapForge/dist/cli.js --version