CLI

The MeshKit CLI is the terminal surface for setup, diagnostics, provider validation, proof inspection, policy checks, and Filecoin bridge operations.

It does not replace the SDK path in your application. Use the CLI to prove that a MeshKit environment is configured correctly, collect release evidence, inspect encrypted objects, and run repeatable local-development workflows from a shell or CI job.

When To Use It

Use the CLI when you need to	Use the SDK when you need to
Initialize a local MeshKit sandbox.	Store and read data inside an application flow.
Run provider health checks before a release.	Build product features around files, records, sharing, messages, or sync.
Inspect a CID or proof returned by a previous operation.	Control runtime behavior, identity resolution, UI state, and retries.
Audit policy and Filecoin bridge state from operations tooling.	Handle user-facing errors and persist workflow state in your database.

Install

Run the CLI through npx or install it as a dev dependency:

npx -p @meshkit/cli meshkit doctor --json

npm install -D @meshkit/cli
npx meshkit doctor --json

The package requires Node.js 20.11 or newer.

Configuration Model

The CLI loads configuration in this order:

--config <path> when passed.
MESHKIT_CONFIG when set.
meshkit.config.json in the current working directory.

Local-dev state is stored in this order:

--store <path> when passed.
MESHKIT_STORE when set.
provider.store from a local-dev config.
.meshkit/local-dev.json.

meshkit init writes .env.local, meshkit.config.json, and local-dev state only when those files are missing. Keep .env.local and token values out of source control.

Command Map

Goal	Command
Create local config	`meshkit init`
Check current local provider and store path	`meshkit dev`
Store sample encrypted content	`meshkit dev put <name> <content>`
Run health checks	`meshkit doctor`
Inspect proof metadata for a CID	`meshkit inspect <cid>`
Read sanitized provider events	`meshkit logs`
Validate the configured provider	`meshkit providers test`
Check Filecoin bridge deal state	`meshkit deals status <dealId>`
Request Filecoin bridge renewal	`meshkit deals renew <dealId> --duration-days <days>`
Retrieve Filecoin bridge content	`meshkit deals retrieve <dealId> --output <path>`
Check policy provider health	`meshkit policies test`
Audit a policy decision trail	`meshkit policies audit <policyId>`

Add --json for machine-readable output. JSON failures write to stderr as:

{
  "ok": false,
  "error": {
    "code": "invalid_cli_config",
    "message": "meshkit.config.json must set version to 1.",
    "suggestion": "Fix meshkit.config.json or pass a different config file with --config."
  }
}

Production Boundary

CLI evidence proves the environment used by that command. It does not prove every application code path. For production claims, combine CLI output with SDK workflow evidence that shows write, read, metadata, proof, sharing, policy, and cleanup behavior for the actual runtime you ship.

Never commit provider tokens, Filecoin bridge tokens, policy tokens, private keys, capability secrets, decrypted content, or raw user payloads captured while debugging.

Next Steps

Start with CLI quickstart for a local round trip.
Use Commands as the reference surface.
Use Provider testing before changing provider profiles or release claims.
Use Production setup before calling a provider production-ready.