Using w3up-cli

We recently introduced w3up, our new upload service built on a brand new foundation.

Today, we'll take a look at w3up-cli, the command-line interface for the w3up service.

Getting Started

w3up-cli is avaliable through NPM.

You can install it from a command shell using npm install:

npm install -g @web3-storage/w3up-cli

This should make a new w3up command available. Try running w3up without giving it any arguments. You should see something like this, plus some more detailed help text that we'll skip for brevity's sake:

Quickstart:
1. Generate Your identity
	- w3up id 			Create an id
	- w3up register <email> 	Register
2. Upload to W3 Up
	- w3up upload <filename> 	Upload a file or directory
3. Verify
	- w3up list 			View your upload

Let's give the quickstart a try!

Creating and registering a UCAN identity

First, we need to create and register a new UCAN identity. UCAN is a new authorization protocol that puts the user in charge of their own identity using public key cryptography. For an overview, check out our introduction to w3up post, and stay tuned for more in-depth posts about using UCANs with w3up.

The w3up id command will create a new UCAN identity key and save it to your local machine, printing the public UCAN id.

w3up id

You should see something like this:

✔ Generating new id
✔ ID: did:key:z6MkoeP5Z692sroWg1YdE75zwHmXWYZFhqEFZ8J45hDr5yCQ

If you run w3up id again, it will load the key from your saved settings instead of generating a new one.

Once you have an id, you can register it with the w3up service using w3up register:

w3up register $your_email_address

Replace $your_email_address with your address, and check your inbox for a confirmation email. Once you click the link in the confirmation email, you'll see a "Registration succeeded" message. Now you're ready to upload!

Uploading files

The w3up upload command takes the path to a file or directory and uploads it to w3up.

Below we'll make a text file with the contents "Hello, Web3" and upload it using w3up upload.

echo "Hello, Web3" > hello.txt

w3up upload hello.txt

You'll see something like this:

✔ Succeeded uploading bagbaierashsppq2wjv4nuzdm6akwm4a7265h7mkyoiztc6ve2kmjirex7f3q with 200: OK
roots:
 bafybeihz3pma73nw6diuz6kjn7gbcddevretqawfatbpc7f3fvlgcmznum

The output above shows two CIDs (Content Identifiers), and if you used the same hello.txt file you should see the exact same CIDs. Of course, if you're uploading a different file, the CIDs will be different, but you should still see two of them in the output.

The first CID (starting with bag) identifies the Content Archive (CAR) that w3up prepares when uploading data. CARs are collections of content addressed data in an "IPFS native" format, and w3up uses them extensively under the hood. Generating CARs on the client side helps us ensure end-to-end data integrity, and it helps streamline the upload process and ingestion into Elastic IPFS.

The second CID (starting with bafy) identifies the "root" of the graph of content addressed data that is contained in the CAR. All data on IPFS is encoded into a set of "blocks" of binary data, with links between blocks forming a graph. Using the root CID, you can fetch the entire graph using an IPFS implementation like kubo or an IPFS to HTTP gateway.

For example, we can take the root CID from above and use it with the IPFS gateway at https://w3s.link by creating the following URL: https://w3s.link/ipfs/bafybeihz3pma73nw6diuz6kjn7gbcddevretqawfatbpc7f3fvlgcmznum

This will take you to an IPFS directory listing containing our `hello.txt` file:

Gateway URLs let you "bridge the gap" between IPFS and the web2 protocols supported by all browsers today. You can learn more about gateways in the IPFS documentation, but the TL;DR is to make a URL of the form https://$GATEWAY_HOST/ipfs/$CID, where $GATEWAY_HOST is the domain of the gateway, and $CID is the root CID of your content. If you're looking for a gateway host, feel free to use ours at w3s.link.

Verifying the upload

Once your upload completes, you can use the w3up list command to get a list of all the uploads you've made so far.

w3up list

You'll see something like this:

✔ Listing Uploads...
✔ 
Date       Root CID 
---------  -------  
9/28/2022  bafybeihz3pma73nw6diuz6kjn7gbcddevretqawfatbpc7f3fvlgcmznum

Count: 1

Here we can see the root CIDs of the content we've uploaded so far. Note that we're likely to tweak things a bit during the beta period, so your output may look a little different depending on when you run the command.

What's next?

The w3up tool has more commands for managing your uploads, creating and inspecting CAR files, and more. Check out the README for more details.

We're still building w3up and are adding and refining features every day. We need your help to build the best possible platform, so please reach out and let us know how you're using it and how we can improve things for your needs.

We'll also be posting updates to this blog as things roll out, so stay tuned!