pepper CLI reference

Synopsis and global options

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

--api <URL>

Local agent URL. Environment: PEPPER_API. Default: http://127.0.0.1:9080.

--api-token <TOKEN>

Bearer token. Environment: PEPPER_API_TOKEN.

--json

Emit JSON instead of human-readable output where supported.

-h, --help

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

Node

node status

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

node peers

List P2P peers known by the local agent.

Raw blocks

block put <PATH>

Store PATH as one immutable raw block and implicitly pin its CID.

block get <CID> --output <PATH>

Retrieve and verify CID; -o is the short form of --output.

block has <CID>

Check whether the local agent stores CID.

Objects

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

Chunk and store a file, then implicitly pin its root manifest. --erasure requests Reed-Solomon coding.

object get <CID> --output <PATH>

Stream and verify an object to PATH; -o is accepted.

Directories

dir put <PATH>

Store a regular-file directory snapshot and implicitly pin its root manifest. Symlinks and special files are not included.

dir get <CID> <OUTPUT>

Restore a snapshot without traversing destination symlinks. Root restores require PEPPER_ALLOW_ROOT_RESTORE=1.

Pins

pin create <CID> [--replicas N]

Create an explicit permanent root pin and ensure the requested replication factor.

pin status <CID>

Show direct active pins and reachable block count for a root.

pin delete <CID>

Delete pins owned by this API node. Use the node that created the pin.

Compute

compute submit <PATH>

Submit a JSON Firecracker job specification.

compute status <JOB_ID>

Show persisted job state and receipt information.

compute logs <JOB_ID>

Show captured stdout and stderr metadata/content.

compute cancel <JOB_ID>

Request cancellation of a queued, delegated, or running job.

compute output <JOB_ID>

Print the 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 mandatory for execution and subject to the agent allowlist. Resource values are additionally capped by agent configuration.

Administration

admin gc [--dry-run]

Collect local blocks not reachable from active synchronized pins. --dry-run only reports.

admin repair

Run a repair pass immediately.

admin status

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

admin storage

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

admin erasure

Show erasure policy and shard health.

admin corruption-scan

Verify local block files and report corruption.

admin quarantine-purge

Permanently remove quarantined invalid files.

Exit and safety behavior

Commands return nonzero on connection, HTTP, validation, integrity, or filesystem errors. Downloads use bounded streaming. Directory restoration rejects unsafe paths, symlink traversal, and root execution unless explicitly opted in.