CLI

The command line interface to the Storacha Network.

Getting started

Install the CLI from npm (requires Node 18 or higher):

``sh npm install -g @storacha/cli`

Login with this agent to act on behalf of the account associated with your email address:

`sh storacha login alice@example.com`

Create a new Space for storing your data and register it:

`sh storacha space create Documents # pick a good name!`

If you'd like to learn more about what is going on under the hood with w3up and its use of Spaces, UCANs, and more, check out the client README here.

Upload a file or directory:

`sh storacha up recipies.txt`

> ⚠️❗ Public Data 🌎: All data uploaded to storacha is available to anyone who requests it using the correct CID. Do not store any private or sensitive information in an unencrypted form using storacha.

> ⚠️❗ Permanent Data ♾️: Removing files from storacha will remove them from the file listing for your account, but that doesn’t prevent nodes on the decentralized storage network from retaining copies of the data indefinitely. Do not use storacha for data that may need to be permanently deleted in the future.

`Commands`

- Basics -storacha login-storacha up-storacha ls-storacha rm-storacha open-storacha whoami- Space management -storacha space add-storacha space create-storacha space ls-storacha space use-storacha space info-storacha space recover- Capability management -storacha delegation create-storacha delegation ls-storacha delegation revoke-storacha proof add-storacha proof ls- Key management -storacha key create- UCAN-HTTP Bridge -storacha bridge generate-tokens- Advanced usage -storacha can blob add-storacha can blob ls-storacha can blob rm-storacha can index add-storacha can space info^{coming soon!} -storacha can space recover^{coming soon!} -storacha can upload add-storacha can upload ls-storacha can upload rm

---

`$3`

Authenticate this agent with your email address to get access to all capabilities that had been delegated to it.

`$3`

Upload file(s) to Storacha. The IPFS Content ID (CID) for your files is calculated on your machine, and sent up along with your files. web3.storage makes your content available on the IPFS network

- --no-wrapDon't wrap input files with a directory. --H, --hiddenInclude paths that start with ".". --c, --carFile is a CAR file. ---shard-size Shard uploads into CAR files of approximately this size in bytes.

`$3`

List all the uploads registered in the current space.

- --jsonFormat as newline delimited JSON ---shards Pretty print with shards in output

`$3`

Remove an upload from the uploads listing. Note that this command does not remove the data from the IPFS network, nor does it remove it from space storage (by default).

- --shards Also remove all shards referenced by the upload from the store. Use with caution and ensure other uploads do not reference the same shards.

`$3`

Open a CID on https://storacha.link in your browser. You can also pass a CID and a path.

`bash

`opens a browser to https://storacha.link/ipfs/bafybeidluj5ub7okodgg5v6l4x3nytpivvcouuxgzuioa6vodg3xt2uqle`


storacha open bafybeidluj5ub7okodgg5v6l4x3nytpivvcouuxgzuioa6vodg3xt2uqle
opens a browser to https://storacha.link/ipfs/bafybeidluj5ub7okodgg5v6l4x3nytpivvcouuxgzuioa6vodg3xt2uqle/olizilla.png

storacha open bafybeidluj5ub7okodgg5v6l4x3nytpivvcouuxgzuioa6vodg3xt2uqle/olizilla.png


$3
Print information about the current agent.
$3
Add a space to the agent. The proof is a CAR encoded UCAN delegating capabilities over a space to _this_ agent.

proof is a filesystem path to a CAR encoded UCAN, as generated by storacha delegation create _or_ a base64 identity CID string as created by storacha delegation create --base64.

`$3`

Create a new space with an optional name.

- --access-type Access type for the space: public or private (default: public). Private spaces have restricted access and are not publicly discoverable. ---encryption-provider Encryption provider for private spaces: google-kms (default: google-kms). Only relevant when --access-type is private. ---encryption-algorithm Encryption algorithm for private spaces (default: RSA_DECRYPT_OAEP_3072_SHA256). Only relevant when --access-type is private.

