@stoar/cli/README.md

CLI tool for STOAR - decentralized file storage on Arweave

# @stoar/cli

CLI tool for STOAR - decentralized file storage on Arweave.

## Installation

```bash
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:

```bash
# 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

```bash
# 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

```bash
# 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

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

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

### Configuration

```bash
# 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

```bash
# Install dependencies
bun install

# Build
bun run build

# Run tests
bun run test

# Development mode
bun run dev
```

## License

MIT