From 71afae4576e0e62ca4bf9168f517fc06ff37ac30 Mon Sep 17 00:00:00 2001 From: Rob Brackett Date: Fri, 25 May 2018 19:05:00 -0700 Subject: [PATCH 01/17] Fill in lots of links to external content Plus just a little bit of original text to fill things in a bit. Also has a few rough cuts at "concepts" docs so other people can start expanding them or adding more. License: MIT Signed-off-by: Rob Brackett --- .editorconfig | 8 + .gitignore | 2 + Makefile | 4 +- content/_index.md | 70 +- content/api/_index.md | 5 + content/api/cli.md | 3866 ++++++++ content/api/http.md | 3680 ++++++++ content/api/libraries.md | 3 + content/community/_index.md | 5 + content/community/irc.md | 28 + content/concepts/_index.md | 7 + content/concepts/cid.md | 22 + content/concepts/dnslink.md | 45 + content/concepts/ipns.md | 20 + content/concepts/mfs.md | 16 + content/concepts/unixfs.md | 14 + content/contribute/_index.md | 5 + content/contribute/how_to_help.md | 151 + content/guides/_index.md | 0 content/guides/examples.md | 65 + content/reference/go/overview.md | 34 + content/reference/js/_index.md | 4 + content/reference/js/overview.md | 24 + content/specs/working_groups.md | 12 + content/start/_index.md | 4 + content/start/examples.md | 64 - content/start/faq.md | 6 + content/start/install.md | 209 +- content/start/usage.md | 167 + content/start/webui-connection.png | Bin 0 -> 129911 bytes package-lock.json | 12951 +++++++++++++++++++++++++++ scripts/pkg2md.sh | 8 + 32 files changed, 21252 insertions(+), 247 deletions(-) create mode 100644 .editorconfig create mode 100644 content/api/_index.md create mode 100644 content/api/cli.md create mode 100644 content/api/http.md create mode 100644 content/api/libraries.md create mode 100644 content/community/_index.md create mode 100644 content/community/irc.md create mode 100644 content/concepts/_index.md create mode 100644 content/concepts/cid.md create mode 100644 content/concepts/dnslink.md create mode 100644 content/concepts/ipns.md create mode 100644 content/concepts/mfs.md create mode 100644 content/concepts/unixfs.md create mode 100644 content/contribute/_index.md create mode 100644 content/contribute/how_to_help.md create mode 100644 content/guides/_index.md create mode 100644 content/guides/examples.md create mode 100644 content/reference/go/overview.md create mode 100644 content/reference/js/_index.md create mode 100644 content/reference/js/overview.md create mode 100644 content/specs/working_groups.md delete mode 100644 content/start/examples.md create mode 100644 content/start/faq.md create mode 100644 content/start/usage.md create mode 100644 content/start/webui-connection.png create mode 100644 package-lock.json diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..0f6e914 --- /dev/null +++ b/.editorconfig @@ -0,0 +1,8 @@ +[*] +insert_final_newline = true +indent_size = 4 +indent_style = space +trim_trailing_whitespace = true + +[*.html] +indent_size = 2 diff --git a/.gitignore b/.gitignore index f1e3f9d..9ab0824 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,5 @@ +.vscode + node_modules/ public/ tmp/ diff --git a/Makefile b/Makefile index 03ddbf7..a98c036 100644 --- a/Makefile +++ b/Makefile @@ -19,8 +19,8 @@ endif packages: $(PREPEND)scripts/pkg2md.sh github.com/ipfs/js-ipfs-api master $(PKGDIR) pkg $(PREPEND)scripts/pkg2md.sh github.com/ipfs/js-ipfs master $(PKGDIR) pkg - $(PREPEND)scripts/pkg2md.sh github.com/ipfs/go-ipfs-api master $(PKGDIR) pkg - $(PREPEND)scripts/pkg2md.sh github.com/ipfs/go-ipfs/core/coreapi master $(PKGDIR) pkg + $(PREPEND)scripts/pkg2md.sh github.com/ipfs/go-ipfs-api v1.2.1 $(PKGDIR) go/pkg + $(PREPEND)scripts/pkg2md.sh github.com/ipfs/go-ipfs/core/coreapi v0.4.15 $(PKGDIR) go/pkg build: clean packages $(PREPEND)hugo && \ diff --git a/content/_index.md b/content/_index.md index 33715e3..10f00b1 100644 --- a/content/_index.md +++ b/content/_index.md @@ -3,25 +3,61 @@ type: index title: IPFS Documentation --- -## Code +Welcome to the IPFS documentation portal! Whether you’re just learning about IPFS or are looking for detailed reference information, this is the place to start. You might have noticed that IPFS is a project with a big scope — and a *lot* of different tools, sites, and code. -These are links to some of the IPFS repositories. +## Getting Started + +Head over to the [getting started](/start) section for an introduction to the basics of IPFS and a guide to getting up and running. + + +## Commands & API + +If you are using IPFS via the [command line](/api/cli) or [interacting with a running IPFS node](/api/http) programmatically, you’ll use IPFS’s commands API. It’s implemented in both the Go and JavaScript versions of IPFS. + + +## Concepts + +IPFS is a complex system that aims to change a lot of things about how we use the internet, so it naturally comes with a lot of new concepts. Check the [concepts](/concepts) section to learn more about the major architectural pieces of IPFS and about terms and ideas associated with distributed filesystes. + + +## Go & JavaScript Implementations + +IPFS is fundamentally a set of protocols for communicating about a distributed system of files, but those protocols are informed by reference implementations in both [Go](/reference/go/overview) and [JavaScript](/reference/js/overview). The Go implemntation is more mature and implements more of the IPFS protocols, but the JS implementation can be used in a broader variety of requirements (including in web browsers). + + +## Guides + +The guides section hosts guides, tutorials, and example projects demonstrating various ways to use IPFS. + + +## Specifications & Planning + +While IPFS has two reference implementations (in Go and JavaScript), it is fundamentally a set of protocols for formatting and communicating about distributed filesystems. You can find specifications for those protocols, whitepapers, and information about our RFC (Request for Change) process here. + + +## Applications + +Both the Go and JavaScript implementations of IPFS are written to function as libraries and command-line applications with relatively restricted functionality. We are working on a variety of other applications that make use of IPFS, like GUI applications, browser extensions, and clustering tools for managing large data archives. You can find more about them here. -- ipfs/go-ipfs - IPFS for raw performance and large datasets -- ipfs/js-ipfs - IPFS for decentralized web applications -- ipfs-shipyard/ipfs-companion - IPFS browser extension -- ipfs-shipyard/ipfs-desktop - IPFS desktop app -- ipfs/specs - Technical specs for IPFS -- ipfs/ipfs - Project overview ## Community -- [discuss.ipfs.io](https://discuss.ipfs.io) - Forum for IPFS discussions and support (recommended) -- [#ipfs on freenode IRC](https://riot.im/app/#/room/#ipfs:matrix.org) - Chat room focused on IPFS ([publicly logged](https://botbot.me/freenode/ipfs/)) -- [ipfs-users@groups.google.com](https://groups.google.com/forum/#!forum/ipfs-users) - Mailing list focused on IPFS -- ipfs/awesome-ipfs - Tools and applications built on IPFS -- ipfs/archives - Dataset archival with IPFS -- ipfs/community - Community management and how we work together -- ipfs/pm - IPFS weekly meetings, planning, and project management -- ipfs/in-web-browsers - IPFS in web browsers working group -- ipfs/ipfs - Project overview +Get in touch with other members of the IPFS community who are building tools on top of IPFS or even helping to build IPFS itself! You can ask questions, discuss new ideas, or get support for problems at https://discuss.ipfs.io, but you can also [hop on IRC](/community/irc) for a quick chat. + +See the other links in the community section for more information about meetings, events, apps people are building, and more. + + +## Get Involved + +IPFS is an open-source community project. While [Protocol Labs](https://protocol.ai) is able to sponsor some of the work around it, much of the design, code, and effort is contributed by volunteers and community members like you. If you’re interested in helping improve IPFS, check the [how to help](/contribute/how_to_help) guide to get started. + +If you are diving in to contribute new code, make sure you check both the [contribution guidelines] and the style guide for your language ([Go](https://github.com/ipfs/community/blob/master/go-code-guidelines.md), [JavaScript](https://github.com/ipfs/community/blob/master/js-code-guidelines.md)). + + +## Related Projects + +We’ve split out some of the major parts of IPFS into separate projects over time — while they’re still critical components of IPFS, they can be useful in a variety of other contexts, too. Check their individual sites for specific information and references: + +- [Libp2p](https://libp2p.io) manages all the peer-to-peer networking parts of IFPS. +- [Multiformats](https://multiformats.io) is a variety of *self-describing* data formats. +- [IPLD](https://ipld.io) is a set of tools for describing links between content-addressed data, like IPFS files, Git commits, or Ethereum blocks. diff --git a/content/api/_index.md b/content/api/_index.md new file mode 100644 index 0000000..1b02f42 --- /dev/null +++ b/content/api/_index.md @@ -0,0 +1,5 @@ +--- +title: "Commands & API" +headless: true +opened: true +--- diff --git a/content/api/cli.md b/content/api/cli.md new file mode 100644 index 0000000..c3a4865 --- /dev/null +++ b/content/api/cli.md @@ -0,0 +1,3866 @@ +--- +title: "CLI Commands" +identifier: clicommands +--- + + + + +**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* + +- [ipfs](#ipfs) +- [ipfs add](#ipfs-add) +- [ipfs bitswap](#ipfs-bitswap) +- [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) +- [ipfs block put](#ipfs-block-put) +- [ipfs block rm](#ipfs-block-rm) +- [ipfs block stat](#ipfs-block-stat) +- [ipfs bootstrap](#ipfs-bootstrap) +- [ipfs bootstrap add](#ipfs-bootstrap-add) +- [ipfs bootstrap add default](#ipfs-bootstrap-add-default) +- [ipfs bootstrap list](#ipfs-bootstrap-list) +- [ipfs bootstrap rm](#ipfs-bootstrap-rm) +- [ipfs bootstrap rm all](#ipfs-bootstrap-rm-all) +- [ipfs cat](#ipfs-cat) +- [ipfs commands](#ipfs-commands) +- [ipfs config](#ipfs-config) +- [ipfs config edit](#ipfs-config-edit) +- [ipfs config profile](#ipfs-config-profile) +- [ipfs config profile apply](#ipfs-config-profile-apply) +- [ipfs config replace](#ipfs-config-replace) +- [ipfs config show](#ipfs-config-show) +- [ipfs daemon](#ipfs-daemon) +- [ipfs dag](#ipfs-dag) +- [ipfs dag get](#ipfs-dag-get) +- [ipfs dag put](#ipfs-dag-put) +- [ipfs dag resolve](#ipfs-dag-resolve) +- [ipfs dht](#ipfs-dht) +- [ipfs dht findpeer](#ipfs-dht-findpeer) +- [ipfs dht findprovs](#ipfs-dht-findprovs) +- [ipfs dht get](#ipfs-dht-get) +- [ipfs dht provide](#ipfs-dht-provide) +- [ipfs dht put](#ipfs-dht-put) +- [ipfs dht query](#ipfs-dht-query) +- [ipfs diag](#ipfs-diag) +- [ipfs diag cmds](#ipfs-diag-cmds) +- [ipfs diag cmds clear](#ipfs-diag-cmds-clear) +- [ipfs diag cmds set-time](#ipfs-diag-cmds-set-time) +- [ipfs diag sys](#ipfs-diag-sys) +- [ipfs dns](#ipfs-dns) +- [ipfs file](#ipfs-file) +- [ipfs file ls](#ipfs-file-ls) +- [ipfs files](#ipfs-files) +- [ipfs files chcid](#ipfs-files-chcid) +- [ipfs files cp](#ipfs-files-cp) +- [ipfs files flush](#ipfs-files-flush) +- [ipfs files ls](#ipfs-files-ls) +- [ipfs files mkdir](#ipfs-files-mkdir) +- [ipfs files mv](#ipfs-files-mv) +- [ipfs files read](#ipfs-files-read) +- [ipfs files rm](#ipfs-files-rm) +- [ipfs files stat](#ipfs-files-stat) +- [ipfs files write](#ipfs-files-write) +- [ipfs filestore](#ipfs-filestore) +- [ipfs filestore dups](#ipfs-filestore-dups) +- [ipfs filestore ls](#ipfs-filestore-ls) +- [ipfs filestore verify](#ipfs-filestore-verify) +- [ipfs get](#ipfs-get) +- [ipfs id](#ipfs-id) +- [ipfs init](#ipfs-init) +- [ipfs key](#ipfs-key) +- [ipfs key gen](#ipfs-key-gen) +- [ipfs key list](#ipfs-key-list) +- [ipfs key rename](#ipfs-key-rename) +- [ipfs key rm](#ipfs-key-rm) +- [ipfs log](#ipfs-log) +- [ipfs log level](#ipfs-log-level) +- [ipfs log ls](#ipfs-log-ls) +- [ipfs log tail](#ipfs-log-tail) +- [ipfs ls](#ipfs-ls) +- [ipfs mount](#ipfs-mount) +- [ipfs name](#ipfs-name) +- [ipfs name publish](#ipfs-name-publish) +- [ipfs name pubsub](#ipfs-name-pubsub) +- [ipfs name pubsub cancel](#ipfs-name-pubsub-cancel) +- [ipfs name pubsub state](#ipfs-name-pubsub-state) +- [ipfs name pubsub subs](#ipfs-name-pubsub-subs) +- [ipfs name resolve](#ipfs-name-resolve) +- [ipfs object](#ipfs-object) +- [ipfs object data](#ipfs-object-data) +- [ipfs object diff](#ipfs-object-diff) +- [ipfs object get](#ipfs-object-get) +- [ipfs object links](#ipfs-object-links) +- [ipfs object new](#ipfs-object-new) +- [ipfs object patch](#ipfs-object-patch) +- [ipfs object patch add-link](#ipfs-object-patch-add-link) +- [ipfs object patch append-data](#ipfs-object-patch-append-data) +- [ipfs object patch rm-link](#ipfs-object-patch-rm-link) +- [ipfs object patch set-data](#ipfs-object-patch-set-data) +- [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 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) +- [ipfs pin ls](#ipfs-pin-ls) +- [ipfs pin rm](#ipfs-pin-rm) +- [ipfs pin update](#ipfs-pin-update) +- [ipfs pin verify](#ipfs-pin-verify) +- [ipfs ping](#ipfs-ping) +- [ipfs pubsub](#ipfs-pubsub) +- [ipfs pubsub ls](#ipfs-pubsub-ls) +- [ipfs pubsub peers](#ipfs-pubsub-peers) +- [ipfs pubsub pub](#ipfs-pubsub-pub) +- [ipfs pubsub sub](#ipfs-pubsub-sub) +- [ipfs refs](#ipfs-refs) +- [ipfs refs local](#ipfs-refs-local) +- [ipfs repo](#ipfs-repo) +- [ipfs repo fsck](#ipfs-repo-fsck) +- [ipfs repo gc](#ipfs-repo-gc) +- [ipfs repo stat](#ipfs-repo-stat) +- [ipfs repo verify](#ipfs-repo-verify) +- [ipfs repo version](#ipfs-repo-version) +- [ipfs resolve](#ipfs-resolve) +- [ipfs shutdown](#ipfs-shutdown) +- [ipfs stats](#ipfs-stats) +- [ipfs stats bitswap](#ipfs-stats-bitswap) +- [ipfs stats bw](#ipfs-stats-bw) +- [ipfs stats repo](#ipfs-stats-repo) +- [ipfs swarm](#ipfs-swarm) +- [ipfs swarm addrs](#ipfs-swarm-addrs) +- [ipfs swarm addrs listen](#ipfs-swarm-addrs-listen) +- [ipfs swarm addrs local](#ipfs-swarm-addrs-local) +- [ipfs swarm connect](#ipfs-swarm-connect) +- [ipfs swarm disconnect](#ipfs-swarm-disconnect) +- [ipfs swarm filters](#ipfs-swarm-filters) +- [ipfs swarm filters add](#ipfs-swarm-filters-add) +- [ipfs swarm filters rm](#ipfs-swarm-filters-rm) +- [ipfs swarm peers](#ipfs-swarm-peers) +- [ipfs tar](#ipfs-tar) +- [ipfs tar add](#ipfs-tar-add) +- [ipfs tar cat](#ipfs-tar-cat) +- [ipfs update](#ipfs-update) +- [ipfs version](#ipfs-version) + +## ipfs + +``` +USAGE + ipfs - Global p2p merkle-dag filesystem. + +SYNOPSIS + ipfs [--config= | -c] [--debug= | -D] [--help=] [-h=] [--local= | -L] [--api=] ... + +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. + +SUBCOMMANDS + BASIC COMMANDS + init Initialize ipfs local configuration + add Add a file to IPFS + cat Show IPFS object data + 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 + resolve Resolve any type of name + name Publish and resolve IPNS names + key Create and list IPNS name keypairs + dns Resolve DNS links + pin Pin objects to local storage + repo Manipulate the IPFS repository + 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 + swarm Manage connections to the p2p network + 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 + + 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. +``` + +## ipfs add + +``` +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=] [--] ... + +ARGUMENTS + + ... - The path to a file to be added to ipfs. + +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. + +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 + 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. + + > 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 + > ipfs object links Qmf1hDN65tR55Ubh2RN1FPxr69xq3giVBz1KApsresY8Gn + QmY6yj1GsermExDXoosVE3aSPxdMNYr6aKuw3nA8LoWPRS 2059 + QmerURi9k4XzKCaaPbsK6BL5pMEjF7PGphjDvkkjDtsVf3 868 + QmQB28iwSriSUSMqG2nXDTLtdPHgWb4rebBrU7Q1j4vxPv 338 +``` + +## ipfs bitswap + +``` +USAGE + ipfs bitswap - Interact with the bitswap agent. + +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. + + Use 'ipfs bitswap --help' for more information about each command. +``` + +## ipfs bitswap ledger + +``` +USAGE + ipfs bitswap ledger - Show the current ledger for a peer. + +SYNOPSIS + ipfs bitswap ledger [--] + +ARGUMENTS + + - The PeerID (B58) of the ledger to inspect. + +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 + +``` +USAGE + ipfs bitswap reprovide - Trigger reprovider. + +SYNOPSIS + ipfs bitswap reprovide + +DESCRIPTION + + Trigger reprovider to announce our data to network. +``` + +## ipfs bitswap stat + +``` +USAGE + ipfs bitswap stat - Show some diagnostic information on the bitswap agent. + +SYNOPSIS + ipfs bitswap stat +``` + +## ipfs bitswap unwant + +``` +USAGE + ipfs bitswap unwant ... - Remove a given block from your wantlist. + +SYNOPSIS + ipfs bitswap unwant [--] ... + +ARGUMENTS + + ... - Key(s) to remove from your wantlist. +``` + +## ipfs bitswap wantlist + +``` +USAGE + ipfs bitswap wantlist - Show blocks currently on the wantlist. + +SYNOPSIS + ipfs bitswap wantlist [--peer= | -p] + +OPTIONS + + -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 + +``` +USAGE + ipfs block - Interact with raw IPFS blocks. + +SYNOPSIS + ipfs block + +DESCRIPTION + + 'ipfs block' is a plumbing command used to manipulate raw IPFS blocks. + Reads from stdin or writes to stdout, and is a base58 encoded + multihash. + +SUBCOMMANDS + ipfs block get - Get a raw IPFS block. + ipfs block put - Store input as an IPFS block. + 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. +``` + +## ipfs block get + +``` +USAGE + ipfs block get - Get a raw IPFS block. + +SYNOPSIS + ipfs block get [--] + +ARGUMENTS + + - The base58 multihash of an existing block to get. + +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 + +``` +USAGE + ipfs block put - Store input as an IPFS block. + +SYNOPSIS + ipfs block put [--format= | -f] [--mhtype=] [--mhlen=] [--] + +ARGUMENTS + + - The data to be stored as an IPFS block. + +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. + +DESCRIPTION + + 'ipfs block put' is a plumbing command for storing raw IPFS blocks. + It reads from stdin, and is a base58 encoded multihash. +``` + +## ipfs block rm + +``` +USAGE + ipfs block rm ... - Remove IPFS block(s). + +SYNOPSIS + ipfs block rm [--force | -f] [--quiet | -q] [--] ... + +ARGUMENTS + + ... - Bash58 encoded multihash of block(s) to remove. + +OPTIONS + + -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. +``` + +## ipfs block stat + +``` +USAGE + ipfs block stat - Print information of a raw IPFS block. + +SYNOPSIS + ipfs block stat [--] + +ARGUMENTS + + - The base58 multihash of an existing block to stat. + +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 + +``` +USAGE + ipfs bootstrap - Show or edit the list of bootstrap peers. + +SYNOPSIS + ipfs bootstrap + +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 + if you understand the risks of adding or removing nodes from this list. + +SUBCOMMANDS + ipfs bootstrap add []... - Add peers to the bootstrap list. + 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. +``` + +## ipfs bootstrap add + +``` +USAGE + ipfs bootstrap add []... - Add peers to the bootstrap list. + +SYNOPSIS + ipfs bootstrap add [--default] [--] [...] + +ARGUMENTS + + []... - A peer to add to the bootstrap list (in the format '/') + +OPTIONS + + --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 + if you understand the risks of adding or removing nodes from this list. + +SUBCOMMANDS + ipfs bootstrap add default - Add default peers to the bootstrap list. + + Use 'ipfs bootstrap add --help' for more information about each command. +``` + +## ipfs bootstrap add default + +``` +USAGE + ipfs bootstrap add default - Add default peers to the bootstrap list. + +SYNOPSIS + ipfs bootstrap add default + +DESCRIPTION + + Outputs a list of peers that were added (that weren't already + in the bootstrap list). +``` + +## ipfs bootstrap list + +``` +USAGE + ipfs bootstrap list - Show peers in the bootstrap list. + +SYNOPSIS + ipfs bootstrap list + +DESCRIPTION + + Peers are output in the format '/'. +``` + +## ipfs bootstrap rm + +``` +USAGE + ipfs bootstrap rm []... - Remove peers from the bootstrap list. + +SYNOPSIS + ipfs bootstrap rm [--all] [--] [...] + +ARGUMENTS + + []... - A peer to add to the bootstrap list (in the format '/') + +OPTIONS + + --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 + if you understand the risks of adding or removing nodes from this list. + +SUBCOMMANDS + ipfs bootstrap rm all - Remove all peers from the bootstrap list. + + Use 'ipfs bootstrap rm --help' for more information about each command. +``` + +## ipfs bootstrap rm all + +``` +USAGE + ipfs bootstrap rm all - Remove all peers from the bootstrap list. + +SYNOPSIS + ipfs bootstrap rm all + +DESCRIPTION + + Outputs the list of peers that were removed. +``` + +## ipfs cat + +``` +USAGE + ipfs cat ... - Show IPFS object data. + +SYNOPSIS + ipfs cat [--offset= | -o] [--length= | -l] [--] ... + +ARGUMENTS + + ... - The path to the IPFS object(s) to be outputted. + +OPTIONS + + -o, --offset int - Byte offset to begin reading from. + -l, --length int - Maximum number of bytes to read. + +DESCRIPTION + + Displays the data contained by an IPFS or IPNS object(s) at the given path. +``` + +## ipfs commands + +``` +USAGE + ipfs commands - List all available commands. + +SYNOPSIS + ipfs commands [--flags | -f] + +OPTIONS + + -f, --flags bool - Show command flags. + +DESCRIPTION + + Lists all available commands (and subcommands) and exits. +``` + +## ipfs config + +``` +USAGE + ipfs config [] - Get and set ipfs config values. + +SYNOPSIS + ipfs config [--bool] [--json] [--] [] + +ARGUMENTS + + - The key of the config entry (e.g. "Addresses.API"). + [] - The value to set the config entry to. + +OPTIONS + + --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 + ipfs config edit - Open the config file for editing in $EDITOR. + ipfs config profile - Apply profiles to config. + ipfs config replace - Replace the config with . + ipfs config show - Output config file contents. + + Use 'ipfs config --help' for more information about each command. +``` + +## ipfs config edit + +``` +USAGE + ipfs config edit - Open the config file for editing in $EDITOR. + +SYNOPSIS + ipfs config edit + +DESCRIPTION + + To use 'ipfs config edit', you must have the $EDITOR environment + variable set to your preferred text editor. +``` + +## ipfs config profile + +``` +USAGE + ipfs config profile - Apply profiles to config. + +SYNOPSIS + ipfs config profile + +SUBCOMMANDS + ipfs config profile apply - Apply profile to config. + + Use 'ipfs config profile --help' for more information about each command. +``` + +## ipfs config profile apply + +``` +USAGE + ipfs config profile apply - Apply profile to config. + +SYNOPSIS + ipfs config profile apply [--] + +ARGUMENTS + + - The profile to apply to the config. +``` + +## ipfs config replace + +``` +USAGE + ipfs config replace - Replace the config with . + +SYNOPSIS + ipfs config replace [--] + +ARGUMENTS + + - The file to use as the new config. + +DESCRIPTION + + Make sure to back up the config file first if necessary, as this operation + can't be undone. +``` + +## ipfs config show + +``` +USAGE + ipfs config show - Output config file contents. + +SYNOPSIS + ipfs config show + +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 + +``` +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] + +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. + +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 :)"]' + + 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"]' + + 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 + +``` +USAGE + ipfs dag - Interact with ipld dag objects. + +SYNOPSIS + ipfs dag + +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. +``` + +## ipfs dag get + +``` +USAGE + ipfs dag get - Get a dag node from ipfs. + +SYNOPSIS + ipfs dag get [--] + +ARGUMENTS + + - The object to get + +DESCRIPTION + + 'ipfs dag get' fetches a dag node from ipfs and prints it out in the specifed + format. +``` + +## ipfs dag put + +``` +USAGE + ipfs dag put ... - Add a dag node to ipfs. + +SYNOPSIS + ipfs dag put [--format= | -f] [--input-enc=] [--pin] [--hash=] [--] ... + +ARGUMENTS + + ... - The object to put + +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: . + +DESCRIPTION + + 'ipfs dag put' accepts input from a file or stdin and parses it + into an object of the specified format. +``` + +## ipfs dag resolve + +``` +USAGE + ipfs dag resolve - Resolve ipld block + +SYNOPSIS + ipfs dag resolve [--] + +ARGUMENTS + + - The path to resolve + +DESCRIPTION + + 'ipfs dag resolve' fetches a dag node from ipfs, prints it's address and remaining path. +``` + +## ipfs dht + +``` +USAGE + ipfs dht - Issue commands directly through the DHT. + +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. + + 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. + +SYNOPSIS + ipfs dht findpeer [--verbose | -v] [--] ... + +ARGUMENTS + + ... - The ID of the peer to search for. + +OPTIONS + + -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. + +SYNOPSIS + ipfs dht findprovs [--verbose | -v] [--num-providers= | -n] [--] ... + +ARGUMENTS + + ... - The key to find providers for. + +OPTIONS + + -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. + +SYNOPSIS + ipfs dht get [--verbose | -v] [--] ... + +ARGUMENTS + + ... - The key to find a value for. + +OPTIONS + + -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). + 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. + +SYNOPSIS + ipfs dht provide [--verbose | -v] [--recursive | -r] [--] ... + +ARGUMENTS + + ... - The key[s] to send provide records for. + +OPTIONS + + -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. + +SYNOPSIS + ipfs dht put [--verbose | -v] [--] + +ARGUMENTS + + - The key to store the value at. + - The value to store. + +OPTIONS + + -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. + + 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 + 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. + +SYNOPSIS + ipfs dht query [--verbose | -v] [--] ... + +ARGUMENTS + + ... - The peerID to run the query against. + +OPTIONS + + -v, --verbose bool - Print extra information. + +DESCRIPTION + + Outputs a list of newline-delimited Peer IDs. +``` + +## ipfs diag + +``` +USAGE + ipfs diag - Generate diagnostic reports. + +SYNOPSIS + ipfs diag + +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. +``` + +## ipfs diag cmds + +``` +USAGE + ipfs diag cmds - List commands run on this IPFS node. + +SYNOPSIS + ipfs diag cmds [--verbose | -v] + +OPTIONS + + -v, --verbose bool - Print extra information. + +DESCRIPTION + + Lists running and recently run commands. + +SUBCOMMANDS + ipfs diag cmds clear - Clear inactive requests from the log. + ipfs diag cmds set-time