Examples:

`bash

`Create a public space (default)`


storacha space create "My Documents"
Create a private space with Google KMS encryption (default)

storacha space create "Private Files" --access-type private
Create a private space with custom algorithm

storacha space create "Secure Vault" --access-type private --encryption-algorithm "RSA_DECRYPT_OAEP_4096_SHA256"


$3
List spaces known to the agent.
$3
Set the current space in use by the agent.
$3
Get information about a space (by default the current space) from the service, including
which providers the space is currently registered with.

- --spaceThe space to get information about. Defaults to the current space. ---json Format as newline delimited JSON

`$3`

Recover a space from a saved mnemonic key

`$3`

Create a delegation to the passed audience for the given abilities with the _current_ space as the resource.

- --canA capability to delegate. To specify more than one capability, use this option more than once. ---nameHuman readable name for the audience receiving the delegation. ---typeType of the audience receiving the delegation, one of: device, app, service. ---outputPath of file to write the exported delegation data to. ---base64 Format as base64 identity CID string. Useful when saving it as an environment variable.

`bash

`delegate space/info to did:key:z6M..., output as a CAR`


storacha delegation create did:key:z6M... --can space/info --output ./info.ucan
delegate admin capabilities to did:key:z6M..., output as a string

storacha delegation create did:key:z6M... --can 'space/' --can 'upload/' --can 'filecoin/*' --base64
delegate write (not remove) capabilities to did:key:z6M..., output as a string

storacha delegation create did:key:z6M... \
  --can 'space/blob/add' \
  --can 'space/index/add' \
  --can 'upload/add' \
  --can 'filecoin/offer' \
  --base64


$3
List delegations created by this agent for others.

- --json Format as newline delimited JSON

`$3`

Revoke a delegation by CID.

- --proof Name of a file containing the delegation and any additional proofs needed to prove authority to revoke

`$3`

Add a proof delegated to this agent. The proof is a CAR encoded delegation to _this_ agent. Note: you probably want to use storacha space add unless you know the delegation you received targets a resource _other_ than a space.

`$3`

List proofs of delegated capabilities. Proofs are delegations with an audience matching the agent DID.

- --json Format as newline delimited JSON

`$3`

Print a new key pair. Does not change your current signing key

- --json Export as dag-json

`$3`

Generate tokens that can be used as the X-Auth-Secret and Authorization headers required to use the UCAN-HTTP bridge.

See the UCAN Bridge specification for more information on how these are expected to be used.

- --canOne or more abilities to delegate. ---expirationUnix timestamp (in seconds) when the delegation is no longer valid. Zero indicates no expiration. ---json If set, output JSON suitable to splat into the headers field of a fetch request.

`$3`

Store a blob file to the service.

`$3`

List blobs in the current space.

- --jsonFormat as newline delimited JSON ---sizeThe desired number of results to return ---cursor An opaque string included in a prior upload/list response that allows the service to provide the next "page" of results

`$3`

Remove a blob from the store by base58btc encoded multihash.

`$3`

Register an upload - a DAG with the given root data CID that is stored in the given shard(s), identified by CID.

`$3`

List uploads in the current space.

- --jsonFormat as newline delimited JSON ---shardsPretty print with shards in output ---sizeThe desired number of results to return ---cursorAn opaque string included in a prior upload/list response that allows the service to provide the next "page" of results ---pre If true, return the page of results preceding the cursor

`$3`

Remove an upload from the current space's upload list. Does not remove blobs from the store.

`Environment Variables`

`$3`

Set the key storacha CLI should use to sign ucan invocations. By default storacha CLI will generate a new Ed25519 key on first run and store it. Set it along with a custom STORACHA_STORE_NAME to manage multiple custom keys and profiles. Trying to use an existing store with different keys will fail.

You can generate Ed25519 keys with storacha key create.

Usage

