Operate Folderbase from an agent

Agents can use the Folderbase CLI directly. An MCP server is optional rather than required.

Discover the contract

folderbase protocol contract --json
folderbase --help-json

Use the reported contract instead of guessing which commands or fields exist.

List the workspace

folderbase workspace list /path/to/project --json

The result exposes ordinary workspace files and suppresses engine state and common reconstructable noise.

Read a file

folderbase workspace read /path/to/project FOLDERBASE.md --json

Retain the returned SHA-256 with the content. It becomes the concurrency precondition for a save.

Save without clobbering

printf '%s' "$UPDATED_TEXT" | folderbase workspace save \
  /path/to/project FOLDERBASE.md \
  --expected-sha256 "$LOADED_SHA256" \
  --stdin \
  --json

If the expected hash no longer matches, read the current file and reconcile instead of retrying an unconditional overwrite.

Large and binary files

Agents should inspect metadata before retrieving or transforming large content. Folderbase uses streaming and content-addressed chunks for transfer rather than requiring an entire object to fit in model context.

See CLI JSON v1 for transport guarantees.