cid-tool

    3.0.0 • Public • Published

    CID Tool

    Build Status dependencies Status JavaScript Style Guide

    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.

    Install

    npm i cid-tool

    DownloadsWeekly Downloads

    3,073

    Version

    3.0.0

    License

    MIT

    Unpacked Size

    80.1 kB

    Total Files

    61

    Last publish

    Collaborators

    • achingbrain
    • alanshaw
    • hugomrdias