{"id":15061727,"url":"https://github.com/ipfs-cluster/js-cluster-client","last_synced_at":"2025-10-04T21:31:28.310Z","repository":{"id":57276556,"uuid":"184316732","full_name":"ipfs-cluster/js-cluster-client","owner":"ipfs-cluster","description":" A client library for the IPFS Cluster HTTP API, implemented in JavaScript.","archived":false,"fork":true,"pushed_at":"2019-09-05T18:06:08.000Z","size":111,"stargazers_count":31,"open_issues_count":4,"forks_count":16,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-09-25T23:23:51.885Z","etag":null,"topics":["ipfs","ipfs-cluster","ipfs-cluster-api","ipfs-http-client","js"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"te0d/js-ipfs-cluster-api","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ipfs-cluster.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-04-30T19:04:48.000Z","updated_at":"2024-05-17T16:48:55.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ipfs-cluster/js-cluster-client","commit_stats":null,"previous_names":["cluster-labs/ipfs-cluster-api","ipfs-cluster/ipfs-cluster-api"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipfs-cluster%2Fjs-cluster-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipfs-cluster%2Fjs-cluster-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipfs-cluster%2Fjs-cluster-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipfs-cluster%2Fjs-cluster-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ipfs-cluster","download_url":"https://codeload.github.com/ipfs-cluster/js-cluster-client/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":219876787,"owners_count":16554787,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ipfs","ipfs-cluster","ipfs-cluster-api","ipfs-http-client","js"],"created_at":"2024-09-24T23:24:17.073Z","updated_at":"2025-10-04T21:31:28.006Z","avatar_url":"https://github.com/ipfs-cluster.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"https://i.pinimg.com/564x/f4/f9/68/f4f968409552de91c2ff09d2a141f2e4.jpg\" alt=\"ipfs-cluster-api\" /\u003e\n\u003c/p\u003e\n\u003ch3 align=\"center\"\u003eA Javascript client library for the IPFS Cluster HTTP API.\u003c/h3\u003e\n\n[![Made by](https://img.shields.io/badge/made%20by-Cluster%20Labs-blue.svg?style=flat-square)](https://clusterlabs.io) [![Main project](https://img.shields.io/badge/project-ipfscloud-blue.svg?style=flat-square)](http://github.com/cluster-labs/ipfscloud-web) [![npm version](https://badge.fury.io/js/ipfs-cluster-api.svg)](https://badge.fury.io/js/ipfs-cluster-api)\n \u003ca href=\"\"\u003e\u003cimg src=\"https://img.shields.io/badge/npm-%3E%3D3.0.0-orange.svg?style=flat-square\" /\u003e\u003c/a\u003e \u003ca href=\"\"\u003e\u003cimg src=\"https://img.shields.io/badge/Node.js-%3E%3D8.0.0-orange.svg?style=flat-square\" /\u003e\u003c/a\u003e \u003ca href=\"https://david-dm.org/cluster-labs/ipfs-cluster-api\"\u003e\u003cimg src=\"https://david-dm.org/cluster-labs/ipfs-cluster-api.svg?style=flat-square\" /\u003e\u003c/a\u003e \u003ca href=\"https://bundlephobia.com/result?p=ipfs-cluster-api\"\u003e\u003cimg src=\"https://flat.badgen.net/bundlephobia/minzip/ipfs-cluster-api\"\u003e\u003c/a\u003e \u003ca href=\"https://github.com/feross/standard\"\u003e\u003cimg src=\"https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat-square\"\u003e\u003c/a\u003e\n [![Join the chat at https://gitter.im/ipfs-cluster-api/community](https://badges.gitter.im/cluster-labs/ipfs-cluster-api.svg)](https://gitter.im/ipfs-cluster-api/community)\n [![Build Status](https://travis-ci.org/cluster-labs/ipfs-cluster-api.svg?branch=master)](https://travis-ci.org/cluster-labs/ipfs-cluster-api)\n [![Code Coverage](https://codecov.io/gh/cluster-labs/ipfs-cluster-api/branch/master/graph/badge.svg)](https://codecov.io/gh/cluster-labs/ipfs-cluster-api)\n---\n\n**UNOFFICIAL AND ALPHA**\n\nThis is a port of `ipfs/js-ipfs-api` adapted for the API exposed by `ipfs/ipfs-cluster`.\n\n## Maintainer\n\n[**Vaibhav Saini**](https://github.com/vasa-develop)\n\n## Table of Contents\n\n- [Install](#install)\n  - [Running the daemon with the right port](#running-the-daemon-with-the-right-port)\n  - [Importing the module and usage](#importing-the-module-and-usage)\n\t- [In a web browser through Browserify](#through-browserify)\n\t- [In a web browser through Webpack](#through-webpack)\n\t- [In a web browser through CDN](#from-cdn)\n  - [Custom Headers](#custom-headers)\n- [Usage](#usage)\n  - [API Docs](#api)\n  - [Callbacks and promises](#callbacks-and-promises)\n- [Development](#development)\n- [Contribute](#contribute)\n- [Historical Context](#historical)\n- [License](#license)\n\n\n## Install\n\nThis module uses node.js, and can be installed through npm:\n\n```\nnpm install --save ipfs-cluster-api\n```\n\nWe support both the Current and Active LTS versions of Node.js. Please see [nodejs.org](https://nodejs.org/) for what these currently are.\n\n### Running the daemon with the right port\n\n**ipfs daemon**\n\nTo make `ipfs-cluster-service` work, you need to have a `ipfs` local daemon running. It needs to be open on the right port. `5001` is the default, and is used in the examples below, but it can be set to whatever you need.\n\n```\n# Show the ipfs config API port to check it is correct\n\u003e ipfs config Addresses.API\n/ip4/127.0.0.1/tcp/5001\n# Set it if it does not match the above output\n\u003e ipfs config Addresses.API /ip4/127.0.0.1/tcp/5001\n# Restart the daemon after changing the config\n\n# Run the daemon\n\u003e ipfs daemon\n```\n\n**ipfs-cluster-service daemon**\n\nTo interact with the API, you need to have a daemon running. It needs to be open on the right port. `9094` is the default, and is used in the examples below, but it can be set to whatever you need. You can setup `ipfs-cluster-service` by following [**this installation guide**](https://github.com/ipfs/ipfs-cluster#install). \n\nAfter installing run the daemon.\n\n```\n# Run the daemon\n\u003e ipfs-cluster-service daemon\n```\n\n### Importing the module and usage\n\n```javascript\nconst ipfsCluster = require('ipfs-cluster-api')\n\n// connect to ipfs daemon API server\nconst cluster = ipfsCluster('localhost', '9094', { protocol: 'http' }) // leaving out the arguments will default to these values\n\n// or connect with multiaddr\nconst cluster = ipfsCluster('/ip4/127.0.0.1/tcp/9094')\n\n// or using options\nconst cluster = ipfsCluster({ host: 'localhost', port: '9094', protocol: 'http' })\n\n// or specifying a specific API path\nconst cluster = ipfsCluster({ host: '1.1.1.1', port: '80', 'api-path': '/some/api/path' })\n```\n\n### In a web browser\n\n#### **through Browserify**\nSame as in Node.js, you just have to [browserify](http://browserify.org/) to bundle the code before serving it.\n \u003e Note: The code uses `es6`, so you have to use [babel](https://babeljs.io/) to convert the code into `es5` before using `browserify`. \n\n#### **through webpack**\nSame as in Node.js, you just have to [webpack](https://webpack.js.org/) to bundle the the code before serving it.\n \u003e Note: The code uses `es6`, so you have to use [babel](https://babeljs.io/) to convert the code into `es5` before using `webpack`.\n\n#### **from CDN**\n\nInstead of a local installation (and browserification) you may request a remote copy of IPFS API from unpkg CDN.\n\nTo always request the latest version, use the following:\n```html\n\u003c!-- loading the minified version --\u003e\n\u003cscript src=\"https://unpkg.com/ipfs-cluster-api/dist/src/index.min.js\"\u003e\u003c/script\u003e\n\u003c!-- loading the human-readable (not minified) version --\u003e\n\u003cscript src=\"https://unpkg.com/ipfs-cluster-api/dist/src/index.js\"\u003e\u003c/script\u003e\n```\n\nCDN-based IPFS Cluster API provides the `IpfsClusterAPI` constructor as a method of the global `window` object. Example:\n\n```javascript\n// connect to ipfs daemon API server\nconst cluster = IpfsClusterAPI('localhost', '9094', { protocol: 'http' }) // leaving out the arguments will default to these values\n\n// or connect with multiaddr\nconst cluster = IpfsClusterAPI('/ip4/127.0.0.1/tcp/9094')\n\n// or using options\nconst cluster = IpfsClusterAPI({ host: 'localhost', port: '9094', protocol: 'http' })\n\n// or specifying a specific API path\nconst cluster = IpfsClusterAPI({ host: '1.1.1.1', port: '80', 'api-path': '/some/api/path' })\n```\n\nIf you omit the host and port, the client will parse `window.host`, and use this information. This also works, and can be useful if you want to write apps that can be run from multiple different gateways:\n\n```javascript\nconst cluster = window.IpfsClusterAPI()\n```\n\n### **Custom Headers**\n\nIf you wish to send custom headers with each request made by this library, for example, the Authorization header. You can use the config to do so:\n\n```javascript\nconst cluster = ipfsCluster({\n  host: 'localhost',\n  port: 9094,\n  protocol: 'http',\n  headers: {\n    authorization: 'Basic ' + TOKEN\n  }\n})\n```\n\n\n## Usage\n\n### API\n\nThe API is currently a work-in-progress. The exposed methods are designed\nto be similar to `ipfs-cluster-ctl` provided in [`ipfs/ipfs-cluster`](https://github.com/ipfs/ipfs-cluster).\n\n-\t[`add`](#adding-\u0026-pinning-data-to-cluster)\n\t-\t[`cluster.add(data, [options], [callback])`](#add)\n-\t[`peers`](#peer-management)\n\t-\t[`cluster.peers.ls([callback])`](#peersls)\n\t-\t[`cluster.peers.rm(peerid, [callback])`](#peersremove)\n-\t[`pin`](#pins-management)\n\t-\t[`cluster.pin.ls([options], [callback])`](#pinls)\n\t-\t[`cluster.pin.add(cid, [options], [callback])`](#pinadd)\n\t-\t[`cluster.pin.rm(cid, [callback])`](#pinremove)\n-\t[`health`](#health)\n\t- [`cluster.health.graph([callback])`](#graph)\n\t- [`cluster.health.metrics(type, [callback])`](#metrics)\n-\t[`miscellaneous`](#node-management)\n\t-\t[`cluster.id([callback])`](#id)\n\t-\t[`cluster.version([callback])`](#version)\n\t- [`cluster.status([cid], [options], [callback])`](#status)\n\t-\t[`cluster.sync([cid], [options], [callback])`](#sync)\n\t-\t[`cluster.recover([cid], [options], [callback])`](#recover)\n\n\n### Adding \u0026 pinning data to cluster\n#### **`add`**\n\u003e Add and pin data to the cluster\n\nAdd allows to add and replicate content to several ipfs daemons, performing a Cluster Pin operation on success. It takes elements from local paths as well as from web URLs (accessed with a GET request).\n\nCluster Add is equivalent to \"ipfs add\" in terms of DAG building, and supports the same options for adjusting the chunker, the DAG layout etc. However, it will allocate the content and send it directly to the allocated peers (among which may not necessarily be the local ipfs daemon).\n\nOnce the adding process is finished, the content is fully added to all allocations and pinned in them. This makes cluster add slower than a local ipfs add, but the result is a fully replicated CID on completion. If you prefer faster adding, add directly to the local IPFS and trigger a cluster \"pin add\".\n\n\n**`cluster.add(data, [options], [callback])`**\n\nWhere  `data`  may be:\n\n-   a  [`Buffer instance`](https://www.npmjs.com/package/buffer)\n-   a  [`Readable Stream`](https://www.npmjs.com/package/readable-stream)\n-   a  [`Pull Stream`](https://www.npmjs.com/package/pull-stream)\n-   an array of objects, each of the form:\n```javascript\n{\n  path: '/tmp/myfile.txt', // The file path\n  content: \u003cdata\u003e // A Buffer, Readable Stream or Pull Stream with the contents of the file\n}\n```\nIf no `content` is passed, then the path is treated as an empty directory\n\n\n`options` is an optional object argument that might include the following keys:\n-\t`replication-min` (int, default: 0):\tSets the minimum replication factor for pinning this file\n-\t`replication-max` (int, default: 0):\tSets the maximum replication factor for pinning this: file\n-\t`name` (string, default: \"\"):\tSets a name for this pin\n-\t`shard` (bool, default: false)\t\n-\t`shard-size` (int, default: 0)\n-\t`recursive` (bool, default: false):\tAdd directory paths recursively\n-\t`layout` (string, default: false):\tDag layout to use for dag generation: balanced or trickle\n-\t`chunker` (string, default: \"size-262144\"):\t\t'size-[size]' or 'rabin-[min]-[avg]-[max]'\n-\t`raw-leaves` (bool, default: false):\tUse raw blocks for leaves\n-\t`hidden` (bool, default: false):\tInclude files that are hidden.  Only takes effect on recursive add\n-\t`wrap-with-directory` (bool, default: false):\tWrap a with a directory object\n-\t`progress` (bool, default: false)\t\n-\t`cid-version` (int, default: 0)\n-\t`hash` (string, default: \"sha2-256\"):\tHash function to use. Implies cid-version=1\n-\t`stream-channels` (bool, default: true)\t\n-\t`nocopy` (bool, default: false):\tAdd the URL using filestore. Implies raw-leaves\n\n\n`callback` must follow `function (err, res) {}` signature, where `err` is an error if the operation was not successful. If successful, `res` will return an object of following form:\n\n```javascript\n{\n  path: '/path/to/file/foo.txt',\n  hash: 'QmRG3FXAW76xD7ZrjCWk8FKVaTRPYdMtwzJHZ9gArzHK5f',\n  size: 2417\n}\n```\n\nIf no `callback` is passed, a promise is returned.\n\n### Example\n```javascript\ncluster.add(Buffer.from(\"vasa\"), (err, result) =\u003e {\n  err ? console.error(err) : console.log(result)\n})\n```\n### Peer management\n\u003e Lists, adds \u0026 removes peers from the cluster\n\n#### **`peers`**\n\n#### **`peers.ls`**\n\u003e Lists the peers in the cluster\n\t\nThis command tells IPFS Cluster to no longer manage a CID. This will trigger unpinning operations in all the IPFS nodes holding the content.\n\nWhen the request has succeeded, the command returns the status of the CID in the cluster. The CID should disappear from the list offered by \"pin ls\", although unpinning operations in the cluster may take longer or fail.\t\n\n**`cluster.peers.ls([callback])`**\n\t\n`callback` must follow `function (err, res) {}` signature, where `err` is an error if the operation was not successful. If successful, `res` returns a information abount the connected peers in the following form:\n```json\n[ { \"id\": \"QmPq34QAMCFLNTXWtM3pc7qeQ2kneuCgLZjSVywWoEumRn\",\n\t\"addresses\":\n\t\t[ \"/p2p-circuit/ipfs/QmPq34QAMCFLNTXWtM3pc7qeQ2kneuCgLZjSVywWoEumRn\",\n\t\t\t\"/ip4/127.0.0.1/tcp/9096/ipfs/QmPq34QAMCFLNTXWtM3pc7qeQ2kneuCgLZjSVywWoEumRn\",\n\t\t\t\"/ip4/10.184.9.134/tcp/9096/ipfs/QmPq34QAMCFLNTXWtM3pc7qeQ2kneuCgLZjSVywWoEumRn\",\n\t\t\t\"/ip4/172.17.0.1/tcp/9096/ipfs/QmPq34QAMCFLNTXWtM3pc7qeQ2kneuCgLZjSVywWoEumRn\",\n\t\t\t\"/ip4/172.18.0.1/tcp/9096/ipfs/QmPq34QAMCFLNTXWtM3pc7qeQ2kneuCgLZjSVywWoEumRn\" ],\n\t\"cluster_peers\": [ \"QmPq34QAMCFLNTXWtM3pc7qeQ2kneuCgLZjSVywWoEumRn\" ],\n\t\"cluster_peers_addresses\": null,\n\t\"version\": \"0.10.1\",\n\t\"commit\": \"\",\n\t\"rpc_protocol_version\": \"/ipfscluster/0.10/rpc\",\n\t\"error\": \"\",\n\t\"ipfs\":\n\t\t{ \"id\": \"QmdKAFhAAnc6U3ik6XfEDVKEsok7TnQ1yeyXmnnvGFmBhx\",\n\t\t\t\"addresses\": [/*Array*/],\n\t\t\t\"error\": \"\" },\n\t\"peername\": \"jarvis\" } ]\n```\n\n### Example\n```javascript\ncluster.peers.ls((err, peers) =\u003e {\n\terr ? console.error(err) : console.log(peers)\n})\n```\n\n#### **`peers.remove`**\n\u003e Removes peer from the cluster\n\nThis command removes a peer from the cluster. If the peer is online, it will automatically shut down. All other cluster peers should be online for the operation to succeed, otherwise some nodes may be left with an outdated list of cluster peers.\n\t\n**`cluster.peers.rm(peerid, [callback])`**\n\nWhere `peerid` is the `id` of the peer to be removed.\n\t\n`callback` must follow `function (err, res) {}` signature, where `err` is an error if the operation was not successful.\n\nIf no `callback` is passed, a promise is returned.\n\n### Example\n```javascript\ncluster.peers.rm(\"QmdKAFhAAnc6U3ik6XfEDVKEsok7TnQ1yeyXmnnvGFmBhx\", (err) =\u003e {\n\terr ? console.error(err) : console.log(\"peer removed\") \n})\n```\n\n### Pins management\n\u003e Lists, adds \u0026 removes pins from the pinlist of the cluster\n\n#### **`pin`**\n\n#### **`pin.ls`**\n\u003e Lists the pins in the pinlist\n\nThis command will list the CIDs which are tracked by IPFS Cluster and to which peers they are currently allocated. This list does not include any monitoring information about the IPFS status of the CIDs, it merely represents the list of pins which are part of the shared state of the cluster. For IPFS-status information about the pins, use \"status\".\n\t\n**`cluster.pin.ls([options], [callback])`**    \n\n`options` is an optional object argument that might include the following keys:\n* `filter`: (default: `pin`)  The filter only takes effect when listing all pins. The possible values are:\n\n\t- all\n\t- pin\n\t- meta-pin\n\t- clusterdag-pin\n\t- shard-pin\n\n`callback` must follow `function (err, pins) {}` signature, where `err` is an error if the operation was not successful. If successful, `pins` returns the list of pins.\n\nIf no `callback` is passed, a promise is returned.\n\n### Example\n\t\n```javascript\ncluster.pin.ls({filter: 'all'}, (err, pins) =\u003e {\n\terr ? console.error(err) : console.log(pins)\n})\n```\n\n\t  \n\n\t  \n\n#### **`pin.add`**\n\u003e Adds a pin to the cluster\n\t\nThis command tells IPFS Cluster to start managing a CID. Depending on the pinning strategy, this will trigger IPFS pin requests. The CID will become part of the Cluster's state and will tracked from this point.\n\nWhen the request has succeeded, the command returns the status of the CID in the cluster and should be part of the list offered by \"pin ls\".\n\nAn optional replication factor can be provided: -1 means \"pin everywhere\" and 0 means use cluster's default setting. Positive values indicate how many peers should pin this content.\n\nAn optional allocations argument can be provided, allocations should be a comma-separated list of peer IDs on which we want to pin. Peers in allocations are prioritized over automatically-determined ones, but replication factors would stil be respected.\n\t\n**`cluster.pin.add(cid, [options], [callback])`**\n\nWhere `cid` is the [CID](https://docs.ipfs.io/guides/concepts/cid/)  of the data to be pinned.\n\n`options` is an optional object argument that might include the following keys:\n-\t`replication-min`\t(int, default: 0):\tSets the minimum replication factor for this pin\t\n-\t`replication-max`\t(int, default: 0):\tSets the maximum replication factor for this pin\n-\t`replication`\t(int, default: 0):\tSets a custom replication factor (overrides `replication-min` and `replication-max`)\n-\t`name`\t(int, default: \"\"):\tSets a name for this pin\n-\t`user-allocations`: (string array): Optional comma-separated list of peer IDs where data will be pinned\n-\t`shard_size`\t(int, default: 0)\n\n`callback` must follow `function (err) {}` signature, where `err` is an error if the operation was not successful.\n\nIf no `callback` is passed, a promise is returned.\n\n### Example\n```javascript\ncluster.pin.add(CID, (err) =\u003e {\n\terr ? console.error(err) : console.log('pin added')\n})\n```\n\n   \n\n#### **`pin.remove`**\n\u003e Removes a pin from the pinlist\n\nThis command tells IPFS Cluster to no longer manage a CID. This will trigger unpinning operations in all the IPFS nodes holding the content.\n\nWhen the request has succeeded, the command returns the status of the CID in the cluster. The CID should disappear from the list offered by \"pin ls\", although unpinning operations in the cluster may take longer or fail.\n\n\t\n\t\n**`cluster.pin.rm(cid, [callback])`**\n\nWhere `cid` is the [CID](https://docs.ipfs.io/guides/concepts/cid/) of the data to be unpinned.\n\n`callback` must follow `function (err) {}` signature, where `err` is an error if the operation was not successful.\n\nIf no `callback` is passed, a promise is returned.\n\n### Example\n```javascript\nconst CID = \"QmU4xZd9Yj7EzRj5ntw6AJ1VkbWNe1jXRM56KoRLkTxKch\"\n\ncluster.pin.rm(CID, (err) =\u003e {\n\terr ? console.error(err) : console.log(`${CID} unpinned`)\n})\n```\n\n\n\n#### Node management\n#### **`id`**\n\u003e Gets the connected peer's name, address info\n\nThis command displays information about the peer that the tool is contacting.\n\n**`cluster.id([callback])`**\n\n`callback` must follow `function (err, id) {}` signature, where `err` is an error if the operation was not successful. If successful, `id` returns the information about the peer that the tool is contacting.\n\nIf no `callback` is passed, a promise is returned.\n\n### Example\n\n```javascript\ncluster.id((err, id) =\u003e {\n\terr ? console.error(err) : console.log(id)\n})\n```\n\n#### **`version`**\n\u003e Gets the current version of IPFS Cluster version\n\nThis command retrieves the IPFS Cluster version and can be used\nto check that it matches the CLI version \n\n**`cluster.version([callback])`**\n\n`callback` must follow `function (err, version) {}` signature, where `err` is an error if the operation was not successful. If successful, `version` will return the IPFS Cluster version.\n\nIf no `callback` is passed, a promise is returned.\n\n### Example\n```javascript\ncluster.version((err, version) =\u003e {\n\terr ? console.error(err) : console.log(version)\n})\n```\n\n#### **`health`**\n\n#### **`graph`**\n\u003e Lists the health graph of the cluster\n\nThis command queries all connected cluster peers and their ipfs peers to generate a graph of the connections.  Output is a dot file encoding the cluster's connection state.\n\n*  **`cluster.health.graph([callback])`**\n\n`callback` must follow `function (err, graph) {}` signature, where `err` is an error if the operation was not successful. If successful, `graph` returns the cluster's current state.\n\nIf no `callback` is passed, a promise is returned.\n\n#### Example\n\n```javascript\ncluster.health.graph((err, health) =\u003e {\n\terr ? console.error(err) : console.log(health)\n})\n```\n\n#### **`metrics`**\n\u003e Lists the health metrics of the cluster\n\nThis commands displays the latest valid metrics of the given type logged by this peer for all current cluster peers.\n\n* **`cluster.health.metrics(type, [callback])`**\n\n`type` is the type of the monitoring desired(`freespace` OR `ping`)\n\n`callback` must follow `function (err, metrics) {}` signature, where `err` is an error if the operation was not successful. If successful, `metrics` returns the desired metrics.\n\nIf no `callback` is passed, a promise is returned.\n\n### Example\n\n```javascript\ncluster.health.metrics('freespace', (err, metrics) =\u003e {\n\terr ? console.error(err) : console.log(metrics)\n})\n```\n\n####\t**`status`**\n\u003e Retrieves the status of the CIDs tracked by IPFS Cluster\n\nThis command retrieves the status of the CIDs tracked by IPFS Cluster, including which member is pinning them and any errors. If a CID is provided, the status will be only fetched for a single\nitem. Metadata CIDs are included in the status response\n\nThe status of a CID may not be accurate. A manual sync can be triggered with \"sync\".\n\nWhen the `local` option is set, it will only fetch the status from the contacted cluster peer. By default, status will be fetched from all peers.\n\nWhen the `filter` option is set, it will only fetch the peer information where status of the pin matches at least one of the filter values.\n\n**`cluster.status([cid], [options], [callback])`**\n\nWhere `cid` is the [CID](https://docs.ipfs.io/guides/concepts/cid/) of the data for which we need the status.\n\n`options` is an optional object argument that might include the following keys:\n* `filter`(string): list of filters\n  - error\n  - cluster_error\n  - pin_error\n  - pin_queued\n  - pinned\n  - pinning\n  - queued\n  - remote\n  - unpin_error\n  - unpin_queued\n  - unpinned\n  - unpinning\n  \n* `local`(boolean): if set `true`, runs operation only on the contacted peer\n\n`callback` must follow `function (err, res) {}` signature, where `err` is an error if the operation was not successful. If successful `res` returns the status of the passed `cid` \n\nIf no `callback` is passed, a promise is returned.\n\n### Example\n```javascript\nconst CID = \"QmU4xZd9Yj7EzRj5ntw6AJ1VkbWNe1jXRM56KoRLkTxKch\"\n\ncluster.status(CID, { filter:  'pinned', local:  true }, (err, res) =\u003e {\n\terr ? console.error(err) : console.log(res)\n})\n```\n\n####\t**`sync`**\n\u003e Syncs the pinset/CID across all the peers in the cluster\n\nThis command asks Cluster peers to verify that the current status of tracked CIDs is accurate by triggering queries to the IPFS daemons that pin them. If a CID is provided, the sync and recover operations will be limited to that single item.\n\nUnless providing a specific CID, the command will output only items which have changed status because of the sync or are in error state in some node, therefore, the output should be empty if no operations were performed.\n\nCIDs in error state may be manually recovered with \"recover\".\n\nWhen the `local` option is passed, it will only trigger sync operations on the contacted peer. By default, all peers will sync.\n\n**`cluster.sync([cid], [options], [callback])`**\n\nWhere `cid` is the [CID](https://docs.ipfs.io/guides/concepts/cid/) of the data to be synced.\n\n`options` is an optional object argument that might include the following keys:\n* `local`(boolean): if set `true`, runs operation only on the contacted peer\n\n`callback` must follow `function (err) {}` signature, where `err` is an error if the operation was not successful.\n\nIf no `callback` is passed, a promise is returned.\n\n### Example\n\n```javascript\nconst CID = \"QmU4xZd9Yj7EzRj5ntw6AJ1VkbWNe1jXRM56KoRLkTxKch\"\n\ncluster.sync(CID, { local:  true }, (err) =\u003e {\n\terr ? console.error(err) : console.log(`${CID} synced`)\n})\n```\n\n####\t**`recover`**\n\u003e re-track or re-forget CIDs in error state\n\nThis command asks Cluster peers to re-track or re-forget CIDs in error state, usually because the IPFS pin or unpin operation has failed.\n\nThe command will wait for any operations to succeed and will return the status of the item upon completion. Note that, when running on the full sets of tracked CIDs (without argument), it may take a considerably long time.\n\nWhen the `local` option is set, it will only trigger recover operations on the contacted peer (as opposed to on every peer).\n\nFor now, ONLY requests with parameter `local=true` are supported\n\n\n**`cluster.recover([cid], [options], [callback])`**\n\nWhere `cid` is the [CID](https://docs.ipfs.io/guides/concepts/cid/) of the data to be recovered.\n\n`options` is an optional object argument that might include the following keys:\n* `local`(boolean, default: true): if set `true` it will only trigger recover\noperations on the contacted peer\n\n`callback` must follow `function (err) {}` signature, where `err` is an error if the operation was not successful.\n\nIf no `callback` is passed, a promise is returned.\n\n### Example\n```javascript\nconst CID = \"QmU4xZd9Yj7EzRj5ntw6AJ1VkbWNe1jXRM56KoRLkTxKch\"\n\ncluster.recover(CID, { local:  true }, (err) =\u003e {\n\terr ? console.error(err) : console.log(`${CID} recovered`)\n})\n```\n\n## Development\n\n### Testing\nWe run tests by executing `npm test` in a terminal window. This will run Node.js tests.\n\n## Contribute\n\nThe `ipfs-cluster-api` is a work in progress. As such, there's a few things you can do right now to help out:\n\n- **[Check out the existing issues](https://github.com/cluster-labs/ipfs-cluster-api/issues)**!\n- **Perform code reviews**. More eyes will help \n\t- speed the project along \n\t- ensure quality and\n\t- reduce possible future bugs.\n- **Add tests**. There can never be enough tests.\n\nYou can also checkout our **[other projects](https://github.com/cluster-labs)**\n\nIt's recommended to follow the [Contribution Guidelines](https://github.com/ipfs/community/blob/master/CONTRIBUTING_JS.md).\n\n## Historical Context\n\nThis module started as a direct mapping from the Go `ipfs-cluster-ctl` to a JavaScript implementation.\n\n## License\n\n[MIT](LICENSE)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fipfs-cluster%2Fjs-cluster-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fipfs-cluster%2Fjs-cluster-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fipfs-cluster%2Fjs-cluster-client/lists"}