CID Tool

A module and command line tool for converting, formatting and discovering properties of CIDs

Install

• Install Node.js 8+

npm install -g cid-tool # for command line usage
# or
npm install cid-tool    # for programmatic usage

Usage

CLI

$ cid --help
cid <command>

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

$ 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

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|String|Uint8Array | CID to convert. |

Returns

| Type | Description | |------|-------------| | String | Base 32 encoded version 1 CID |

Example

> CIDTool.base32('QmdnJHe9XKk6atRSqAq1SdCu12MMSKxSPC93EWngEDoypj')
'bafybeihfofifyyrirgqad3de7nkyldbleo3awwv4ghbba4ipjqthk2nhaa'

CIDTool.bases()

List available multibase encoding name and code pairs.

Returns

| Type | Description | |------|-------------| | Array<{name<String>, code<String>}> | Multibase encoding name and code pairs |

Example

> 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.

Returns

| Type | Description | |------|-------------| | Array<{name<String>, code<Number>}> | CID codec name and code pairs |

Example

> 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|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

> 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.

Returns

| Type | Description | |------|-------------| | Array<{name<String>, code<Number>}> | Multihash hashing algorithm name and code pairs |

Example

> 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!

This repository falls under the IPFS Code of Conduct.

Want to hack on IPFS?

License

Copyright (c) Protocol Labs, Inc. under the MIT License. See LICENSE for details.