Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@stoar/cli) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@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:

Command line flag: --wallet path/to/wallet.json
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