CLI
bamfs — upload, read, verify, tag, transfer, and prove from a terminal.
bamfs upload ./site --name my-project --tag v1Configuration
Two inputs, and only one of them is a file:
.bamfs.jsonin the working directory — chain keys, RPC URLs, and per-chain defaults such asdefaultCompressionanddefaultBundleGasBudget. Reads against a canonical chain need none of this; the SDK ships the addresses.BAMFS_PRIVATE_KEYin the environment — required only for writes. The CLI never reads a key from disk and never writes one there.
Every command takes -c, --chain <name> to select a network. Omitted, it resolves to the
production chain — Base. A defaultChain in .bamfs.json overrides that, and an explicit
--chain overrides both.
Commands
| Command | What it does |
|---|---|
upload <path> | Upload a directory or single file. With --name, also mints a project token and publishes to it. |
update <path> | Publish a new version of an existing project from a local path. |
read <cid> | Read a file or directory back out of contract storage. |
info | Project metadata, version history, and tags. |
diff <dir> | Diff a local directory against the on-chain tree. |
tag | set / remove / get / list — mutable named pointers to versions. |
transfer <projectId> <newOwner> | Hand a project to a new owner. One tx, effective immediately. |
verify <cid> | Check that a BAMFS CID resolves to the expected IPFS CID, on-chain and locally. |
pin | Pin a root to IPFS via local Kubo, Pinata, or any PSA-compatible service. |
prove <rootCid> | Generate a ZK proof that a root maps to a deterministic IPFS CID. |
submit-proof <artifact> | Submit a proof artifact to IpfsCidVerifier. |
prove-and-submit <rootCid> | Both of the above in one step. |
dev | Run a local Anvil chain with BAMFS contracts deployed. |
bamfs <command> --help is authoritative for flags.
Writing
upload and update share the flags that matter:
| Flag | Notes |
|---|---|
--compress <codec> | none | gzip | brotli | fastlz. Defaults to the chain's defaultCompression, which is fastlz on the canonical chains. |
--tag <tag> | Tag the published version. latest is reserved — it always resolves to the head. |
--dry-run | Compute CIDs and print the plan; send nothing. (upload only.) |
--max-bundle-gas <gas> | Ceiling per multicall bundle. Defaults to 24,000,000, then clamps under the node's estimate cap. |
--no-bundle | One transaction per chunk write. Slower; useful when diagnosing a failing bundle. |
--dry-run is the cheap way to answer "how many transactions is this, and what
will the CID be" before spending anything.
--compress must match between upload and diff. A mismatch re-derives every
expected CID and reports the whole tree as changed.
Reading
Reads need no key and no account:
bamfs read <root> --path index.html -o ./index.html
bamfs info --project-id 4
bamfs verify <root>read writes to stdout unless given -o, so it pipes.
Pinning
BAMFS does not run a pinning service. pin hands the bytes to one you choose:
bamfs pin --project-id 4 --provider local --endpoint http://127.0.0.1:5001
bamfs pin --project-id 4 --provider pinata --api-key "$PINATA_JWT"It verifies the resulting CID against the on-chain resolver unless you pass
--no-verify. See IPFS for why the CID matches, and
when it does not.