`bash STORACHA_PRINCIPAL=$(storacha key create --json | jq -r .key) STORACHA_STORE_NAME="other" storacha whoami did:key:z6Mkf7bvSNgoXk67Ubhie8QMurN9E4yaCCGBzXow78zxnmuB`

Default _unset_, a random Ed25519 key is generated.

`$3`

Allows you to use the storacha CLI with different profiles. You could use it to log in with different emails and keep the delegations separate.

storacha CLI stores state to disk using the conf module. STORACHA_STORE_NAME sets the conf configName option.

Default storacha-cli

`$3`

storachaCLI will use the w3up service at https://up.storacha.network. If you would like to use a different w3up-compatible service, setSTORACHA_SERVICE_DID and STORACHA_SERVICE_URL environment variables to set the service DID and URL endpoint.

Default https://up.storacha.network

`$3`

storacha CLI will use the w3up did:web:up.storacha.networkas the service DID. If you would like to use a different w3up-compatible service, setSTORACHA_SERVICE_DID and STORACHA_SERVICE_URL environment variables to set the service DID and URL endpoint.

Default did:web:up.storacha.network

`$3`

The URL at which UCAN receipts issued by the service may be fetched.

Default https://up.storacha.network/receipt/

`$3`

Enable collection of OTEL telemetry.

`$3`

Customise the endpoint traces are sent to.

STORACHA_TRACES_SAMPLER_ARG

Configure the sampler with a ratio between 0 and 1 (inclusive). Default: 1.

`FAQ`

`$3`

In the system default user config directory:

