# sonrctl 🚀 **Blazingly fast CLI for managing Sonr blockchain nodes, validators, and networks** Built with [Bun](https://bun.sh) - the all-in-one JavaScript runtime. ## Features - ⚡ **Blazingly Fast** - Built on Bun for instant startup and execution - 🎯 **Simple API** - Clean, intuitive commands for node management - 🐳 **Docker Integration** - Seamless container orchestration for testnets - 💾 **SQLite Config** - Lightweight, fast configuration management - 🎨 **Beautiful Output** - Colored, formatted CLI output - 🔧 **Node Management** - Initialize, start, stop, and monitor nodes - 🌐 **Network Operations** - Full testnet deployment and management ## Installation ### Install Bun (if not already installed) ```bash curl -fsSL https://bun.sh/install | bash ``` ### Install sonrctl ```bash # Clone the repository git clone https://github.com/sonr-io/sonr.git cd sonr # Install dependencies bun install # Link the CLI globally bun link ``` ### Install snrd binary ```bash sonrctl install latest ``` ## Quick Start ```bash # Show help sonrctl help # Initialize a validator node sonrctl init validator val-naruto --chain-id sonrtest_1-1 # Start the entire testnet network sonrctl start network --detach # Check network status sonrctl status network # Stop the network sonrctl stop network ``` ## Commands ### `sonrctl install [version]` Install or update the snrd binary. ```bash # Install latest version sonrctl install latest # Install specific version (coming soon) sonrctl install v1.0.0 ``` ### `sonrctl init [options]` Initialize a new node configuration. **Types:** `validator`, `sentry`, `full` **Options:** - `--chain-id ` - Chain ID (default: sonrtest_1-1) - `--home ` - Home directory (default: ~/.sonr/) - `--rpc-port ` - RPC port (default: 26657) - `--rest-port ` - REST API port (default: 1317) - `--grpc-port ` - gRPC port (default: 9090) - `--grpc-web-port ` - gRPC-Web port (default: 9091) - `--json-rpc-port ` - JSON-RPC port (default: 8545) - `--json-rpc-ws-port ` - JSON-RPC WebSocket port (default: 8546) **Examples:** ```bash # Initialize a validator sonrctl init validator val-naruto # Initialize a sentry with custom home sonrctl init sentry sentry-naruto --home ~/.sonr/custom-sentry # Initialize with custom ports sonrctl init validator my-val --rpc-port 26658 --rest-port 1318 ``` ### `sonrctl start [options]` Start a node or the entire network. **Targets:** - `` - Start a specific registered node - `network` - Start the entire testnet using docker-compose **Options:** - `--detach`, `-d` - Run in background (network only) **Examples:** ```bash # Start a specific node sonrctl start val-naruto # Start network in foreground sonrctl start network # Start network in background sonrctl start network --detach ``` ### `sonrctl stop ` Stop a node, network, or all containers. **Targets:** - `` - Stop a specific container - `network` - Stop the entire testnet - `all` - Stop all running containers **Examples:** ```bash # Stop a specific node sonrctl stop val-naruto # Stop the network sonrctl stop network # Stop all containers sonrctl stop all ``` ### `sonrctl status [target]` Check status of nodes and network. **Targets:** - (none) - Show overall status - `` - Show specific node status - `network` - Show network status **Examples:** ```bash # Show overall status sonrctl status # Show specific node status sonrctl status val-naruto # Show network status sonrctl status network ``` ### `sonrctl config [args]` Manage sonrctl configuration. **Commands:** - `list` - List all configuration - `get ` - Get a specific value - `set ` - Set a configuration value **Examples:** ```bash # List all configuration sonrctl config list # Get chain ID sonrctl config get chain_id # Set home directory sonrctl config set home ~/.sonr-custom ``` ## Configuration sonrctl stores its configuration in: - **Config Database:** `~/.config/sonr/config.db` - **Node Home:** `~/.sonr/` (default) The SQLite database stores: - Global configuration (chain ID, binary path, etc.) - Registered nodes - Node metadata ## Project Structure ``` src/ ├── index.ts # Main CLI entry point ├── types.ts # TypeScript type definitions ├── commands/ # Command implementations │ ├── install.ts # Install snrd binary │ ├── init.ts # Initialize nodes │ ├── start.ts # Start nodes/network │ ├── stop.ts # Stop nodes/network │ ├── status.ts # Check status │ └── config.ts # Configuration management └── lib/ # Utility libraries ├── constants.ts # Constants and defaults ├── logger.ts # Beautiful logging ├── config.ts # SQLite configuration manager ├── toml.ts # TOML file utilities ├── docker.ts # Docker operations └── node.ts # Node operations ``` ## Architecture sonrctl is built with a clean, modular architecture: 1. **Command Layer** - Handles user input and command routing 2. **Library Layer** - Provides utilities for common operations 3. **Storage Layer** - SQLite database for configuration persistence ### Key Design Decisions - **Bun Runtime** - For blazingly fast execution and built-in tools - **SQLite Storage** - Lightweight, fast, and portable - **No External Dependencies** - Minimal deps, maximum performance - **Clean Separation** - Commands, libraries, and utilities are separate - **Type Safety** - Full TypeScript support ## Docker Integration sonrctl integrates seamlessly with Docker for testnet deployment: - Start/stop docker-compose networks - Manage individual containers - Monitor container status - Execute commands in containers - View container logs The CLI can work as a drop-in replacement for manual docker-compose operations. ## Development ### Prerequisites - [Bun](https://bun.sh) v1.0+ - Docker (for network operations) - Git ### Running Locally ```bash # Run directly with Bun bun run src/index.ts help # Run a specific command bun run src/index.ts status ``` ### Adding New Commands 1. Create a new file in `src/commands/` 2. Export an async function that takes `args: string[]` 3. Import and add to the switch statement in `src/index.ts` 4. Update the help text Example: ```typescript // src/commands/mycommand.ts export async function mycommand(args: string[]) { Logger.header('My Command'); // Implementation } // src/index.ts import { mycommand } from './commands/mycommand'; // Add to switch statement case 'mycommand': await mycommand(commandArgs); break; ``` ## Examples ### Setting Up a Testnet ```bash # 1. Install the binary sonrctl install # 2. Start the testnet network sonrctl start network --detach # 3. Check status sonrctl status network # 4. View logs docker logs -f val-naruto # 5. Stop when done sonrctl stop network ``` ### Creating a Custom Node ```bash # 1. Initialize a custom validator sonrctl init validator my-validator \ --chain-id mychain-1 \ --home ~/.sonr/my-validator \ --rpc-port 26667 # 2. Configure genesis (manual step) # Edit ~/.sonr/my-validator/config/genesis.json # 3. Start the node sonrctl start my-validator # 4. Check status sonrctl status my-validator ``` ## Troubleshooting ### Command not found ```bash # Make sure Bun's bin directory is in your PATH export PATH="$HOME/.bun/bin:$PATH" # Re-link the CLI bun link ``` ### Docker permission denied ```bash # Add your user to the docker group sudo usermod -aG docker $USER # Log out and back in, or run: newgrp docker ``` ### Binary not found after install ```bash # Check if ~/.local/bin is in your PATH export PATH="$HOME/.local/bin:$PATH" # Add to your shell profile echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc ``` ## Contributing Contributions are welcome! Please: 1. Fork the repository 2. Create a feature branch 3. Make your changes 4. Add tests if applicable 5. Submit a pull request ## License Apache 2.0 - See LICENSE file for details ## Links - [Sonr Network](https://sonr.io) - [Documentation](https://docs.sonr.io) - [GitHub](https://github.com/sonr-io/sonr) - [Bun](https://bun.sh) --- **Built with ❤️ using Bun**