pepper CLI reference

Synopsis and global options

pepper [--api <URL>] [--api-token <TOKEN>] [--json] <COMMAND>

--api <URL>

Agent base URL. PEPPER_API environment variable; default http://127.0.0.1:9080.

--api-token <TOKEN>

Bearer token for auth.api_bearer_token. PEPPER_API_TOKEN environment variable.

--json

Emit JSON instead of human-readable output where supported.

-h, --help

Print help. Global options may be placed before or after subcommands.

Node and immutable storage

node status

Show the local node identity, configuration summary, schema, addresses, and uptime.

node peers

List P2P peers known by the local agent.

block put <PATH> [--replicas N]

Store one raw block, optionally overriding durability, and implicitly pin it.

block get <CID> -o <PATH>

Retrieve and verify a raw block.

block has <CID>

Check local block presence.

object put <PATH> [--erasure DATA:PARITY]

Chunk a file into an object DAG or an erasure-coded object and pin its root.

object get <CID> -o <PATH>

Stream and verify an object to a file.

dir put <PATH>

Store and pin a regular-file directory snapshot.

dir get <CID> <OUTPUT>

Safely restore a directory snapshot.

Pins and compute

pin create <CID> [--replicas N]

Create an explicit permanent root pin and ensure durability.

pin status <CID>

Show direct active pins and reachable-block count.

pin delete <CID>

Delete pins owned by this API node.

compute submit <PATH>

Submit a version-1 Firecracker job JSON specification.

compute status <JOB_ID>

Show persisted job state and receipt metadata.

compute logs <JOB_ID>

Show captured stdout/stderr content and metadata.

compute cancel <JOB_ID>

Cancel a queued, delegated, or running job.

compute output <JOB_ID>

Print a completed job's output root CID.

Compute job JSON

{
  "type": "command",
  "version": 1,
  "runtime": "firecracker",
  "rootfs_cid": "cid://...",
  "command": ["/bin/sh", "-c", "process /inputs/data > /output/result"],
  "inputs": [
    {"mount": "/inputs/data", "cid": "cid://..."}
  ],
  "outputs": [
    {"path": "output/result", "name": "result"}
  ],
  "resources": {
    "timeout_seconds": 300,
    "max_input_bytes": 1073741824,
    "max_output_bytes": 1073741824,
    "memory_mib": 128,
    "cpu_millis": 1000,
    "pids_max": 128
  }
}

command must be non-empty. runtime must be firecracker when supplied. Input mount paths and output paths/names must be safe and unique. rootfs_cid is required for execution and subject to the agent allowlist. Requested resources are capped by agent configuration.

Namespaces and KV

namespace create --kind <KIND> [--alias NAME]

Create a three-replica transactional namespace.

namespace inspect|status|replicas|history <NAMESPACE>

Inspect namespace data, Raft health, voters, or revisions.

namespace diff <NAMESPACE> <A> <B>

Compare two revisions.

namespace rollback <NAMESPACE> <REVISION> [--request-id ID]

Publish an older root as a new revision.

namespace snapshot create <NAMESPACE> <NAME> [--revision N] [--request-id ID]

Create a named retained snapshot.

namespace snapshot delete <NAMESPACE> <NAME> [--request-id ID]

Delete a named snapshot.

namespace snapshot list <NAMESPACE>

List named snapshots.

kv get <NAMESPACE> <KEY> [--revision N] [--root CID] [--checkpoint CID]

Read a key linearly or from selected history.

kv put <NAMESPACE> <KEY> --cid CID [PRECONDITIONS]

Set a key to an existing CID.

kv put-file <NAMESPACE> <KEY> <PATH> [PRECONDITIONS]

Upload a file object and atomically publish its CID.

kv delete <NAMESPACE> <KEY> [PRECONDITIONS]

Delete a key.

kv scan <NAMESPACE> [--prefix TEXT] [--limit N] [--cursor CURSOR] [--revision N]

Scan ordered keys; default limit 100.

kv txn apply <NAMESPACE> <PATH> [--request-id ID]

Apply a version-1 JSON transaction.

Buckets

bucket create <ALIAS>

Create a versioned bucket namespace.

bucket put <BUCKET> <KEY> <PATH> [--content-type TYPE] [PRECONDITIONS]

Upload and publish an object version.

bucket get <BUCKET> <KEY> -o <PATH> [--revision N]

Download the live or historical object.

bucket head <BUCKET> <KEY> [--revision N]

Inspect object metadata without downloading content.

bucket delete <BUCKET> <KEY> [PRECONDITIONS]

Append a delete tombstone.

bucket list <BUCKET> [--prefix TEXT] [--limit N] [--cursor CURSOR] [--revision N]

List live objects at a stable root.

bucket versions <BUCKET> <KEY>

Show immutable versions and tombstones.

Filesystems

fs create <ALIAS>

Create a filesystem namespace.

fs commit <FS> <SOURCE> --base-revision N [--message TEXT] [--request-id ID]

Upload a local tree and atomically commit it.

fs checkout <FS> <DESTINATION> [--revision N]

Materialize the head or a selected revision.

fs history <FS>

List filesystem revisions.

fs diff <FS> <A> <B>

Compare two filesystem revisions.

fs restore <FS> <REVISION> <DESTINATION>

Materialize a historical revision without moving the head.

fs rollback <FS> <REVISION> [--request-id ID]

Create a new head from an older revision.

fs clone-from-root <FS> <ROOT_CID> [--request-id ID]

Commit a previously created filesystem root.

fs mount <FS> <MOUNTPOINT>

Reserved experimental command; FUSE is not enabled in 0.2.0.

Administration

admin gc [--dry-run]

Collect local blocks unreachable from active synchronized roots.

admin repair

Run provider and durability repair immediately.

admin status

Show subsystem, authentication, queue, and configured-limit status.

admin storage

Show block counts, capacity, reservations, usage, and pressure.

admin erasure

Show erasure policy, health, and repair metrics.

admin corruption-scan

Verify local block files and attempt recovery.

admin quarantine-purge

Permanently remove quarantined invalid files.

admin namespace checkpoint <NAMESPACE>

Create a namespace checkpoint.

admin namespace rebalance <NAMESPACE>

Evaluate and apply capacity-aware replica rebalancing.

admin namespace replace-replica <NAMESPACE> <FAILED_NODE> [--replacement-node NODE]

Catch up a learner and safely replace a voter.

admin namespace recover <NAMESPACE> <CHECKPOINT_CID> --members N1 N2 N3 --confirm-fork-risk

Explicit quorum-loss disaster recovery with fork-risk acknowledgement.

Preconditions, request IDs, and exit codes

PRECONDITIONS means optional --if-generation N, --if-cid CID, and --request-id ID where the command exposes them. JSON output is recommended for automation. Exit 1 is a general failure; namespace-aware stable categories are 20 conflict, 21 unavailable/not leader, 22 durability not met, 23 unauthorized/forbidden, and 24 invalid request/cursor.