- macOS: ~/Library/Preferences/storacha- Windows:%APPDATA%\storacha\Config (for example, C:\Users\USERNAME\AppData\Roaming\storacha\Config) - Linux:~/.config/storacha (or $XDG_CONFIG_HOME/storacha`)

Contributing

Feel free to join in. All welcome. Please read our contributing guidelines and/or open an issue!

License

Dual-licensed under MIT + Apache 2.0

CLI

The command line interface to the Storacha Network.

Getting started

Install the CLI from npm (requires Node 18 or higher):

``sh npm install -g @storacha/cli`

Login with this agent to act on behalf of the account associated with your email address:

`sh storacha login alice@example.com`

Create a new Space for storing your data and register it:

`sh storacha space create Documents # pick a good name!`

If you'd like to learn more about what is going on under the hood with w3up and its use of Spaces, UCANs, and more, check out the client README here.

Upload a file or directory:

`sh storacha up recipies.txt`

`Commands`

---

`$3`

Authenticate this agent with your email address to get access to all capabilities that had been delegated to it.

`$3`

Upload file(s) to Storacha. The IPFS Content ID (CID) for your files is calculated on your machine, and sent up along with your files. web3.storage makes your content available on the IPFS network

`$3`

List all the uploads registered in the current space.

- --jsonFormat as newline delimited JSON ---shards Pretty print with shards in output

`$3`

Remove an upload from the uploads listing. Note that this command does not remove the data from the IPFS network, nor does it remove it from space storage (by default).

- --shards Also remove all shards referenced by the upload from the store. Use with caution and ensure other uploads do not reference the same shards.

`$3`

Open a CID on https://storacha.link in your browser. You can also pass a CID and a path.

`bash

`opens a browser to https://storacha.link/ipfs/bafybeidluj5ub7okodgg5v6l4x3nytpivvcouuxgzuioa6vodg3xt2uqle`


storacha open bafybeidluj5ub7okodgg5v6l4x3nytpivvcouuxgzuioa6vodg3xt2uqle
opens a browser to https://storacha.link/ipfs/bafybeidluj5ub7okodgg5v6l4x3nytpivvcouuxgzuioa6vodg3xt2uqle/olizilla.png

storacha open bafybeidluj5ub7okodgg5v6l4x3nytpivvcouuxgzuioa6vodg3xt2uqle/olizilla.png


$3
Print information about the current agent.
$3
Add a space to the agent. The proof is a CAR encoded UCAN delegating capabilities over a space to _this_ agent.

proof is a filesystem path to a CAR encoded UCAN, as generated by storacha delegation create _or_ a base64 identity CID string as created by storacha delegation create --base64.

`$3`

Create a new space with an optional name.

Examples:

`bash

`Create a public space (default)`


storacha space create "My Documents"
Create a private space with Google KMS encryption (default)

storacha space create "Private Files" --access-type private
Create a private space with custom algorithm

storacha space create "Secure Vault" --access-type private --encryption-algorithm "RSA_DECRYPT_OAEP_4096_SHA256"


$3
List spaces known to the agent.
$3
Set the current space in use by the agent.
$3
Get information about a space (by default the current space) from the service, including
which providers the space is currently registered with.

- --spaceThe space to get information about. Defaults to the current space. ---json Format as newline delimited JSON

`$3`

Recover a space from a saved mnemonic key

`$3`

Create a delegation to the passed audience for the given abilities with the _current_ space as the resource.

`bash

`delegate space/info to did:key:z6M..., output as a CAR`


storacha delegation create did:key:z6M... --can space/info --output ./info.ucan
delegate admin capabilities to did:key:z6M..., output as a string

storacha delegation create did:key:z6M... --can 'space/' --can 'upload/' --can 'filecoin/*' --base64
delegate write (not remove) capabilities to did:key:z6M..., output as a string

storacha delegation create did:key:z6M... \
  --can 'space/blob/add' \
  --can 'space/index/add' \
  --can 'upload/add' \
  --can 'filecoin/offer' \
  --base64


$3
List delegations created by this agent for others.

- --json Format as newline delimited JSON

`$3`

Revoke a delegation by CID.

- --proof Name of a file containing the delegation and any additional proofs needed to prove authority to revoke

`$3`

List proofs of delegated capabilities. Proofs are delegations with an audience matching the agent DID.

- --json Format as newline delimited JSON

`$3`

Print a new key pair. Does not change your current signing key

- --json Export as dag-json

`$3`

Generate tokens that can be used as the X-Auth-Secret and Authorization headers required to use the UCAN-HTTP bridge.

See the UCAN Bridge specification for more information on how these are expected to be used.

`$3`

Store a blob file to the service.

`$3`

List blobs in the current space.

`$3`

Remove a blob from the store by base58btc encoded multihash.

`$3`

Register an upload - a DAG with the given root data CID that is stored in the given shard(s), identified by CID.

`$3`

List uploads in the current space.

`$3`

Remove an upload from the current space's upload list. Does not remove blobs from the store.

`Environment Variables`

`$3`

You can generate Ed25519 keys with storacha key create.

Usage

`bash STORACHA_PRINCIPAL=$(storacha key create --json | jq -r .key) STORACHA_STORE_NAME="other" storacha whoami did:key:z6Mkf7bvSNgoXk67Ubhie8QMurN9E4yaCCGBzXow78zxnmuB`

Default _unset_, a random Ed25519 key is generated.

`$3`

Allows you to use the storacha CLI with different profiles. You could use it to log in with different emails and keep the delegations separate.

storacha CLI stores state to disk using the conf module. STORACHA_STORE_NAME sets the conf configName option.

Default storacha-cli

`$3`

Default https://up.storacha.network

`$3`

Default did:web:up.storacha.network

`$3`

The URL at which UCAN receipts issued by the service may be fetched.

Default https://up.storacha.network/receipt/

`$3`

Enable collection of OTEL telemetry.

`$3`

Customise the endpoint traces are sent to.

STORACHA_TRACES_SAMPLER_ARG

Configure the sampler with a ratio between 0 and 1 (inclusive). Default: 1.

`FAQ`

`$3`

In the system default user config directory:

Contributing

Feel free to join in. All welcome. Please read our contributing guidelines and/or open an issue!

License

Dual-licensed under MIT + Apache 2.0