|
| 1 | +--- |
| 2 | +title: 'Publish using the command line' |
| 3 | +description: 'Learn how to publish content with IPFS by pinning a file to a pinning service using the command line.' |
| 4 | +--- |
| 5 | + |
| 6 | +# Publish a file with IPFS using the command line |
| 7 | + |
| 8 | +Similar to the [Publish a file with IPFS](./publish.md) quickstart, this guide will teach you about [pinning services](../concepts/persistence.md#pinning-in-context) and how to use them to publish content-addressed data with IPFS. However, instead of using the [Web3 UI used in the related guide](./publish.md#upload-and-pin-a-file) , you will upload the file to [web3.storage](https://web3.storage/) using the [w3 command line interface](https://github.com/web3-storage/w3cli). By the end of this guide, you should have a better understanding of how content addressing and CIDs work from a high level, as well as how to use the w3 command line interface to publish data to IPFS. |
| 9 | + |
| 10 | +:::callout |
| 11 | +The web3.storage pinning service was chosen purely for demonstration purposes, and is one of many [pinning services](../concepts/persistence.md#pinning-in-context) you can choose from. While each pinning services has different SDKs and APIs, their fundamental role is the same - to store files and make them available to the IPFS network. In fact, one of the main benefits of IPFS is that files can be pinned to multiple pinning services, thereby reducing vendor lock-in. |
| 12 | +::: |
| 13 | + |
| 14 | +## Contents <!-- omit from toc --> |
| 15 | + |
| 16 | +- [Overview](#overview) |
| 17 | +- [Pinning services](#pinning-services) |
| 18 | +- [Prerequisites](#prerequisites) |
| 19 | +- [Uploading and pinning a file](#uploading-and-pinning-a-file) |
| 20 | +- [CIDs explained](#cids-explained) |
| 21 | +- [Retrieving with a gateway](#retrieving-with-a-gateway) |
| 22 | +- [Summary and next steps](#summary-and-next-steps) |
| 23 | + |
| 24 | +## Overview |
| 25 | + |
| 26 | +_Pinning_ refers to the process of ensuring that a particular piece of content is retrievable with IPFS. In other words, pinning is equivalent to storing a file on a computer or server that is connected to the internet, thereby making it available to the rest of the IPFS network. |
| 27 | + |
| 28 | +Pinning can be done at various levels, from individual files to entire directories that are addressed by a CID. You can also pin CIDs to multiple IPFS nodes to increase the redundancy and resilience of the file on the network. |
| 29 | + |
| 30 | +## Pinning services |
| 31 | + |
| 32 | +[Pinning services](../concepts/persistence.md#pinning-services) are similar to hosting services, in that they run an IPFS node for you and ensure that your files are available to the IPFS network. |
| 33 | + |
| 34 | +:::callout |
| 35 | +Data pinned to the IPFS network is public by default and retrievable by anyone. Avoid publishing private data or adequately encrypt it before publishing. |
| 36 | +::: |
| 37 | + |
| 38 | +## Prerequisites |
| 39 | + |
| 40 | +- A unix-like terminal. |
| 41 | +- Node.js installed in the terminal environment. |
| 42 | +- The [following image](../quickstart/images/welcome-to-IPFS.jpg), downloaded and saved on your computer: |
| 43 | + |
| 44 | + |
| 45 | + |
| 46 | +## Install and register to w3 |
| 47 | + |
| 48 | +1. Install the [w3 command line interface](https://github.com/web3-storage/w3cli). |
| 49 | + |
| 50 | + ```shell |
| 51 | + npm install -g @web3-storage/w3cli |
| 52 | + |
| 53 | +1. Authorize the w3 tool to act on behalf of the account associated with your email address `<your@email.com>`: |
| 54 | + |
| 55 | + ```shell |
| 56 | + w3 authorize <your@email.com> |
| 57 | +
|
| 58 | +## Upload and pin a file |
| 59 | +
|
| 60 | +1. Create a space for your files. |
| 61 | +
|
| 62 | + ```shell |
| 63 | + w3 space create Pictures |
| 64 | + |
| 65 | +1. Upload your file. |
| 66 | + |
| 67 | + ```shell |
| 68 | + w3 up welcome-to-IPFS.jpg |
| 69 | + ``` |
| 70 | + |
| 71 | +Congratulations, you have successfully **pinned** a file to IPFS using the w3 cli! 🎉 |
| 72 | + |
| 73 | +Let's unpack what just happened, by looking at CIDs. |
| 74 | +
|
| 75 | +## CIDs explained |
| 76 | +
|
| 77 | +In IPFS, every file and directory is identified with a Content Identifier ([CID](../concepts/content-addressing.md)). The CID serves as the **permanent address** of the file and can be used by anyone to find it on the IPFS network. |
| 78 | +
|
| 79 | +When a file is first added to an IPFS node (like the image used in this guide), it's first transformed into a content-addressable representation in which the file is split into smaller chunks (if above ~1MB) which are linked together and hashed to produce the CID. |
| 80 | + |
| 81 | +In this guide, the CID for the uploaded image is: |
| 82 | + |
| 83 | +```plaintext |
| 84 | +bafybeicn7i3soqdgr7dwnrwytgq4zxy7a5jpkizrvhm5mv6bgjd32wm3q4 |
| 85 | +``` |
| 86 | + |
| 87 | +You can now share the CID with anyone and they can fetch the file using IPFS. |
| 88 | + |
| 89 | +To dive deeper into the anatomy of the CID, check out the [CID inspector](https://cid.ipfs.tech/#bafybeicn7i3soqdgr7dwnrwytgq4zxy7a5jpkizrvhm5mv6bgjd32wm3q4). |
| 90 | + |
| 91 | +:::callout |
| 92 | +The transformation into a content-addressable representation is a local operation that doesn't require any network connectivity. With web3.storage, this transformation happens client-side (in the browser). |
| 93 | +::: |
| 94 | +
|
| 95 | +## Retrieving with a gateway |
| 96 | +
|
| 97 | +Now that your file is pinned to a pinning service, you will fetch it using an IPFS gateway. An [**IPFS Gateway**](../concepts/ipfs-gateway.md) is an HTTP interface that serves as a bridge to the IPFS network. In other words, it allows you to fetch CIDs from IPFS using HTTP. |
| 98 | +
|
| 99 | +Pinning services typically offer an IPFS gateway as a way to easily retrieve your CIDs. For example, Web3.storage operates the [w3s.link](https://w3s.link) gateway, from which you can retrieve the uploaded CID. |
| 100 | +
|
| 101 | +To retrieve the CID, open the following URL: |
| 102 | +[bafybeicn7i3soqdgr7dwnrwytgq4zxy7a5jpkizrvhm5mv6bgjd32wm3q4.ipfs.w3s.link](https://bafybeicn7i3soqdgr7dwnrwytgq4zxy7a5jpkizrvhm5mv6bgjd32wm3q4.ipfs.w3s.link/) |
| 103 | +
|
| 104 | +:::callout |
| 105 | +When pinning a file to IPFS, the filename is not stored by default. To ensure the filename is retained, it's common to wrap the file in a directory. In such instances, both the file and the directory will have unique CIDs. Web3.storage wraps files in a directory by default, which is why you see a directory listing with the file `welcome-to-IPFS.jpg` followed by a shorthand CID: `bafk…beom` of the file. |
| 106 | +::: |
| 107 | + |
| 108 | +## Summary and next steps |
| 109 | + |
| 110 | +In this quickstart guide, you learned about [pinning services](../concepts/persistence.md#pinning-in-context), and how to use them to publish content-addressed data with IPFS. You also learned how CIDs address files and directories in IPFS by uploading a file to a pinning service called [web3.storage](https://web3.storage/). |
| 111 | + |
| 112 | +Pinning services provide a convenient alternative to running IPFS nodes and infrastructure. However, the two are not mutually exclusive; you can combine a pinning service with an IPFS node on your computer to increase the resilience of your CIDs. |
| 113 | + |
| 114 | +Possible next steps include: |
| 115 | + |
| 116 | +- Check out [the lifecycle of data in IPFS](../concepts/lifecycle.md) to learn more about how publishing by pinning fits into the full lifecycle of data in IPFS. |
| 117 | +- Try fetching the pinned file by following the [retrieval quickstart](./retrieve.md). |
| 118 | +- If you prefer to upload a file programmatically with JavaScript or Go, check out the [Web3.storage docs](https://web3.storage/docs/how-tos/store/). |
| 119 | +- Alternatively, try out [Filebase](https://filebase.com/), a pinning service that offers an [AWS S3-compatible API for pinning](https://docs.filebase.com/getting-started/s3-api-getting-started-guide), so you can use any S3-compatible SDK, e.g. [aws-sdk](https://www.npmjs.com/package/aws-sdk), and [many](https://github.com/s3tools/s3cmd) more. |
0 commit comments