From 56dbf1fcaad626df627d2aa5a4704ca52a8fb7db Mon Sep 17 00:00:00 2001 From: razyfriday-dev Date: Tue, 12 May 2026 09:17:37 +0100 Subject: [PATCH 1/2] Add comprehensive configuration guide --- docs/CONFIGURATION.md | 190 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 190 insertions(+) create mode 100644 docs/CONFIGURATION.md diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md new file mode 100644 index 00000000..b2558cd2 --- /dev/null +++ b/docs/CONFIGURATION.md @@ -0,0 +1,190 @@ +# Configuration Guide + +The Hostinger API CLI (`hapi`) can be configured in multiple ways. This guide explains all configuration options and methods. + +## Configuration Methods + +The CLI supports three configuration methods (in order of precedence): + +1. **Command-line flags** - Highest priority +2. **Environment variables** - Medium priority +3. **Configuration file** - Lowest priority + +## Configuration File + +By default, the CLI reads configuration from `$HOME/.hapi.yaml`. + +### Specifying a Custom Configuration File + +Use the `--config` flag to specify a custom configuration file location: + +```bash +hapi --config /path/to/custom-config.yaml vps vm list +``` + +### Configuration File Format + +The configuration file is in YAML format. Here's a complete example: + +```yaml +# API Authentication +api_token: your_api_token_here + +# API Endpoint (optional) +api_url: https://api.hostinger.com + +# Default output format (json|table|tree) +output_format: table + +# Request timeout in seconds (optional) +request_timeout: 30 + +# Enable verbose logging (optional) +verbose: false + +# Debug mode (optional) +debug: false +``` + +## Environment Variables + +All configuration file properties can be set via environment variables with the `HAPI_` prefix in UPPERCASE. + +### Available Environment Variables + +| Configuration Key | Environment Variable | Type | Description | +|---|---|---|---| +| `api_token` | `HAPI_API_TOKEN` | string | Your Hostinger API token (required) | +| `api_url` | `HAPI_API_URL` | string | Hostinger API endpoint (optional) | +| `output_format` | `HAPI_OUTPUT_FORMAT` | string | Default output format: json, table, or tree | +| `request_timeout` | `HAPI_REQUEST_TIMEOUT` | integer | Request timeout in seconds | +| `verbose` | `HAPI_VERBOSE` | boolean | Enable verbose output | +| `debug` | `HAPI_DEBUG` | boolean | Enable debug mode | + +### Example: Using Environment Variables + +```bash +export HAPI_API_TOKEN=your_api_token_here +export HAPI_OUTPUT_FORMAT=json +hapi vps vm list +``` + +## Command-Line Flags + +Use flags to override configuration file and environment variable settings. + +### Global Flags + +```bash +hapi --config # Specify configuration file location +hapi --format # Set output format (json|table|tree) +hapi -h, --help # Show help information +``` + +### Example: Using Flags + +```bash +# Use JSON output format +hapi --format json vps vm list + +# Use custom config file and JSON output +hapi --config ~/custom-config.yaml --format json vps vm list +``` + +## Configuration Priority Example + +```bash +# Configuration file: /etc/hapi/config.yaml +# - output_format: table +# - api_token: from_config_file + +# Environment variable: +# - HAPI_OUTPUT_FORMAT=json + +# Command: +hapi --format tree vps vm list + +# Result: tree format is used (highest priority) +``` + +## Output Formats + +The CLI supports three output formats: + +### Table Format (Default) +``` +ID NAME STATUS RAM CPU +----- ----------- ------ --- --- +12345 my-server active 4GB 2 +``` + +### JSON Format +```json +{ + "id": 12345, + "name": "my-server", + "status": "active", + "ram": "4GB", + "cpu": 2 +} +``` + +### Tree Format +``` +my-server (ID: 12345) +├── status: active +├── ram: 4GB +└── cpu: 2 +``` + +## Best Practices + +1. **Security**: Store API tokens securely + - Never commit `hapi.yaml` to version control + - Use environment variables in CI/CD pipelines + - Restrict file permissions: `chmod 600 ~/.hapi.yaml` + +2. **Organization**: Use separate config files for different environments + ```bash + hapi --config ~/.hapi.production.yaml ... + hapi --config ~/.hapi.staging.yaml ... + ``` + +3. **Default Format**: Set your preferred output format in the config file + ```yaml + output_format: json + ``` + +4. **Documentation**: Document your configuration approach for your team + +## Getting Your API Token + +To obtain your API token: + +1. Log in to your Hostinger account +2. Navigate to API Management +3. Generate a new API token +4. Copy and store it securely + +## Troubleshooting + +### "Config file not found" Error +- Ensure the config file path is correct +- Check file permissions: `ls -la ~/.hapi.yaml` +- Verify the file is in YAML format + +### "Invalid API token" Error +- Verify the API token is correct in your configuration +- Check that the token has not expired +- Generate a new token if necessary + +### "Timeout" Error +- Increase `request_timeout` in configuration +- Check your network connectivity +- Verify the API endpoint is accessible + +## See Also + +- [Getting Started Guide](GETTING_STARTED.md) +- [CLI Reference](hapi.md) +- [Hostinger API Documentation](https://developers.hostinger.com) From 7feff0a6240d628227ae6a463505adb98ee44ef0 Mon Sep 17 00:00:00 2001 From: razyfriday-dev Date: Tue, 12 May 2026 09:31:39 +0100 Subject: [PATCH 2/2] Add comprehensive getting started guide --- docs/GETTING_STARTED.md | 267 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 267 insertions(+) create mode 100644 docs/GETTING_STARTED.md diff --git a/docs/GETTING_STARTED.md b/docs/GETTING_STARTED.md new file mode 100644 index 00000000..e1816ccf --- /dev/null +++ b/docs/GETTING_STARTED.md @@ -0,0 +1,267 @@ +# Getting Started with Hostinger API CLI + +Welcome to the Hostinger API Command Line Interface (`hapi`)! This guide will help you get up and running quickly. + +## Prerequisites + +- A Hostinger account with API access +- A valid API token from your Hostinger account +- Operating system: Linux, macOS, or Windows (with WSL) + +## Installation + +### Step 1: Download the Binary + +Visit the [releases page](https://github.com/razyfriday-dev/api-cli/releases) and download the latest binary for your operating system. + +#### Linux Installation + +```bash +# Download the binary +wget https://github.com/razyfriday-dev/api-cli/releases/download/v1.0.0/hapi-v1.0.0-linux-amd64.tar.gz + +# Extract the archive +tar xzf hapi-v1.0.0-linux-amd64.tar.gz + +# Move to system path +sudo mv hapi /usr/local/bin/ + +# Verify installation +hapi --version +``` + +#### macOS Installation + +```bash +# Download the binary +wget https://github.com/razyfriday-dev/api-cli/releases/download/v1.0.0/hapi-v1.0.0-darwin-amd64.tar.gz + +# Extract the archive +tar xzf hapi-v1.0.0-darwin-amd64.tar.gz + +# Move to system path +sudo mv hapi /usr/local/bin/ + +# Verify installation +hapi --version +``` + +#### Windows Installation + +1. Download `hapi-v1.0.0-windows-amd64.zip` from the releases page +2. Extract the ZIP file to a folder (e.g., `C:\Program Files\hapi`) +3. Add the folder to your system PATH environment variable +4. Open PowerShell and verify: `hapi --version` + +## Step 2: Obtain Your API Token + +1. Log in to your [Hostinger account](https://hpanel.hostinger.com) +2. Navigate to **Settings** → **API Management** (or similar) +3. Click **Generate New Token** +4. Copy the token (you'll only see it once!) +5. Store it securely + +## Step 3: Configure the CLI + +Choose one of the configuration methods below: + +### Option A: Configuration File (Recommended) + +Create `~/.hapi.yaml`: + +```bash +cat > ~/.hapi.yaml << 'EOF' +api_token: your_api_token_here +output_format: table +EOF +``` + +Set secure permissions: + +```bash +chmod 600 ~/.hapi.yaml +``` + +### Option B: Environment Variable + +```bash +export HAPI_API_TOKEN=your_api_token_here +``` + +### Option C: Command-Line Flag + +```bash +hapi --config /path/to/config.yaml vps vm list +``` + +## Step 4: Verify Configuration + +Test your setup: + +```bash +hapi vps vm list +``` + +If successful, you'll see a list of your VPS instances. + +## Common Commands + +### List Your VPS Instances + +```bash +hapi vps vm list +``` + +### Get Details About a Specific VPS + +```bash +hapi vps vm get +``` + +### View Available Data Centers + +```bash +hapi vps data-centers list +``` + +### Manage Firewall Rules + +```bash +# List firewall rules +hapi vps firewall rules list + +# Create a new rule +hapi vps firewall rules create \ + --action allow \ + --protocol tcp \ + --port 80 +``` + +### Check VPS Metrics + +```bash +hapi vps vm metrics +``` + +### Manage SSH Public Keys + +```bash +# List public keys +hapi vps public-keys list + +# Create a new public key +hapi vps public-keys create --name "my-key" --key "ssh-rsa AAAA..." + +# Attach to VPS +hapi vps public-keys attach +``` + +## Enable Shell Auto-Completion + +Auto-completion makes the CLI easier to use. See [AUTOCOMPLETE.md](AUTOCOMPLETE.md) for detailed instructions. + +### Quick Start (Bash) + +```bash +hapi completion bash | sudo tee /etc/bash_completion.d/hapi +``` + +Then reload your shell: + +```bash +exec bash +``` + +## Output Formats + +The CLI supports multiple output formats. Set your preference in the config file or use the `--format` flag: + +### Table Format (Default) + +```bash +hapi vps vm list +``` + +### JSON Format + +```bash +hapi vps vm list --format json +``` + +### Tree Format + +```bash +hapi vps vm list --format tree +``` + +## Troubleshooting + +### "Command not found: hapi" + +- Verify the binary is in your PATH: `echo $PATH` +- Try the full path: `/usr/local/bin/hapi --version` +- If installed locally, use: `./hapi --version` + +### "Invalid API token" + +- Double-check your token in the configuration file +- Verify the token hasn't expired +- Generate a new token from your Hostinger account + +### "Permission denied" Error + +- Check file permissions: `ls -la ~/.hapi.yaml` +- Ensure the binary is executable: `chmod +x /usr/local/bin/hapi` + +### "Connection timeout" + +- Verify your internet connection +- Check if the Hostinger API is accessible: `ping api.hostinger.com` +- Try increasing the timeout in your config file + +## Next Steps + +1. **Explore the Full Command Reference**: See [CLI Reference](hapi.md) +2. **Learn Configuration Options**: Check [CONFIGURATION.md](CONFIGURATION.md) +3. **Enable Auto-Completion**: Follow [AUTOCOMPLETE.md](AUTOCOMPLETE.md) +4. **Read the API Documentation**: Visit [Hostinger Developer Docs](https://developers.hostinger.com) + +## Getting Help + +### View Help for Any Command + +```bash +# General help +hapi --help + +# VPS command help +hapi vps --help + +# Specific command help +hapi vps vm list --help +``` + +### Report Issues + +Found a bug? Please report it on [GitHub Issues](https://github.com/razyfriday-dev/api-cli/issues). + +## Support + +For API-related questions, visit the [Hostinger Developer Documentation](https://developers.hostinger.com). + +## Additional Resources + +- [Configuration Guide](CONFIGURATION.md) +- [Shell Auto-Completion Guide](AUTOCOMPLETE.md) +- [Full CLI Reference](hapi.md) +- [Hostinger API Documentation](https://developers.hostinger.com) + +--- + +**Ready to get started?** Run your first command: + +```bash +hapi vps vm list +``` + +Happy managing! 🚀