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:

1. Installing the CLI tool
2. Creating and provisioning your first space
3. Uploading a file or directory
4. 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

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!