npm package: @sonr.io/cli
Description: Sonr installation CLI tool
Author: Sonr Team
Latest version: 0.2.8

# @sonr.io/install

A streamlined CLI tool for installing the Sonr blockchain daemon (`snrd`) and WebAssembly runtime (`motr.wasm`) on your system.

## Overview

`@sonr.io/install` provides a simple, interactive installation experience for the Sonr blockchain tools. The installer automatically detects your operating system and architecture, downloads the appropriate binaries, and configures them for immediate use.

## Features

- **Automatic platform detection** - Supports Darwin (macOS) and Linux on x64 and arm64 architectures
- **Multiple installation options** - Install to user directory, system-wide, or current directory
- **Version management** - Install the latest release or build from source
- **CDN fallback** - Primary CDN with automatic GitHub fallback for reliability
- **Interactive prompts** - User-friendly CLI experience with progress indicators
- **PATH configuration** - Automatic PATH update instructions

## Requirements

### System Requirements

- **Node.js**: v20.0.0 or higher
- **Operating System**: macOS or Linux (Windows not supported)
- **Architecture**: x64 (amd64) or arm64

### Build Requirements (for source installation)

- **Go**: Latest version
- **Make**: GNU Make
- **Git**: For cloning the repository

## Installation

### Quick Start

Install and run the installer directly using npx:

```bash
npx @sonr.io/install
```

### Install as Global Package

```bash
npm install -g @sonr.io/install
sonr-install
```

### Build from Repository

If you want to install from source, first clone the repository:

```bash
git clone https://github.com/sonr-io/sonr.git
cd sonr
npx @sonr.io/install
```

## Usage

### Interactive Installation

Run the installer to start the interactive installation process:

```bash
npx @sonr.io/install
```

The installer will guide you through:

1. **Installation location selection**:
   - User directory (`~/.local/bin`) - Recommended for personal use
   - System-wide (`/usr/local/bin`) - Requires sudo permissions
   - Current directory - For portable installations

2. **Version selection**:
   - Latest release version
   - Build from source (if in repository)

3. **Confirmation and installation**:
   - Downloads binaries from CDN or GitHub
   - Sets appropriate permissions
   - Verifies installation

### Post-Installation

After installation, the tool provides:

- Installation verification with version information
- PATH configuration instructions (if needed)
- Available command reference

## API Reference

### Core Functions

#### `detectPlatform()`

Detects the current operating system and architecture.

**Returns:**
- `osName`: Normalized OS name (`darwin`, `linux`, `windows`)
- `archName`: Normalized architecture (`amd64`, `arm64`)

**Throws:**
- Error if platform is unsupported

#### `getLatestVersion()`

Fetches the latest release version from GitHub API.

**Returns:**
- `string | null`: Version number without 'v' prefix, or null if not found

#### `downloadBinary(url, destination, fallbackUrl?)`

Downloads a binary file with automatic fallback support.

**Parameters:**
- `url`: Primary download URL (CDN)
- `destination`: Local file path for saving
- `fallbackUrl`: Optional GitHub release URL for fallback

**Throws:**
- Error if both primary and fallback downloads fail

#### `buildLocally(installDir)`

Builds Sonr binaries from source code.

**Parameters:**
- `installDir`: Directory to install built binaries

**Requirements:**
- Must be run from repository root
- Requires `make` and `go` commands

#### `installBinaries(installDir, version, buildFromSource)`

Main installation orchestrator that handles both download and build workflows.

**Parameters:**
- `installDir`: Target installation directory
- `version`: Version string or null for source build
- `buildFromSource`: Boolean flag for source compilation

## Binary Locations

The installer uses a two-tier download strategy:

### Primary CDN
```
https://dl.sonr.io/v{version}/snrd_{os}_{arch}
https://dl.sonr.io/v{version}/motr.wasm
```

### GitHub Fallback
```
https://github.com/sonr-io/sonr/releases/download/v{version}/snrd_{os}_{arch}
https://github.com/sonr-io/sonr/releases/download/v{version}/motr.wasm
```

## Installed Components

After successful installation, you'll have:

### snrd
The Sonr blockchain daemon - the core node software for running Sonr blockchain nodes.

**Common commands:**
- `snrd init` - Initialize a new node
- `snrd start` - Start the blockchain node
- `snrd version` - Display version information
- `snrd --help` - Show all available commands

### motr.wasm
WebAssembly runtime module for secure execution of motor plugins.

## Troubleshooting

### Common Issues

#### "No releases found and cannot build locally"
- **Solution**: Clone the repository first or ensure you have internet connectivity

#### "make is required to build from source"
- **Solution**: Install build tools for your platform
  - macOS: `xcode-select --install`
  - Linux: `sudo apt-get install build-essential`

#### "Windows is not supported"
- **Solution**: Use WSL (Windows Subsystem for Linux) or a virtual machine

#### PATH not updated
- **Solution**: Add the installation directory to your PATH:
  ```bash
  echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
  source ~/.bashrc
  ```

### Verification

Verify successful installation:

```bash
snrd version
```

## Development

### Project Structure

```
cli/install/
├── src/
│   └── index.ts        # Main installer logic
├── dist/               # Compiled JavaScript (generated)
├── package.json        # Package configuration
├── tsconfig.json       # TypeScript configuration
└── CHANGELOG.md        # Version history
```

### Scripts

```bash
# Build the TypeScript source
pnpm build

# Watch mode for development
pnpm dev

# Clean build artifacts
pnpm clean

# Run linting
pnpm lint

# Format code
pnpm format

# Run tests
pnpm test
```

### Dependencies

- **@clack/prompts**: Interactive CLI prompts
- **picocolors**: Terminal output coloring

## Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests and linting
5. Submit a pull request

## License

MIT - See the [LICENSE](../../LICENSE) file for details.

## Support

For issues, questions, or suggestions:

- **GitHub Issues**: [sonr-io/sonr](https://github.com/sonr-io/sonr/issues)
- **Documentation**: [Sonr Docs](https://sonr.dev)

## Changelog

See [CHANGELOG.md](./CHANGELOG.md) for version history and release notes.