Commands

This reference lists the supported MeshKit CLI commands, their required arguments, and the output each command is meant to produce.

Use it after the CLI quickstart. The quickstart teaches the first local workflow; this page is for exact command lookup.

Global Flags

Flag	Default	Description
`--json`	`false`	Writes successful results as compact JSON to stdout. MeshKit-classified failures are written as structured JSON to stderr.
`--config <path>`	`meshkit.config.json`	Loads a specific CLI config file. Overrides `MESHKIT_CONFIG`.
`--store <path>`	`.meshkit/local-dev.json`	Uses a specific local-dev state file. Overrides `MESHKIT_STORE` and the `local-dev` provider config value.

Environment Variables

Variable	Used for
`MESHKIT_CONFIG`	Config file path when `--config` is not passed.
`MESHKIT_STORE`	Local-dev state path when `--store` is not passed.
`MESHKIT_IPFS_API`	Live IPFS HTTP API URL shortcut. Requires `MESHKIT_METADATA_API`.
`MESHKIT_METADATA_API`	MeshKit metadata API URL shortcut. Requires `MESHKIT_IPFS_API`.
`MESHKIT_PROVIDER_TOKEN`	Provider bearer token fallback.
`MESHKIT_FILECOIN_ENDPOINT`	Filecoin bridge endpoint.
`MESHKIT_FILECOIN_TOKEN`	Filecoin bridge bearer token.
`MESHKIT_POLICY_ENDPOINT`	Policy provider endpoint.
`MESHKIT_POLICY_TOKEN`	Policy provider bearer token.

Prefer tokenEnv fields in meshkit.config.json for committed config and keep token values in the environment or a secret manager.

Local Setup Commands

Command	Required arguments	Output
`meshkit init`	None	Creates `.env.local`, `meshkit.config.json`, and local-dev state if missing.
`meshkit dev`	None	Reports provider name, store path, and readiness.
`meshkit dev put <name> <content>`	Optional `name`, text content	Stores encrypted content through the configured provider and returns a `MeshFile`.

meshkit dev put joins all remaining arguments into a single text payload. It is meant for small local examples and diagnostics, not bulk upload workflows.

Diagnostics Commands

Command	Required arguments	Output
`meshkit doctor`	None	Runs provider health checks through `mesh.doctor.run()`.
`meshkit providers test`	None	Runs the same health-check path as `doctor`; use it when the intent is provider validation.
`meshkit inspect <cid>`	`cid`	Returns proof metadata for the CID from `mesh.proofs.get(cid)`.
`meshkit logs`	None	Returns sanitized provider and observability events.

doctor and providers test prove the configured provider for that CLI process. They do not replace application-level tests of your actual SDK runtime.

Filecoin Bridge Commands

Command	Required arguments	Output
`meshkit deals status <dealId>`	`dealId`	Reads persistence status from the configured Filecoin HTTP bridge.
`meshkit deals renew <dealId> --duration-days <days>`	`dealId`; optional positive integer days	Requests renewal through the bridge.
`meshkit deals retrieve <dealId> --output <path>`	`dealId`, output path	Retrieves bridge content and writes bytes to the requested local path.

These commands require a configured persistence provider, either through MESHKIT_FILECOIN_ENDPOINT or a persistence block in meshkit.config.json.

Policy Commands

Command	Required arguments	Output
`meshkit policies test`	None	Runs health checks with the configured policy provider available to the client.
`meshkit policies audit <policyId>`	`policyId`	Returns the policy provider's audit trail for the policy.

Policy commands require a configured policy provider, either through MESHKIT_POLICY_ENDPOINT or a policy block in meshkit.config.json.

Supported Provider Configs

meshkit.config.json must include version: 1. The CLI supports these provider types:

Type	Required fields	Notes
`local-dev`	None	Optional `store`; for demos and repeatable local development only.
`ipfs-http`	`ipfsApiUrl`, `metadataApiUrl`	Use with a MeshKit metadata service, not raw IPFS alone.
`pinning-service`	`endpoint`, `storage`	Adds pinning behavior around another provider profile.
`gateway-retrieval`	`gatewayUrl`, `storage`	Uses gateway reads around another provider profile.
`ipfs-cluster`	`clusterApiUrl`, `metadataApiUrl`	Cluster coordinates IPFS nodes; metadata still comes from MeshKit service.
`fallback`	`providers`	Ordered provider list; all entries should preserve MeshKit metadata semantics.

Persistence supports filecoin-http. Policy supports lit-http.

Failure Output

Commands return exit code 1 on failure. With --json, failures look like this:

{
  "ok": false,
  "error": {
    "code": "missing_deal_id",
    "message": "Missing deal ID. Usage: meshkit deals status <dealId>",
    "suggestion": "Pass the dealId returned by file.persist."
  }
}

MeshKit errors include code, message, suggestion, and optional sanitized details. Generic thrown errors use cli_error.

Safe Output Rules

Safe to save in CI artifacts:

Command name and exit code.
Error code and suggestion.
CID, deal ID, provider name, proof summary, and redacted endpoint names.
JSON output with tokens and plaintext removed.

Unsafe to save:

Provider, Filecoin, or policy bearer tokens.
Private keys, exported identity secrets, and capability token secrets.
Plaintext payloads used with dev put.
Retrieved bytes from deals retrieve unless the artifact store is approved for that data.

On this page