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