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
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.
w3cli is avaliable through NPM.
You can install it from a command shell using
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
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:
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 firstname.lastname@example.org
email@example.com 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!
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
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
$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.
You'll see something like this:
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.
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!