Programmatic CLI Usage

Use Storacha from any programming language by calling the CLI as a subprocess.

This guide shows how to integrate Storacha into any programming language (Python, Rust, PHP, Ruby, Java, etc.) by using the CLI with delegated credentials. No interactive login required.

Overview

The approach is:

1. One-time setup (by account owner): Create a signing key and delegation
2. Server setup (one-time): Import the delegation using environment variables
3. Runtime: Call the CLI as a subprocess from your application

Prerequisites

• Node.js 18 or higher installed on your server
• The Storacha CLI: npm install -g @storacha/cli

One-Time Setup (Account Owner)

Someone with access to your Storacha account needs to create credentials. This only needs to be done once.

1. Generate a key pair for your server

storacha key create --json

Output:

{
  "did": "did:key:z6MkjK9yatoy1KGgRecYgRnqWJFcjMEBXAnLfoEpx1WCE158",
  "key": "MgCY2h0V5s7B+Yz5Rn2x4aVkAIyPM4h+/TqSfFqHHm+JN0e0BSDbtA9G2D2acXLY0OLjJMzeJVbLAzolaim97YJEHkkc="
}

Save both values:

• did - The public identifier for your server
• key - The private key (keep this secret!)

2. Create a delegation for the server

The account owner (who is logged in) creates a delegation:

# Replace <SERVER_DID> with the `did` value from step 1
storacha delegation create <SERVER_DID> \
  --can 'space/*' \
  --can 'upload/*' \
  --can 'blob/*' \
  --output delegation.ucan

3. Transfer credentials to your server

Securely transfer to your server:

• The delegation.ucan file
• The private key value

Server Setup (One-Time)

On your server, import the delegation. No login required.

# Set environment variables
export STORACHA_PRINCIPAL="<PRIVATE_KEY>"
export STORACHA_STORE_NAME="my-server"
 
# Import the space from the delegation
storacha space add delegation.ucan

This registers the space with your server's CLI profile. You only need to do this once.

Upload Files

Now you can upload files programmatically:

export STORACHA_PRINCIPAL="<PRIVATE_KEY>"
export STORACHA_STORE_NAME="my-server"
 
storacha up /path/to/file.txt

Output:

1 file 0.1KB
Stored 1 file
https://storacha.link/ipfs/bafybeia7izi43t7pq7jc77oru6a4e7d7o636c4y3rgbjtgrb24ytp7f6ve

Language Examples

import subprocess
import os
import json
 
# Set credentials
os.environ["STORACHA_PRINCIPAL"] = "<PRIVATE_KEY>"
os.environ["STORACHA_STORE_NAME"] = "my-server"
 
def upload_file(filepath):
    """Upload a file and return the CID."""
    result = subprocess.run(
        ["storacha", "up", filepath, "--json"],
        capture_output=True,
        text=True,
        check=True
    )
    data = json.loads(result.stdout)
    return data["root"]["/"]
 
def list_uploads():
    """List all uploads as JSON."""
    result = subprocess.run(
        ["storacha", "ls", "--json"],
        capture_output=True,
        text=True,
        check=True
    )
    return result.stdout
 
def remove_upload(cid):
    """Remove an upload by CID."""
    result = subprocess.run(
        ["storacha", "rm", cid],
        capture_output=True,
        text=True,
        check=True
    )
    return result.returncode == 0
 
# Example usage
if __name__ == "__main__":
    cid = upload_file("myfile.txt")
    print(f"Uploaded: https://storacha.link/ipfs/{cid}")

Available Commands

Environment Variables

Security Best Practices

1. Never commit credentials - Use environment variables or secrets management
2. Limit capabilities - Only delegate what's needed for your use case
3. Use separate keys - Different keys for different environments (dev, staging, prod)

Troubleshooting

"No space selected"

Run storacha space add delegation.ucan to import the space from your delegation.

"Capability not authorized"

Ensure your delegation includes the required capabilities. Check with:

storacha proof ls

Command not found

Ensure the CLI is installed globally:

npm install -g @storacha/cli

See Also

• CLI Reference - Full CLI documentation
• Upload from CI - CI/CD specific guide
• Go Client - Native Go implementation