aleph-client

The official command-line interface (CLI) for Aleph Cloud — a decentralized cloud computing platform.

What is Aleph Cloud?

Aleph Cloud provides decentralized computing, storage, and indexing services. With aleph-client, you can:

• Deploy VMs (Instances) — Run persistent virtual machines on decentralized infrastructure
• Deploy Functions (Programs) — Deploy serverless functions that scale automatically
• Store Data — Upload files and data to decentralized storage
• Send Messages — Post, aggregate, and forget messages on the Aleph network
• Manage Domains — Configure custom domains for your deployments

Quick Start

Installation

# Install from PyPI
pip install aleph-client

# Verify installation
aleph --help

Create Your First Instance

# Create a new account (generates keys)
aleph account create

# Deploy an Ubuntu instance with pay-as-you-go credits
aleph instance create --payment-type=credit --name="my-first-vm"

# List your instances
aleph instance list

# SSH into your instance
ssh root@<ipv6-address>

Deploy a Serverless Function

# Create a simple FastAPI app
mkdir my-app && cd my-app
cat > main.py << 'EOF'
from fastapi import FastAPI
app = FastAPI()

@app.get("/")
def hello():
    return {"message": "Hello from Aleph Cloud!"}
EOF

# Deploy it
aleph program upload . main:app --name="my-function"

Store Data

# Upload a file
aleph file upload myfile.txt

# Pin existing content by hash
aleph file pin QmYourContentHash

Commands Overview

Run aleph <command> --help for detailed usage of each command.

Payment Options

Aleph Cloud supports multiple payment methods:

• Credits (Pay-as-you-go) — No token staking required, pay only for what you use
• Hold — Stake ALEPH tokens for allocation
• Superfluid — Stream payments for continuous services
• NFT — Use NFT vouchers for payment

Documentation

• Full Documentation: https://docs.aleph.cloud/devhub/sdks-and-tools/aleph-cli/
• API Reference: https://docs.aleph.cloud/devhub/api/
• Tutorials: https://docs.aleph.cloud/devhub/tutorials/

Requirements

Linux

apt-get install -y python3-pip libsecp256k1-dev squashfs-tools

macOS

brew tap cuber/homebrew-libsecp256k1
brew install libsecp256k1

Windows

We recommend using WSL (Windows Subsystem for Linux).

Using Docker

Run the CLI without installing locally:

docker run --rm -ti -v $(pwd)/data:/data ghcr.io/aleph-im/aleph-client/aleph-client:master --help

Note: This uses an ephemeral key pair that is discarded when the container stops.

Development

Setup

We use hatch for development:

pip install hatch

Running Tests

hatch test
# or with coverage
hatch run testing:cov

Code Quality

# Format code
hatch run linting:fmt

# Type checking
hatch run linting:typing

Publishing

hatch build
hatch upload

Additional Chains

For NULS2 support:

pip install aleph-sdk-python[nuls2]

Contributing

Contributions are welcome! Please see our contribution guidelines and open a pull request.

Links

• Website: https://aleph.cloud
• Documentation: https://docs.aleph.cloud
• GitHub: https://github.com/aleph-im
• Discord: https://discord.gg/aleph-im
• Twitter: https://twitter.com/alaboratory

License

MIT License - see LICENSE for details.