Using w3up-cli
We recently introduced w3up, our new upload service built on a brand new foundation.
Today, we'll take a look at w3cli, the command-line interface for the w3up service.
Update: This post was updated in January 2023 to reflect changes made during the beta development cycle. The w3up-cli tool originally described in this post has been deprecated and replaced by w3cli. See our announcement post for more information about the changes in beta v2.
Getting Started
w3cli is avaliable through NPM.
You can install it from a command shell using npm install:
npm install -g @web3-storage/w3cli
This should make a new w3 command available. Try running w3 --help. You should see some help text similar to this:
Usage
$ w3 <command> [options]
Available Commands
up Store a file(s) to the service and register an upload.
open Open CID on https://w3s.link
ls List uploads in the current space
rm Remove an upload from the uploads listing.
whoami Print information about the current agent.
space Create and mangage w3 spaces
space create Create a new w3 space
space register Claim the space by associating it with your email address
space add Add a space to the agent.
space ls List spaces known to the agent
space use Set the current space in use by the agent
delegation create Create a delegation to the passed audience for the given abilities with the _current_ space as the resource.
delegation ls List delegations created by this agent for others.
proof add Add a proof delegated to this agent.
proof ls List proofs of capabilities delegated to this agent.
can store add Store a CAR file with the service.
can upload add Register an upload - a DAG with the given root data CID that is stored in the given CAR shard(s), identified by CAR CIDs.
For more info, run any command with the `--help` flag
$ w3 up --help
$ w3 open --help
Options
-v, --version Displays current version
-h, --help Displays this message
Examples
$ w3 up path/to/files
In this post we'll walk through everything you need to get started uploading files using the w3 tool.
Creating and registering a space
Files that you upload to w3up are organized into "spaces," which act a bit like cloud storage buckets.
You can have multiple spaces, but you'll need at least one in order to upload.
Create your first space with the w3 space create command:
w3 space create Documents
You should see something like this, although your identifier will be different:
did:key:z6MkvjhcXtyKA7qsU8wwEwf9qZSUZ9FkksG4xLEwofKGUe9S
We've given our new space the name "Documents." You can name your spaces whatever you want, or skip the name entirely and just refer to them by their DID.
Before we can upload files, we need to register our space with the w3up service using w3 space register:
w3 space register your-address@email-provider.net
Replace your-address@email-provider.net with your actual address, and check your inbox for a confirmation email. Once you click the link in the confirmation email, you shoud see a confirmation message. Now you're ready to upload!
Uploading files
The w3 upcommand takes the path to a file or directory and uploads it to the w3up service.
Below we'll make a text file with the contents "Hello, Web3" and upload it using w3up upload.
echo "Hello, Web3" > hello.txt
w3 up hello.txt
You'll see something like this:
1 file (12B)
bagbaieraspawtgooy5lptr7loyd3fxjsrgkamre3y6au3ga4df5bkhrxdkmq
⁂ Stored 1 file
⁂ https://w3s.link/ipfs/bafybeidwm2gfdrx2yjnzdqnw7n3a2er2vo5uwv6w5otjfbyboeoq3jfiby
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 is embedded into the w3s.link gateway URL that's printed to the console. This CID 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.
Following the URL will take you to an IPFS gateway, where you'll see 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://$CID.ipfs.$GATEWAY_HOST or https://$GATEWAY_HOST/ipfs/$CID, where $GATEWAY_HOST is the domain of the gateway, and $CID is the root CID of your content.
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.
w3 list
You'll see something like this:
bafybeidwm2gfdrx2yjnzdqnw7n3a2er2vo5uwv6w5otjfbyboeoq3jfiby
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 w3 tool has more commands for managing your spaces, delegating permissions, 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!
