CLI
You can get started using Storacha right away from your command line using our command line interface tool. Additionally, if you use the CLI, you can sign up using your Github credentials!
In this guide, we'll walk through the following steps:
- Installing the CLI tool
- Creating and provisioning your first space
- Uploading a file or directory
- Viewing your file with IPFS
Install
You'll need Node.js (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
Install the @storacha/cli
package with npm
npm install -g @storacha/cli
Once the install is complete, you'll have a storacha
command available. Try running storacha --help
to get an idea of what's possible.
Standalone Binaries
These binaries are built from the Go client codebase which is not as fully featured as the JS client.
Pre-compiled, standalone binaries are now available for MacOS, Linux and Windows: Download latest release (opens in a new tab).
We strongly recommend reading the Go CLI documentation (opens in a new tab). These binaries are built from the Go client codebase which is not as fully featured as the JS client. To use the Go CLI tool, you will need to obtain a delegation created by the JS CLI or console (opens in a new tab).
Create Your First Space
Everything uploaded to Storacha is associated with a "Space". A space 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 Storacha by providing an email address.
To create a space using the storacha
command line tool, use the storacha space create
command. You should 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. Names for spaces cannot be changed at this time. In the example below, we'll use the name Documents
:
storacha 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:
did:key:z6MkixXechJLc3TWibQj9RN6AiFx8VoMY9HNB3Y97WcwK3fm
You can now run storacha space ls
to show a list of your spaces:
* did:key:z6MkixXechJLc3TWibQj9RN6AiFx8VoMY9HNB3Y97WcwK3fm Documents
The *
symbol indicates that the Documents
space is currently active. If you make multiple spaces, you can switch between them with storacha space use
, passing in the name or DID of the space you want to activate.
Upload Files
Now that you've created and registered a space, you're ready to upload files to Storacha!
Use the storacha up
command to upload a file or directory:
storacha up your-file.txt
Once your upload is complete, you should see a URL that links to your file on the storacha.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 storacha up
.
When uploading directories, files beginning with a .
character are ignored by default. To include hidden files instead, pass in the -H
or --hidden
flag.
View Your File with IPFS
When your upload completes, you should see a link to your files on the storacha.link
IPFS gateway. Just click the link to see your file!