https://github.com/multiformats/js-cid-tool
A module and command line tool for converting, formatting and discovering properties of CIDs
https://github.com/multiformats/js-cid-tool
Last synced: about 1 year ago
JSON representation
A module and command line tool for converting, formatting and discovering properties of CIDs
- Host: GitHub
- URL: https://github.com/multiformats/js-cid-tool
- Owner: multiformats
- License: mit
- Created: 2018-09-12T15:59:09.000Z (almost 8 years ago)
- Default Branch: master
- Last Pushed: 2021-04-08T11:25:43.000Z (about 5 years ago)
- Last Synced: 2024-11-08T06:05:35.529Z (over 1 year ago)
- Language: JavaScript
- Homepage:
- Size: 1.29 MB
- Stars: 8
- Watchers: 18
- Forks: 8
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# CID Tool
[](https://travis-ci.org/multiformats/js-cid-tool) [](https://david-dm.org/multiformats/js-cid-tool) [](https://standardjs.com)
> A module and command line tool for converting, formatting and discovering properties of CIDs
## Install
* Install Node.js 8+
```sh
npm install -g cid-tool # for command line usage
# or
npm install cid-tool # for programmatic usage
```
## Usage
### CLI
```console
$ cid --help
cid
Commands:
cid base32 [cids...] Convert CIDs to base 32 CID version 1.
cid bases List available multibase encoding names.
cid codecs List available CID codec names.
cid format [cids...] Format and convert a CID in various useful ways.
cid hashes List available multihash hashing algorithm names.
Options:
--version Show version number [boolean]
--help Show help [boolean]
```
**Note**: help is also available for each command e.g. `cid format --help`
#### Example
```console
$ cid base32 QmdnJHe9XKk6atRSqAq1SdCu12MMSKxSPC93EWngEDoypj
bafybeihfofifyyrirgqad3de7nkyldbleo3awwv4ghbba4ipjqthk2nhaa
$ cid bases --prefix
0 base1
1 base2
7 base8
9 base10
f base16
b base32
c base32pad
v base32hex
t base32hexpad
h base32z
Z base58flickr
z base58btc
m base64
M base64pad
u base64url
U base64urlpad
$ cid codecs
raw
base1
base2
base8
base10
cbor
protobuf
# ...
$ cid format mAXASIOVxUFxiKImgAexk+1WFjCsjtgtavDHCEHEPTCZ1aacA -f "%b CIDv%V %h"
base64 CIDv1 sha2-256
$ cid hashes
id
sha1
sha2-256
sha2-512
dbl-sha2-256
sha3-224
sha3-256
sha3-384
sha3-512
shake-128
shake-256
keccak-224
# ...
```
### Module
```js
const CIDTool = require('cid-tool')
// Then see API docs below...
```
## API
### `CIDTool.base32(cid)`
Convert the passed CID to base 32 CID version 1.
#### Parameters
| Name | Type | Description |
|------|------|-------------|
| cid | [`CID`](https://github.com/ipld/js-cid/)\|`String`\|`Uint8Array` | CID to convert. |
#### Returns
| Type | Description |
|------|-------------|
| `String` | Base 32 encoded version 1 CID |
#### Example
```js
> CIDTool.base32('QmdnJHe9XKk6atRSqAq1SdCu12MMSKxSPC93EWngEDoypj')
'bafybeihfofifyyrirgqad3de7nkyldbleo3awwv4ghbba4ipjqthk2nhaa'
```
### `CIDTool.bases()`
List available [multibase encoding name and code pairs](https://github.com/multiformats/multibase/blob/master/multibase.csv).
#### Returns
| Type | Description |
|------|-------------|
| `Array<{name, code}>` | Multibase encoding name and code pairs |
#### Example
```js
> CIDTool.bases()
[ { name: 'base1', code: '0' },
{ name: 'base2', code: '1' },
{ name: 'base8', code: '7' },
{ name: 'base10', code: '9' },
{ name: 'base16', code: 'f' },
{ name: 'base32', code: 'b' },
{ name: 'base32pad', code: 'c' },
{ name: 'base32hex', code: 'v' },
{ name: 'base32hexpad', code: 't' },
{ name: 'base32z', code: 'h' },
{ name: 'base58flickr', code: 'Z' },
{ name: 'base58btc', code: 'z' },
{ name: 'base64', code: 'm' },
{ name: 'base64pad', code: 'M' },
{ name: 'base64url', code: 'u' },
{ name: 'base64urlpad', code: 'U' } ]
```
### `CIDTool.codecs()`
List available [CID codec name and code pairs](https://github.com/multiformats/multicodec/blob/master/table.csv).
#### Returns
| Type | Description |
|------|-------------|
| `Array<{name, code}>` | CID codec name and code pairs |
#### Example
```js
> CIDTool.codecs()
[ { name: 'raw', code: 85 },
{ name: 'base1', code: 1 },
{ name: 'base2', code: 0 },
{ name: 'base8', code: 7 },
{ name: 'base10', code: 9 },
{ name: 'cbor', code: 81 },
{ name: 'protobuf', code: 80 },
/* ... */ ]
```
### `CIDTool.format(cid, [options])`
Format and convert a CID in various useful ways.
#### Parameters
| Name | Type | Description |
|------|------|-------------|
| cid | [`CID`](https://github.com/ipld/js-cid/)\|`String`\|`Uint8Array` | CID to format |
| options | `Object` | (optional) options for formatting |
| options.format | `String` | Format string to use, default "%s" |
| options.base | `String` | Multibase name or code to use for output |
| options.cidVersion | `Number` | Convert the CID to the given version if possible |
Available format specifiers:
* %% literal %
* %b multibase name
* %B multibase code
* %v version string
* %V version number
* %c codec name
* %C codec code
* %h multihash name
* %H multihash code
* %L hash digest length
* %m multihash encoded in base %b (with multibase prefix)
* %M multihash encoded in base %b without multibase prefix
* %d hash digest encoded in base %b (with multibase prefix)
* %D hash digest encoded in base %b without multibase prefix
* %s cid string encoded in base %b (1)
* %S cid string encoded in base %b without multibase prefix
* %P cid prefix: %v-%c-%h-%L
(1) For CID version 0 the multibase must be base58btc and no prefix is used. For Cid version 1 the multibase prefix is included.
#### Returns
| Type | Description |
|------|-------------|
| `String` | Formatted string |
#### Example
```js
> CIDTool.format('QmUNLLsPACCz1vLxQVkXqqLX5R1X345qqfHbsf67hvA3Nn', { format: '%b-%v-%c-%h-%L' })
'base58btc-cidv0-dag-pb-sha2-256-32'
> CIDTool.format('QmUNLLsPACCz1vLxQVkXqqLX5R1X345qqfHbsf67hvA3Nn', { cidVersion: 1 })
'zdj7WbTaiJT1fgatdet9Ei9iDB5hdCxkbVyhyh8YTUnXMiwYi'
> CIDTool.format('zdj7WksYf5DNoDhTbjNZundK13TdEYo9sNaFWYZuKBM3fNszf', { base: 'base64' })
'mAXASIOVxUFxiKImgAexk+1WFjCsjtgtavDHCEHEPTCZ1aacA'
```
### `CIDTool.hashes()`
List available [multihash hashing algorithm name and code pairs](https://github.com/multiformats/multihash/blob/master/hashtable.csv).
#### Returns
| Type | Description |
|------|-------------|
| `Array<{name, code}>` | Multihash hashing algorithm name and code pairs |
#### Example
```js
> CIDTool.hashes()
[ { name: 'id', code: 0 },
{ name: 'sha1', code: 17 },
{ name: 'sha2-256', code: 18 },
{ name: 'sha2-512', code: 19 },
{ name: 'dbl-sha2-256', code: 86 },
{ name: 'sha3-224', code: 23 },
{ name: 'sha3-256', code: 22 },
/* ... */ ]
```
## Contribute
Feel free to join in. All welcome. Open an [issue](https://github.com/multiformats/cid-tool/issues)!
This repository falls under the IPFS [Code of Conduct](https://github.com/ipfs/community/blob/master/code-of-conduct.md).
### Want to hack on IPFS?
[](https://github.com/ipfs/community/blob/master/contributing.md)
## License
Copyright (c) Protocol Labs, Inc. under the **MIT License**. See [LICENSE](./LICENSE) for details.