diff --git a/content/reference/api/cli.md b/content/reference/api/cli.md index be3f632..d201248 100644 --- a/content/reference/api/cli.md +++ b/content/reference/api/cli.md @@ -12,7 +12,9 @@ menu: **Note:** IPFS can run in either “online” (you have IPFS running separately as a daemon process) or “offline” mode, but some commands are only supported when online. For example `ipfs swarm peers` only works in online mode because you won’t be connected to a swarm at all if you’re offline. For more about running IPFS as a daemon, see [“going online” in the usage documentation]({{< relref "usage.md#going-online" >}}). -*Generated on 2018-04-09 13:54:54.079504* +This document is autogenerated from scripts/cli.sh. For issues and support, check out the docs repository on GitHub. + +*Generated on 2019-07-16 15:20:49, from go-ipfs 0.4.21.* - [ipfs](#ipfs) - [ipfs add](#ipfs-add) @@ -20,7 +22,6 @@ menu: - [ipfs bitswap ledger](#ipfs-bitswap-ledger) - [ipfs bitswap reprovide](#ipfs-bitswap-reprovide) - [ipfs bitswap stat](#ipfs-bitswap-stat) -- [ipfs bitswap unwant](#ipfs-bitswap-unwant) - [ipfs bitswap wantlist](#ipfs-bitswap-wantlist) - [ipfs block](#ipfs-block) - [ipfs block get](#ipfs-block-get) @@ -34,6 +35,12 @@ menu: - [ipfs bootstrap rm](#ipfs-bootstrap-rm) - [ipfs bootstrap rm all](#ipfs-bootstrap-rm-all) - [ipfs cat](#ipfs-cat) +- [ipfs cid](#ipfs-cid) +- [ipfs cid base32](#ipfs-cid-base32) +- [ipfs cid bases](#ipfs-cid-bases) +- [ipfs cid codecs](#ipfs-cid-codecs) +- [ipfs cid format](#ipfs-cid-format) +- [ipfs cid hashes](#ipfs-cid-hashes) - [ipfs commands](#ipfs-commands) - [ipfs config](#ipfs-config) - [ipfs config edit](#ipfs-config-edit) @@ -111,13 +118,12 @@ menu: - [ipfs object put](#ipfs-object-put) - [ipfs object stat](#ipfs-object-stat) - [ipfs p2p](#ipfs-p2p) -- [ipfs p2p listener](#ipfs-p2p-listener) -- [ipfs p2p listener close](#ipfs-p2p-listener-close) -- [ipfs p2p listener ls](#ipfs-p2p-listener-ls) -- [ipfs p2p listener open](#ipfs-p2p-listener-open) +- [ipfs p2p close](#ipfs-p2p-close) +- [ipfs p2p forward](#ipfs-p2p-forward) +- [ipfs p2p listen](#ipfs-p2p-listen) +- [ipfs p2p ls](#ipfs-p2p-ls) - [ipfs p2p stream](#ipfs-p2p-stream) - [ipfs p2p stream close](#ipfs-p2p-stream-close) -- [ipfs p2p stream dial](#ipfs-p2p-stream-dial) - [ipfs p2p stream ls](#ipfs-p2p-stream-ls) - [ipfs pin](#ipfs-pin) - [ipfs pin add](#ipfs-pin-add) @@ -159,28 +165,41 @@ menu: - [ipfs tar add](#ipfs-tar-add) - [ipfs tar cat](#ipfs-tar-cat) - [ipfs update](#ipfs-update) +- [ipfs urlstore](#ipfs-urlstore) +- [ipfs urlstore add](#ipfs-urlstore-add) - [ipfs version](#ipfs-version) +- [ipfs version deps](#ipfs-version-deps) ## ipfs ``` USAGE - ipfs - Global p2p merkle-dag filesystem. + ipfs - Global p2p merkle-dag filesystem. SYNOPSIS - ipfs [--config= | -c] [--debug= | -D] [--help=] [-h=] [--local= | -L] [--api=] ... + ipfs [--config= | -c] [--debug | -D] [--help] [-h] [--api=] [--offline] [--cid-base=] [--upgrade-cidv0-in-output] [--encoding= | --enc] [--timeout=] ... OPTIONS - -c, --config string - Path to the configuration file to use. - -D, --debug bool - Operate in debug mode. - --help bool - Show the full command help text. - -h bool - Show a short version of the command help text. - -L, --local bool - Run the command locally, instead of using the daemon. - --api string - Use a specific API instance (defaults to /ip4/127.0.0.1/tcp/5001). - --enc, --encoding string - The encoding type the output should be encoded with (json, xml, or text). Default: text. - --stream-channels bool - Stream channel output. - --timeout string - set a global timeout on the command. + -c, --config string - Path to the configuration file to use. + -D, --debug bool - Operate in debug mode. + --help bool - Show the full command help text. + -h bool - Show a short version of the command help + text. + -L, --local bool - Run the command locally, instead of using + the daemon. DEPRECATED: use --offline. + --offline bool - Run the command offline. + --api string - Use a specific API instance (defaults to + /ip4/127.0.0.1/tcp/5001). + --cid-base string - Multibase encoding used for version 1 + CIDs in output. + --upgrade-cidv0-in-output bool - Upgrade version 0 to version 1 CIDs in + output. + --enc, --encoding string - The encoding type the output should be + encoded with (json, xml, or text). + Default: text. + --stream-channels bool - Stream channel output. + --timeout string - Set a global timeout on the command. SUBCOMMANDS BASIC COMMANDS @@ -190,13 +209,13 @@ SUBCOMMANDS get Download IPFS objects ls List links from an object refs List hashes of links from an object - + DATA STRUCTURE COMMANDS block Interact with raw blocks in the datastore object Interact with raw dag nodes files Interact with objects as if they were a unix filesystem dag Interact with IPLD documents (experimental) - + ADVANCED COMMANDS daemon Start a long-running daemon process mount Mount an IPFS read-only mountpoint @@ -209,7 +228,7 @@ SUBCOMMANDS stats Various operational stats p2p Libp2p stream mounting filestore Manage the filestore (experimental) - + NETWORK COMMANDS id Show info about IPFS peers bootstrap Add or remove bootstrap peers @@ -217,29 +236,33 @@ SUBCOMMANDS dht Query the DHT for values or peers ping Measure the latency of a connection diag Print diagnostics - + TOOL COMMANDS config Manage configuration version Show ipfs version information update Download and apply go-ipfs updates commands List all available commands - + cid Convert and discover properties of CIDs + log Manage and show logs of running daemon + Use 'ipfs --help' to learn more about each command. - + ipfs uses a repository in the local file system. By default, the repo is located at ~/.ipfs. To change the repo location, set the $IPFS_PATH environment variable: - + export IPFS_PATH=/path/to/ipfsrepo - + EXIT STATUS - + The CLI will exit with one of the following values: - + 0 Successful execution. 1 Failed executions. - Use 'ipfs --help' for more information about each command. + For more information about each command, use: + 'ipfs --help' + ``` ## ipfs add @@ -249,7 +272,13 @@ USAGE ipfs add ... - Add a file or directory to ipfs. SYNOPSIS - ipfs add [--recursive | -r] [--quiet | -q] [--quieter | -Q] [--silent] [--progress | -p] [--trickle | -t] [--only-hash | -n] [--wrap-with-directory | -w] [--hidden | -H] [--chunker= | -s] [--pin=false] [--raw-leaves] [--nocopy] [--fscache] [--cid-version=] [--hash=] [--] ... + ipfs add [--recursive | -r] [--dereference-args] [--stdin-name=] + [--hidden | -H] [--quiet | -q] [--quieter | -Q] [--silent] + [--progress | -p] [--trickle | -t] [--only-hash | -n] + [--wrap-with-directory | -w] [--chunker= | -s] [--pin=false] + [--raw-leaves] [--nocopy] [--fscache] [--cid-version=] + [--hash=] [--inline] [--inline-limit=] [--] + ... ARGUMENTS @@ -257,60 +286,83 @@ ARGUMENTS OPTIONS - -r, --recursive bool - Add directory paths recursively. Default: false. - -q, --quiet bool - Write minimal output. - -Q, --quieter bool - Write only final hash. - --silent bool - Write no output. - -p, --progress bool - Stream progress data. - -t, --trickle bool - Use trickle-dag format for dag generation. - -n, --only-hash bool - Only chunk and hash - do not write to disk. - -w, --wrap-with-directory bool - Wrap files with a directory object. - -H, --hidden bool - Include files that are hidden. Only takes effect on recursive add. - -s, --chunker string - Chunking algorithm, size-[bytes] or rabin-[min]-[avg]-[max]. Default: size-262144. - --pin bool - Pin this object when adding. Default: true. - --raw-leaves bool - Use raw blocks for leaf nodes. (experimental). - --nocopy bool - Add the file using filestore. Implies raw-leaves. (experimental). - --fscache bool - Check the filestore for pre-existing blocks. (experimental). - --cid-version int - CID version. Defaults to 0 unless an option that depends on CIDv1 is passed. (experimental). - --hash string - Hash function to use. Implies CIDv1 if not sha2-256. (experimental). Default: sha2-256. + -r, --recursive bool - Add directory paths recursively. + --dereference-args bool - Symlinks supplied in arguments are + dereferenced. + --stdin-name string - Assign a name if the file source is stdin. + -H, --hidden bool - Include files that are hidden. Only takes + effect on recursive add. + -q, --quiet bool - Write minimal output. + -Q, --quieter bool - Write only final hash. + --silent bool - Write no output. + -p, --progress bool - Stream progress data. + -t, --trickle bool - Use trickle-dag format for dag generation. + -n, --only-hash bool - Only chunk and hash - do not write to + disk. + -w, --wrap-with-directory bool - Wrap files with a directory object. + -s, --chunker string - Chunking algorithm, size-[bytes] or + rabin-[min]-[avg]-[max]. Default: + size-262144. + --pin bool - Pin this object when adding. Default: + true. + --raw-leaves bool - Use raw blocks for leaf nodes. + (experimental). + --nocopy bool - Add the file using filestore. Implies + raw-leaves. (experimental). + --fscache bool - Check the filestore for pre-existing + blocks. (experimental). + --cid-version int - CID version. Defaults to 0 unless an + option that depends on CIDv1 is passed. + (experimental). + --hash string - Hash function to use. Implies CIDv1 if + not sha2-256. (experimental). Default: + sha2-256. + --inline bool - Inline small blocks into CIDs. + (experimental). + --inline-limit int - Maximum block size to inline. + (experimental). Default: 32. DESCRIPTION Adds contents of to ipfs. Use -r to add directories. Note that directories are added recursively, to form the ipfs MerkleDAG. - + The wrap option, '-w', wraps the file (or files, if using the recursive option) in a directory. This directory contains only the files which have been added, and means that the file retains its filename. For example: - + > ipfs add example.jpg added QmbFMke1KXqnYyBBWxB74N4c5SBnJMVAiMNRcGu6x1AwQH example.jpg > ipfs add example.jpg -w added QmbFMke1KXqnYyBBWxB74N4c5SBnJMVAiMNRcGu6x1AwQH example.jpg added QmaG4FuMqEBnQNn3C8XJ5bpW8kLs7zq2ZXgHptJHbKDDVx - + You can now refer to the added file in a gateway, like so: - + /ipfs/QmaG4FuMqEBnQNn3C8XJ5bpW8kLs7zq2ZXgHptJHbKDDVx/example.jpg - + The chunker option, '-s', specifies the chunking strategy that dictates how to break files into blocks. Blocks with same content can - be deduplicated. The default is a fixed block size of + be deduplicated. Different chunking strategies will produce different + hashes for the same file. The default is a fixed block size of 256 * 1024 bytes, 'size-262144'. Alternatively, you can use the - rabin chunker for content defined chunking by specifying - rabin-[min]-[avg]-[max] (where min/avg/max refer to the resulting - chunk sizes). Using other chunking strategies will produce - different hashes for the same file. - + Rabin fingerprint chunker for content defined chunking by specifying + rabin-[min]-[avg]-[max] (where min/avg/max refer to the desired + chunk sizes in bytes), e.g. 'rabin-262144-524288-1048576'. + + The following examples use very small byte sizes to demonstrate the + properties of the different chunkers on a small file. You'll likely + want to use a 1024 times larger chunk sizes for most files. + > ipfs add --chunker=size-2048 ipfs-logo.svg added QmafrLBfzRLV4XSH1XcaMMeaXEUhDJjmtDfsYU95TrWG87 ipfs-logo.svg > ipfs add --chunker=rabin-512-1024-2048 ipfs-logo.svg added Qmf1hDN65tR55Ubh2RN1FPxr69xq3giVBz1KApsresY8Gn ipfs-logo.svg - + You can now check what blocks have been created by: - + > ipfs object links QmafrLBfzRLV4XSH1XcaMMeaXEUhDJjmtDfsYU95TrWG87 QmY6yj1GsermExDXoosVE3aSPxdMNYr6aKuw3nA8LoWPRS 2059 Qmf7ZQeSxq2fJVJbCmgTrLLVN9tDR9Wy5k75DxQKuz5Gyt 1195 @@ -318,6 +370,8 @@ DESCRIPTION QmY6yj1GsermExDXoosVE3aSPxdMNYr6aKuw3nA8LoWPRS 2059 QmerURi9k4XzKCaaPbsK6BL5pMEjF7PGphjDvkkjDtsVf3 868 QmQB28iwSriSUSMqG2nXDTLtdPHgWb4rebBrU7Q1j4vxPv 338 + + ``` ## ipfs bitswap @@ -330,13 +384,15 @@ SYNOPSIS ipfs bitswap SUBCOMMANDS - ipfs bitswap ledger - Show the current ledger for a peer. - ipfs bitswap reprovide - Trigger reprovider. - ipfs bitswap stat - Show some diagnostic information on the bitswap agent. - ipfs bitswap unwant ... - Remove a given block from your wantlist. - ipfs bitswap wantlist - Show blocks currently on the wantlist. + ipfs bitswap ledger - Show the current ledger for a peer. + ipfs bitswap reprovide - Trigger reprovider. + ipfs bitswap stat - Show some diagnostic information on the bitswap + agent. + ipfs bitswap wantlist - Show blocks currently on the wantlist. + + For more information about each command, use: + 'ipfs bitswap --help' - Use 'ipfs bitswap --help' for more information about each command. ``` ## ipfs bitswap ledger @@ -357,6 +413,8 @@ DESCRIPTION The Bitswap decision engine tracks the number of bytes exchanged between IPFS nodes, and stores this information as a collection of ledgers. This command prints the ledger associated with a given peer. + + ``` ## ipfs bitswap reprovide @@ -371,6 +429,8 @@ SYNOPSIS DESCRIPTION Trigger reprovider to announce our data to network. + + ``` ## ipfs bitswap stat @@ -380,21 +440,14 @@ USAGE ipfs bitswap stat - Show some diagnostic information on the bitswap agent. SYNOPSIS - ipfs bitswap stat -``` - -## ipfs bitswap unwant + ipfs bitswap stat [--verbose | -v] [--human] -``` -USAGE - ipfs bitswap unwant ... - Remove a given block from your wantlist. +OPTIONS -SYNOPSIS - ipfs bitswap unwant [--] ... + -v, --verbose bool - Print extra information. + --human bool - Print sizes in human readable format (e.g., 1K 234M 2G). -ARGUMENTS - ... - Key(s) to remove from your wantlist. ``` ## ipfs bitswap wantlist @@ -408,11 +461,13 @@ SYNOPSIS OPTIONS - -p, --peer string - Specify which peer to show wantlist for. Default: self. + -p, --peer string - Specify which peer to show wantlist for. Default: self. DESCRIPTION Print out all blocks currently on the bitswap wantlist for the local peer. + + ``` ## ipfs block @@ -436,7 +491,9 @@ SUBCOMMANDS ipfs block rm ... - Remove IPFS block(s). ipfs block stat - Print information of a raw IPFS block. - Use 'ipfs block --help' for more information about each command. + For more information about each command, use: + 'ipfs block --help' + ``` ## ipfs block get @@ -456,6 +513,8 @@ DESCRIPTION 'ipfs block get' is a plumbing command for retrieving raw IPFS blocks. It outputs to stdout, and is a base58 encoded multihash. + + ``` ## ipfs block put @@ -465,7 +524,8 @@ USAGE ipfs block put - Store input as an IPFS block. SYNOPSIS - ipfs block put [--format= | -f] [--mhtype=] [--mhlen=] [--] + ipfs block put [--format= | -f] [--mhtype=] [--mhlen=] + [--pin] [--] ARGUMENTS @@ -473,14 +533,20 @@ ARGUMENTS OPTIONS - -f, --format string - cid format for blocks to be created with. Default: v0. - --mhtype string - multihash hash function. Default: sha2-256. - --mhlen int - multihash hash length. Default: -1. + -f, --format string - cid format for blocks to be created with. + --mhtype string - multihash hash function. Default: sha2-256. + --mhlen int - multihash hash length. Default: -1. + --pin bool - pin added blocks recursively. Default: false. DESCRIPTION 'ipfs block put' is a plumbing command for storing raw IPFS blocks. It reads from stdin, and is a base58 encoded multihash. + + By default CIDv0 is going to be generated. Setting 'mhtype' to anything other + than 'sha2-256' or format to anything other than 'v0' will result in CIDv1. + + ``` ## ipfs block rm @@ -498,13 +564,15 @@ ARGUMENTS OPTIONS - -f, --force bool - Ignore nonexistent blocks. - -q, --quiet bool - Write minimal output. + -f, --force bool - Ignore nonexistent blocks. + -q, --quiet bool - Write minimal output. DESCRIPTION 'ipfs block rm' is a plumbing command for removing raw ipfs blocks. - It takes a list of base58 encoded multihashs to remove. + It takes a list of base58 encoded multihashes to remove. + + ``` ## ipfs block stat @@ -524,9 +592,11 @@ DESCRIPTION 'ipfs block stat' is a plumbing command for retrieving information on raw IPFS blocks. It outputs the following to stdout: - + Key - the base58 encoded multihash Size - the size of the block in bytes + + ``` ## ipfs bootstrap @@ -541,9 +611,9 @@ SYNOPSIS DESCRIPTION Running 'ipfs bootstrap' with no arguments will run 'ipfs bootstrap list'. - + SECURITY WARNING: - + The bootstrap command manipulates the "bootstrap list", which contains the addresses of bootstrap nodes. These are the *trusted peers* from which to learn about other peers in the network. Only edit this list @@ -554,7 +624,9 @@ SUBCOMMANDS ipfs bootstrap list - Show peers in the bootstrap list. ipfs bootstrap rm []... - Remove peers from the bootstrap list. - Use 'ipfs bootstrap --help' for more information about each command. + For more information about each command, use: + 'ipfs bootstrap --help' + ``` ## ipfs bootstrap add @@ -568,19 +640,21 @@ SYNOPSIS ARGUMENTS - []... - A peer to add to the bootstrap list (in the format '/') + []... - A peer to add to the bootstrap list (in the format + '/') OPTIONS - --default bool - Add default bootstrap nodes. (Deprecated, use 'default' subcommand instead). + --default bool - Add default bootstrap nodes. (Deprecated, use 'default' + subcommand instead). DESCRIPTION Outputs a list of peers that were added (that weren't already in the bootstrap list). - + SECURITY WARNING: - + The bootstrap command manipulates the "bootstrap list", which contains the addresses of bootstrap nodes. These are the *trusted peers* from which to learn about other peers in the network. Only edit this list @@ -589,7 +663,9 @@ DESCRIPTION SUBCOMMANDS ipfs bootstrap add default - Add default peers to the bootstrap list. - Use 'ipfs bootstrap add --help' for more information about each command. + For more information about each command, use: + 'ipfs bootstrap add --help' + ``` ## ipfs bootstrap add default @@ -605,6 +681,8 @@ DESCRIPTION Outputs a list of peers that were added (that weren't already in the bootstrap list). + + ``` ## ipfs bootstrap list @@ -619,6 +697,8 @@ SYNOPSIS DESCRIPTION Peers are output in the format '/'. + + ``` ## ipfs bootstrap rm @@ -632,18 +712,19 @@ SYNOPSIS ARGUMENTS - []... - A peer to add to the bootstrap list (in the format '/') + []... - A peer to add to the bootstrap list (in the format + '/') OPTIONS - --all bool - Remove all bootstrap peers. (Deprecated, use 'all' subcommand). + --all bool - Remove all bootstrap peers. (Deprecated, use 'all' subcommand). DESCRIPTION Outputs the list of peers that were removed. - + SECURITY WARNING: - + The bootstrap command manipulates the "bootstrap list", which contains the addresses of bootstrap nodes. These are the *trusted peers* from which to learn about other peers in the network. Only edit this list @@ -652,7 +733,9 @@ DESCRIPTION SUBCOMMANDS ipfs bootstrap rm all - Remove all peers from the bootstrap list. - Use 'ipfs bootstrap rm --help' for more information about each command. + For more information about each command, use: + 'ipfs bootstrap rm --help' + ``` ## ipfs bootstrap rm all @@ -667,6 +750,8 @@ SYNOPSIS DESCRIPTION Outputs the list of peers that were removed. + + ``` ## ipfs cat @@ -684,12 +769,150 @@ ARGUMENTS OPTIONS - -o, --offset int - Byte offset to begin reading from. - -l, --length int - Maximum number of bytes to read. + -o, --offset int64 - Byte offset to begin reading from. + -l, --length int64 - Maximum number of bytes to read. DESCRIPTION Displays the data contained by an IPFS or IPNS object(s) at the given path. + + +``` + +## ipfs cid + +``` +USAGE + ipfs cid - Convert and discover properties of CIDs + +SYNOPSIS + ipfs cid + +SUBCOMMANDS + ipfs cid base32 ... - Convert CIDs to Base32 CID version 1. + ipfs cid bases - List available multibase encodings. + ipfs cid codecs - List available CID codecs. + ipfs cid format ... - Format and convert a CID in various useful ways. + ipfs cid hashes - List available multihashes. + + For more information about each command, use: + 'ipfs cid --help' + +``` + +## ipfs cid base32 + +``` +USAGE + ipfs cid base32 ... - Convert CIDs to Base32 CID version 1. + +SYNOPSIS + ipfs cid base32 [--] ... + +ARGUMENTS + + ... - Cids to convert. + + +``` + +## ipfs cid bases + +``` +USAGE + ipfs cid bases - List available multibase encodings. + +SYNOPSIS + ipfs cid bases [--prefix] [--numeric] + +OPTIONS + + --prefix bool - also include the single leter prefixes in addition to the + code. + --numeric bool - also include numeric codes. + + +``` + +## ipfs cid codecs + +``` +USAGE + ipfs cid codecs - List available CID codecs. + +SYNOPSIS + ipfs cid codecs [--numeric] + +OPTIONS + + --numeric bool - also include numeric codes. + + +``` + +## ipfs cid format + +``` +USAGE + ipfs cid format ... - Format and convert a CID in various useful ways. + +SYNOPSIS + ipfs cid format [-f=] [-v=] [-b=] [--] ... + +ARGUMENTS + + ... - Cids to format. + +OPTIONS + + -f string - Printf style format string. Default: %s. + -v string - CID version to convert to. + -b string - Multibase to display CID in. + +DESCRIPTION + + Format and converts 's in various useful ways. + + The optional format string is a printf style format string: + + %% 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. + + +``` + +## ipfs cid hashes + +``` +USAGE + ipfs cid hashes - List available multihashes. + +SYNOPSIS + ipfs cid hashes [--numeric] + +OPTIONS + + --numeric bool - also include numeric codes. + + ``` ## ipfs commands @@ -703,11 +926,13 @@ SYNOPSIS OPTIONS - -f, --flags bool - Show command flags. + -f, --flags bool - Show command flags. DESCRIPTION Lists all available commands (and subcommands) and exits. + + ``` ## ipfs config @@ -726,23 +951,23 @@ ARGUMENTS OPTIONS - --bool bool - Set a boolean value. - --json bool - Parse stringified JSON. + --bool bool - Set a boolean value. + --json bool - Parse stringified JSON. DESCRIPTION 'ipfs config' controls configuration variables. It works much like 'git config'. The configuration values are stored in a config file inside your IPFS repository. - + Examples: - + Get the value of the 'Datastore.Path' key: - + $ ipfs config Datastore.Path - + Set the value of the 'Datastore.Path' key: - + $ ipfs config Datastore.Path ~/.ipfs/datastore SUBCOMMANDS @@ -751,7 +976,9 @@ SUBCOMMANDS ipfs config replace - Replace the config with . ipfs config show - Output config file contents. - Use 'ipfs config --help' for more information about each command. + For more information about each command, use: + 'ipfs config --help' + ``` ## ipfs config edit @@ -767,6 +994,8 @@ DESCRIPTION To use 'ipfs config edit', you must have the $EDITOR environment variable set to your preferred text editor. + + ``` ## ipfs config profile @@ -778,10 +1007,62 @@ USAGE SYNOPSIS ipfs config profile +DESCRIPTION + + Available profiles: + 'default-networking': + Restores default network settings. + Inverse profile of the test profile. + 'badgerds': + Replaces default datastore configuration with experimental + badger datastore. + + If you apply this profile after ipfs init, you will need + to convert your datastore to the new configuration. + You can do this using ipfs-ds-convert. + + For more on ipfs-ds-convert see + $ ipfs-ds-convert --help + and + $ ipfs-ds-convert convert --help + + WARNING: badger datastore is experimental. + Make sure to backup your data frequently. + 'default-datastore': + Restores default datastore configuration. + + If you apply this profile after ipfs init, you will need + to convert your datastore to the new configuration. + You can do this using ipfs-ds-convert. + + For more on ipfs-ds-convert see + $ ipfs-ds-convert --help + and + $ ipfs-ds-convert convert --help + + 'lowpower': + Reduces daemon overhead on the system. May affect node + functionality - performance of content discovery and data + fetching may be degraded. + + 'randomports': + Use a random port number for swarm. + 'server': + Disables local host discovery, recommended when + running IPFS on machines with public IPv4 addresses. + 'local-discovery': + Sets default values to fields affected by the server + profile, enables discovery in local networks. + 'test': + Reduces external interference of IPFS daemon, this + is useful when using the daemon in test environments. + SUBCOMMANDS ipfs config profile apply - Apply profile to config. - Use 'ipfs config profile --help' for more information about each command. + For more information about each command, use: + 'ipfs config profile --help' + ``` ## ipfs config profile apply @@ -791,11 +1072,18 @@ USAGE ipfs config profile apply - Apply profile to config. SYNOPSIS - ipfs config profile apply [--] + ipfs config profile apply [--dry-run] [--] ARGUMENTS - The profile to apply to the config. + +OPTIONS + + --dry-run bool - print difference between the current config and the config + that would be generated. + + ``` ## ipfs config replace @@ -815,6 +1103,8 @@ DESCRIPTION Make sure to back up the config file first if necessary, as this operation can't be undone. + + ``` ## ipfs config show @@ -829,6 +1119,8 @@ SYNOPSIS DESCRIPTION NOTE: For security reasons, this command will omit your private key. If you would like to make a full backup of your config (private key included), you must copy the config file from your repo. + + ``` ## ipfs daemon @@ -838,106 +1130,130 @@ USAGE ipfs daemon - Run a network-connected IPFS node. SYNOPSIS - ipfs daemon [--init] [--routing=] [--mount] [--writable] [--mount-ipfs=] [--mount-ipns=] [--unrestricted-api] [--disable-transport-encryption] [--enable-gc] [--manage-fdlimit=false] [--offline] [--migrate] [--enable-pubsub-experiment] [--enable-namesys-pubsub] [--enable-mplex-experiment=false] + ipfs daemon [--init] [--init-profile=] [--routing=] + [--mount] [--writable] [--mount-ipfs=] + [--mount-ipns=] [--unrestricted-api] + [--disable-transport-encryption] [--enable-gc] + [--manage-fdlimit=false] [--migrate] [--enable-pubsub-experiment] + [--enable-namesys-pubsub] [--enable-mplex-experiment=false] OPTIONS - --init bool - Initialize ipfs with default settings if not already initialized. - --routing string - Overrides the routing option. Default: dht. - --mount bool - Mounts IPFS to the filesystem. - --writable bool - Enable writing objects (with POST, PUT and DELETE). - --mount-ipfs string - Path to the mountpoint for IPFS (if using --mount). Defaults to config setting. - --mount-ipns string - Path to the mountpoint for IPNS (if using --mount). Defaults to config setting. - --unrestricted-api bool - Allow API access to unlisted hashes. - --disable-transport-encryption bool - Disable transport encryption (for debugging protocols). - --enable-gc bool - Enable automatic periodic repo garbage collection. - --manage-fdlimit bool - Check and raise file descriptor limits if needed. Default: true. - --offline bool - Run offline. Do not connect to the rest of the network but provide local API. - --migrate bool - If true, assume yes at the migrate prompt. If false, assume no. - --enable-pubsub-experiment bool - Instantiate the ipfs daemon with the experimental pubsub feature enabled. - --enable-namesys-pubsub bool - Enable IPNS record distribution through pubsub; enables pubsub. - --enable-mplex-experiment bool - Add the experimental 'go-multiplex' stream muxer to libp2p on construction. Default: true. + --init bool - Initialize ipfs with default + settings if not already initialized. + --init-profile string - Configuration profiles to apply for + --init. See ipfs init --help for + more. + --routing string - Overrides the routing option. + Default: default. + --mount bool - Mounts IPFS to the filesystem. + --writable bool - Enable writing objects (with POST, + PUT and DELETE). + --mount-ipfs string - Path to the mountpoint for IPFS (if + using --mount). Defaults to config + setting. + --mount-ipns string - Path to the mountpoint for IPNS (if + using --mount). Defaults to config + setting. + --unrestricted-api bool - Allow API access to unlisted hashes. + --disable-transport-encryption bool - Disable transport encryption (for + debugging protocols). + --enable-gc bool - Enable automatic periodic repo + garbage collection. + --manage-fdlimit bool - Check and raise file descriptor + limits if needed. Default: true. + --migrate bool - If true, assume yes at the migrate + prompt. If false, assume no. + --enable-pubsub-experiment bool - Instantiate the ipfs daemon with the + experimental pubsub feature enabled. + --enable-namesys-pubsub bool - Enable IPNS record distribution + through pubsub; enables pubsub. + --enable-mplex-experiment bool - Add the experimental 'go-multiplex' + stream muxer to libp2p on + construction. Default: true. DESCRIPTION The daemon will start listening on ports on the network, which are documented in (and can be modified through) 'ipfs config Addresses'. For example, to change the 'Gateway' port: - + ipfs config Addresses.Gateway /ip4/127.0.0.1/tcp/8082 - + The API address can be changed the same way: - + ipfs config Addresses.API /ip4/127.0.0.1/tcp/5002 - + Make sure to restart the daemon after changing addresses. - + By default, the gateway is only accessible locally. To expose it to other computers in the network, use 0.0.0.0 as the ip address: - + ipfs config Addresses.Gateway /ip4/0.0.0.0/tcp/8080 - + Be careful if you expose the API. It is a security risk, as anyone could control your node remotely. If you need to control the node remotely, make sure to protect the port as you would other services or database (firewall, authenticated proxy, etc). - + HTTP Headers - + ipfs supports passing arbitrary headers to the API and Gateway. You can do this by setting headers on the API.HTTPHeaders and Gateway.HTTPHeaders keys: - - ipfs config --json API.HTTPHeaders.X-Special-Header '["so special :)"]' - ipfs config --json Gateway.HTTPHeaders.X-Special-Header '["so special :)"]' - + + ipfs config --json API.HTTPHeaders.X-Special-Header "[\"so special :)\"]" + ipfs config --json Gateway.HTTPHeaders.X-Special-Header "[\"so special :)\"]" + Note that the value of the keys is an _array_ of strings. This is because headers can have more than one value, and it is convenient to pass through to other libraries. - + CORS Headers (for API) - + You can setup CORS headers the same way: - - ipfs config --json API.HTTPHeaders.Access-Control-Allow-Origin '["example.com"]' - ipfs config --json API.HTTPHeaders.Access-Control-Allow-Methods '["PUT", "GET", "POST"]' - ipfs config --json API.HTTPHeaders.Access-Control-Allow-Credentials '["true"]' - + + ipfs config --json API.HTTPHeaders.Access-Control-Allow-Origin "[\"example.com\"]" + ipfs config --json API.HTTPHeaders.Access-Control-Allow-Methods "[\"PUT\", \"GET\", \"POST\"]" + ipfs config --json API.HTTPHeaders.Access-Control-Allow-Credentials "[\"true\"]" + Shutdown - + To shutdown the daemon, send a SIGINT signal to it (e.g. by pressing 'Ctrl-C') or send a SIGTERM signal to it (e.g. with 'kill'). It may take a while for the daemon to shutdown gracefully, but it can be killed forcibly by sending a second signal. - + IPFS_PATH environment variable - + ipfs uses a repository in the local file system. By default, the repo is located at ~/.ipfs. To change the repo location, set the $IPFS_PATH environment variable: - + export IPFS_PATH=/path/to/ipfsrepo - + Routing - + IPFS by default will use a DHT for content routing. There is a highly experimental alternative that operates the DHT in a 'client only' mode that can be enabled by running the daemon as: - + ipfs daemon --routing=dhtclient - + This will later be transitioned into a config option once it gets out of the 'experimental' stage. - + DEPRECATION NOTICE - + Previously, ipfs used an environment variable as seen below: - + export API_ORIGIN="http://localhost:8888/" - + This is deprecated. It is still honored in this version, but will be removed in a future version, along with this notice. Please move to setting the HTTP Headers. + + ``` ## ipfs dag @@ -952,17 +1268,19 @@ SYNOPSIS DESCRIPTION 'ipfs dag' is used for creating and manipulating dag objects. - + This subcommand is currently an experimental feature, but it is intended to deprecate and replace the existing 'ipfs object' command moving forward. - + SUBCOMMANDS ipfs dag get - Get a dag node from ipfs. ipfs dag put ... - Add a dag node to ipfs. ipfs dag resolve - Resolve ipld block - Use 'ipfs dag --help' for more information about each command. + For more information about each command, use: + 'ipfs dag --help' + ``` ## ipfs dag get @@ -980,8 +1298,10 @@ ARGUMENTS DESCRIPTION - 'ipfs dag get' fetches a dag node from ipfs and prints it out in the specifed + 'ipfs dag get' fetches a dag node from ipfs and prints it out in the specified format. + + ``` ## ipfs dag put @@ -991,7 +1311,8 @@ USAGE ipfs dag put ... - Add a dag node to ipfs. SYNOPSIS - ipfs dag put [--format= | -f] [--input-enc=] [--pin] [--hash=] [--] ... + ipfs dag put [--format= | -f] [--input-enc=] [--pin] + [--hash=] [--] ... ARGUMENTS @@ -999,15 +1320,17 @@ ARGUMENTS OPTIONS - -f, --format string - Format that the object will be added as. Default: cbor. - --input-enc string - Format that the input object will be. Default: json. - --pin bool - Pin this object when adding. - --hash string - Hash function to use. Default: . + -f, --format string - Format that the object will be added as. Default: cbor. + --input-enc string - Format that the input object will be. Default: json. + --pin bool - Pin this object when adding. + --hash string - Hash function to use. Default: . DESCRIPTION 'ipfs dag put' accepts input from a file or stdin and parses it into an object of the specified format. + + ``` ## ipfs dag resolve @@ -1026,6 +1349,8 @@ ARGUMENTS DESCRIPTION 'ipfs dag resolve' fetches a dag node from ipfs, prints it's address and remaining path. + + ``` ## ipfs dht @@ -1038,21 +1363,29 @@ SYNOPSIS ipfs dht SUBCOMMANDS - ipfs dht findpeer ... - Query the DHT for all of the multiaddresses associated with a Peer ID. - ipfs dht findprovs ... - Find peers in the DHT that can provide a specific value, given a key. - ipfs dht get ... - Given a key, query the DHT for its best value. - ipfs dht provide ... - Announce to the network that you are providing given values. - ipfs dht put - Write a key/value pair to the DHT. - ipfs dht query ... - Find the closest Peer IDs to a given Peer ID by querying the DHT. + ipfs dht findpeer ... - Find the multiaddresses associated with a + Peer ID. + ipfs dht findprovs ... - Find peers that can provide a specific value, + given a key. + ipfs dht get ... - Given a key, query the routing system for its + best value. + ipfs dht provide ... - Announce to the network that you are + providing given values. + ipfs dht put - Write a key/value pair to the routing system. + ipfs dht query ... - Find the closest Peer IDs to a given Peer ID + by querying the DHT. + + For more information about each command, use: + 'ipfs dht --help' - Use 'ipfs dht --help' for more information about each command. ``` ## ipfs dht findpeer ``` USAGE - ipfs dht findpeer ... - Query the DHT for all of the multiaddresses associated with a Peer ID. + ipfs dht findpeer ... - Find the multiaddresses associated with a + Peer ID. SYNOPSIS ipfs dht findpeer [--verbose | -v] [--] ... @@ -1063,21 +1396,25 @@ ARGUMENTS OPTIONS - -v, --verbose bool - Print extra information. + -v, --verbose bool - Print extra information. DESCRIPTION Outputs a list of newline-delimited multiaddresses. + + ``` ## ipfs dht findprovs ``` USAGE - ipfs dht findprovs ... - Find peers in the DHT that can provide a specific value, given a key. + ipfs dht findprovs ... - Find peers that can provide a specific value, + given a key. SYNOPSIS - ipfs dht findprovs [--verbose | -v] [--num-providers= | -n] [--] ... + ipfs dht findprovs [--verbose | -v] [--num-providers= | -n] + [--] ... ARGUMENTS @@ -1085,19 +1422,22 @@ ARGUMENTS OPTIONS - -v, --verbose bool - Print extra information. - -n, --num-providers int - The number of providers to find. Default: 20. + -v, --verbose bool - Print extra information. + -n, --num-providers int - The number of providers to find. Default: 20. DESCRIPTION Outputs a list of newline-delimited provider Peer IDs. + + ``` ## ipfs dht get ``` USAGE - ipfs dht get ... - Given a key, query the DHT for its best value. + ipfs dht get ... - Given a key, query the routing system for its best + value. SYNOPSIS ipfs dht get [--verbose | -v] [--] ... @@ -1108,24 +1448,27 @@ ARGUMENTS OPTIONS - -v, --verbose bool - Print extra information. + -v, --verbose bool - Print extra information. DESCRIPTION Outputs the best value for the given key. - - There may be several different values for a given key stored in the DHT; in - this context 'best' means the record that is most desirable. There is no one - metric for 'best': it depends entirely on the key type. For IPNS, 'best' is - the record that is both valid and has the highest sequence number (freshest). + + There may be several different values for a given key stored in the routing + system; in this context 'best' means the record that is most desirable. There is + no one metric for 'best': it depends entirely on the key type. For IPNS, 'best' + is the record that is both valid and has the highest sequence number (freshest). Different key types can specify other 'best' rules. + + ``` ## ipfs dht provide ``` USAGE - ipfs dht provide ... - Announce to the network that you are providing given values. + ipfs dht provide ... - Announce to the network that you are providing + given values. SYNOPSIS ipfs dht provide [--verbose | -v] [--recursive | -r] [--] ... @@ -1136,15 +1479,17 @@ ARGUMENTS OPTIONS - -v, --verbose bool - Print extra information. - -r, --recursive bool - Recursively provide entire graph. + -v, --verbose bool - Print extra information. + -r, --recursive bool - Recursively provide entire graph. + + ``` ## ipfs dht put ``` USAGE - ipfs dht put - Write a key/value pair to the DHT. + ipfs dht put - Write a key/value pair to the routing system. SYNOPSIS ipfs dht put [--verbose | -v] [--] @@ -1156,32 +1501,35 @@ ARGUMENTS OPTIONS - -v, --verbose bool - Print extra information. + -v, --verbose bool - Print extra information. DESCRIPTION Given a key of the form /foo/bar and a value of any form, this will write that - value to the DHT with that key. - + value to the routing system with that key. + Keys have two parts: a keytype (foo) and the key name (bar). IPNS uses the /ipns keytype, and expects the key name to be a Peer ID. IPNS entries are specifically formatted (protocol buffer). - + You may only use keytypes that are supported in your ipfs binary: currently this is only /ipns. Unless you have a relatively deep understanding of the - go-ipfs DHT internals, you likely want to be using 'ipfs name publish' instead + go-ipfs routing internals, you likely want to be using 'ipfs name publish' instead of this. - + Value is arbitrary text. Standard input can be used to provide value. - + NOTE: A value may not exceed 2048 bytes. + + ``` ## ipfs dht query ``` USAGE - ipfs dht query ... - Find the closest Peer IDs to a given Peer ID by querying the DHT. + ipfs dht query ... - Find the closest Peer IDs to a given Peer ID by + querying the DHT. SYNOPSIS ipfs dht query [--verbose | -v] [--] ... @@ -1192,11 +1540,13 @@ ARGUMENTS OPTIONS - -v, --verbose bool - Print extra information. + -v, --verbose bool - Print extra information. DESCRIPTION Outputs a list of newline-delimited Peer IDs. + + ``` ## ipfs diag @@ -1212,7 +1562,9 @@ SUBCOMMANDS ipfs diag cmds - List commands run on this IPFS node. ipfs diag sys - Print system diagnostic information. - Use 'ipfs diag --help' for more information about each command. + For more information about each command, use: + 'ipfs diag --help' + ``` ## ipfs diag cmds @@ -1226,7 +1578,7 @@ SYNOPSIS OPTIONS - -v, --verbose bool - Print extra information. + -v, --verbose bool - Print extra information. DESCRIPTION @@ -1234,9 +1586,12 @@ DESCRIPTION SUBCOMMANDS ipfs diag cmds clear - Clear inactive requests from the log. - ipfs diag cmds set-time