@storacha/cli
v1.1.0
Published
Command Line Interface to the Storacha Network
Downloads
122
Readme
CLI
The command line interface to the Storacha Network.
Getting started
Install the CLI from npm (requires Node 18 or higher):
npm install -g @storacha/cli
Login with this agent to act on behalf of the account associated with your email address:
storacha login [email protected]
Create a new Space for storing your data and register it:
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:
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
- Space management
- Capability management
- Key management
- UCAN-HTTP Bridge
- Advanced usage
storacha login <email>
Authenticate this agent with your email address to get access to all capabilities that had been delegated to it.
storacha up <path> [path...]
Upload file(s) to web3.storage. 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-wrap
Don't wrap input files with a directory.-H, --hidden
Include paths that start with ".".-c, --car
File is a CAR file.--shard-size
Shard uploads into CAR files of approximately this size in bytes.--concurrent-requests
Send up to this many CAR shards concurrently.
storacha ls
List all the uploads registered in the current space.
--json
Format as newline delimited JSON--shards
Pretty print with shards in output
storacha rm <root-cid>
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.
storacha open <cid>
Open a CID on https://w3s.link in your browser. You can also pass a CID and a path.
# opens a browser to https://w3s.link/ipfs/bafybeidluj5ub7okodgg5v6l4x3nytpivvcouuxgzuioa6vodg3xt2uqle
storacha open bafybeidluj5ub7okodgg5v6l4x3nytpivvcouuxgzuioa6vodg3xt2uqle
# opens a browser to https://w3s.link/ipfs/bafybeidluj5ub7okodgg5v6l4x3nytpivvcouuxgzuioa6vodg3xt2uqle/olizilla.png
storacha open bafybeidluj5ub7okodgg5v6l4x3nytpivvcouuxgzuioa6vodg3xt2uqle/olizilla.png
storacha whoami
Print information about the current agent.
storacha space add <proof>
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
.
storacha space create [name]
Create a new space with an optional name.
storacha space ls
List spaces known to the agent.
storacha space use <did>
Set the current space in use by the agent.
storacha space info
Get information about a space (by default the current space) from the service, including which providers the space is currently registered with.
--space
The space to get information about. Defaults to the current space.--json
Format as newline delimited JSON
storacha delegation create <audience-did>
Create a delegation to the passed audience for the given abilities with the current space as the resource.
--can
A capability to delegate. To specify more than one capability, use this option more than once.--name
Human readable name for the audience receiving the delegation.--type
Type of the audience receiving the delegation, one of: device, app, service.--output
Path of file to write the exported delegation data to.--base64
Format as base64 identity CID string. Useful when saving it as an environment variable.
# 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
storacha delegation ls
List delegations created by this agent for others.
--json
Format as newline delimited JSON
storacha delegation revoke <delegation-cid>
Revoke a delegation by CID.
--proof
Name of a file containing the delegation and any additional proofs needed to prove authority to revoke
storacha proof add <proof.ucan>
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.
storacha proof ls
List proofs of delegated capabilities. Proofs are delegations with an audience matching the agent DID.
--json
Format as newline delimited JSON
storacha key create
Print a new key pair. Does not change your current signing key
--json
Export as dag-json
storacha bridge generate-tokens
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.
--can
One or more abilities to delegate.--expiration
Unix timestamp (in seconds) when the delegation is no longer valid. Zero indicates no expiration.--json
If set, output JSON suitable to splat into theheaders
field of afetch
request.
storacha can blob add [path]
Store a blob file to the service.
storacha can blob ls
List blobs in the current space.
--json
Format as newline delimited JSON--size
The 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
storacha can blob rm <multihash>
Remove a blob from the store by base58btc encoded multihash.
storacha can space info <did>
storacha can space recover <email>
storacha can upload add <root-cid> <shard-cid> [shard-cid...]
Register an upload - a DAG with the given root data CID that is stored in the given shard(s), identified by CID.
storacha can upload ls
List uploads in the current space.
--json
Format as newline delimited JSON--shards
Pretty print with shards in output--size
The 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--pre
If true, return the page of results preceding the cursor
storacha can upload rm <root-cid>
Remove an upload from the current space's upload list. Does not remove blobs from the store.
Environment Variables
STORACHA_PRINCIPAL
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
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.
STORACHA_STORE_NAME
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
STORACHA_SERVICE_URL
storacha
CLI will use the w3up service at https://upload.storacha.network. If you would like
to use a different w3up-compatible service, set STORACHA_SERVICE_DID
and STORACHA_SERVICE_URL
environment variables to set the service DID and URL endpoint.
Default https://upload.storacha.network
STORACHA_SERVICE_DID
storacha
CLI will use the w3up did:web:upload.storacha.network
as the service DID. If you would like
to use a different w3up-compatible service, set STORACHA_SERVICE_DID
and STORACHA_SERVICE_URL
environment variables to set the service DID and URL endpoint.
Default did:web:upload.storacha.network
STORACHA_RECEIPTS_URL
The URL at which UCAN receipts issued by the service may be fetched.
Default https://upload.storacha.network/receipt/
FAQ
Where are my keys and delegations stored?
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