@stoar/cli

CLI tool for STOAR - decentralized file storage on Arweave.

Installation

npm install -g @stoar/cli
# or
bun add -g @stoar/cli

Configuration

The CLI requires a wallet to interact with Arweave. You can provide it in two ways:

1. Command line flag: --wallet path/to/wallet.json
2. Environment variable:
   • STOAR_WALLET_PATH=/path/to/wallet.json
   • STOAR_WALLET=<base64-encoded-wallet-json>

Keeping Up to Date

The CLI will automatically check for updates once every 24 hours and notify you when a new version is available. You can:

# Check for updates manually
stoar update --check

# Update to the latest version
stoar update

# Force update even if on latest version
stoar update --force

# Skip automatic update checks
stoar --skip-update-check <command>

# Or set environment variable
export STOAR_SKIP_UPDATE_CHECK=true

Usage

Wallet Management

# Create a new wallet
stoar wallet create --output my-wallet.json

# Check wallet balance
stoar wallet balance --wallet my-wallet.json

# Show wallet address
stoar wallet address --wallet my-wallet.json

File Operations

# Upload a single file
stoar upload file.pdf --wallet wallet.json

# Upload with metadata
stoar upload file.pdf --name "My Document" --tags category=docs,year=2024

# Upload multiple files (automatically uses batch mode for cost savings)
stoar upload *.jpg --wallet wallet.json

# Upload entire directory with glob patterns
stoar upload "images/**/*.png" --wallet wallet.json

# Force batch mode even for single file
stoar upload file.pdf --batch --wallet wallet.json

# Download a file
stoar download <transaction-id> --output downloaded-file.pdf

Query Files

# List your uploads
stoar list --wallet wallet.json

# List with filters
stoar list --tags type=image --limit 50

Configuration

# Set default gateway
stoar config set gateway https://arweave.net

# View configuration
stoar config get

# Reset configuration
stoar config reset

Output Formats

All commands support different output formats:

• --json - Output results in JSON format
• --quiet - Only output essential information
• --verbose - Show detailed output

Current Features

Core Functionality

• ✅ File upload/download with progress indicators
• ✅ Automatic batch mode for multiple files (90%+ cost savings)
• ✅ Directory uploads with glob patterns
• ✅ Wallet management (create, balance, address)
• ✅ Transaction querying with GraphQL
• ✅ Bundle detection and parsing
• ✅ Configuration system
• ✅ Multiple output formats (JSON, quiet, verbose)
• ✅ Automatic update notifications and self-update capability

Advanced Features

• ✅ Auto-batching when uploading multiple files
• ✅ Glob pattern support for flexible file selection
• ✅ Transaction info with bundle content display
• ✅ Tag-based filtering for queries
• ✅ Cross-runtime support (Node.js and Bun)

Upcoming Features

Phase 2 (In Progress)

• Enhanced batch commands (create, add, status, commit)
• Cost estimation before upload
• Resume interrupted uploads

Phase 3

• S3-compatible commands
• Static website deployment
• Real-time monitoring
• Deploy command for websites

Phase 4

• Interactive mode with prompts
• Enhanced UI with charts
• Advanced error recovery

Development

# Install dependencies
bun install

# Build
bun run build

# Run tests
bun run test

# Development mode
bun run dev

License

MIT