You can get started using web3.storage right away from your command line using
w3, our command line interface tool.
In this guide, we'll walk through the following steps:
- Installing the
- Creating and provisioning your first space
- Uploading a file or directory
- Viewing your file with IPFS
You'll need Node (opens in a new tab) version 18 or higher, with NPM version 7 or higher to complete this guide. You can check your local versions like this
node --version && npm --version
@web3-storage/w3cli package with
npm install -g @web3-storage/w3cli
Once the install is complete, you'll have a
w3 command available. Try running
w3 --help to get an idea of what's possible.
When you upload things to web3.storage, each upload is associated with a "space," which is a unique identifier that acts as a namespace for your content.
Spaces are identified by DID using keys created locally on your devices. To use a space for uploads, it needs to be registered with the storage service by providing an email address.
To create a space using the
w3 command line tool, use the
w3 space create command. You can optionally give your space a "friendly" name, which acts like an alias for the space's DID and can make it easier to tell your spaces apart. In the example below, we'll use the name
w3 space create Documents
The DID for the new space will be printed to the console. It should look something like this, although the part after
did:key will be unique to your space:
You can now run
w3 space ls to show a list of your spaces:
* did:key:z6MkixXechJLc3TWibQj9RN6AiFx8VoMY9HNB3Y97WcwK3fm Documents
* symbol indicates that the
Documents space is currently active. If you make multiple spaces, you can switch between them with
w3 space use, passing in the name or DID of the space you want to activate.
Now that you've created and registered a space, you're ready to upload files to web3.storage!
w3 up command to upload a file or directory:
w3 up your-file.txt
Once your upload is complete, you should see a URL that links to your file on the
w3s.link IPFS gateway.
If you uploaded a single file, the link will resolve to an IPFS directory listing, with the actual file contained in the directory. This "wrapper" directory preserves the original filename of your upload, which can help organize your content and allows people to download files using their original names. If you don't want to create the wrapper directory, you can pass in the
--no-wrap flag when running
When uploading directories, files beginning with a
. character are ignored by default. To include hidden files instead, pass in the
When your upload completes, you should see a link to your files on the
w3s.link IPFS gateway. Just click the link to see your files!