apploud-cli

# Apploud CLI A powerful command-line tool for interacting with the Apploud container hosting service. Manage your LXD/LXC containers with ease through an intuitive CLI interface. [![npm version](https://badge.fury.io/js/apploud-cli.svg)](https://badge.fury.io/js/apploud-cli) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) ## Features - 🚀 **Interactive Shell Access**: Connect directly to your containers with full terminal support - 📁 **File Transfer**: Upload and download files with progress tracking - 📊 **Instance Management**: List and monitor container status with colored indicators - 🔐 **Secure Authentication**: Dual authentication support - GitHub OAuth or email/password - 🎨 **Enhanced UX**: Beautiful ASCII art welcome messages and colored output - 📝 **Comprehensive Logging**: Debug mode for troubleshooting - 🔄 **Real-time Operations**: WebSocket-based communication for fast responses ## Installation ### Global Installation (Recommended) ```bash npm install -g apploud-cli ``` After installation, you can use the `apploud` command from anywhere on your system. ### Local Installation ```bash npm install apploud-cli ``` With local installation, you'll need to use the CLI through npx: ```bash npx apploud-cli <command> ``` ## Quick Start 1. **Install the CLI globally:** ```bash npm install -g apploud-cli ``` 2. **Authenticate with your Apploud account:** ```bash # GitHub OAuth (recommended) apploud login # Or email/password apploud login --email ``` 3. **List your available instances:** ```bash apploud instances ``` 4. **Connect to a container:** ```bash apploud shell my-container ``` ## Configuration The CLI connects to Apploud services using predefined URLs. You can override these with environment variables if needed: - `APP_URL`: The base URL of the Apploud API - `WS_URL`: The WebSocket URL for real-time operations ## Commands Reference ### Authentication Commands #### `login` Log in to the Apploud system and store authentication token. The CLI supports two authentication methods: **Method 1: GitHub OAuth (Recommended)** ```bash apploud login ``` This will: 1. Open your default browser 2. Redirect you to GitHub for OAuth authentication 3. Store your authentication token securely for future use **Method 2: Email and Password** ```bash apploud login --email ``` This will: 1. Prompt you to enter your email address 2. Prompt you to enter your password 3. Authenticate directly with the Apploud service 4. Store your authentication token securely for future use **Options:** - `--email`: Use email/password authentication instead of GitHub OAuth #### `logout` Log out and remove stored authentication token. ```bash apploud logout ``` ### Instance Management Commands #### `instances` List all available container instances with status indicators. ```bash apploud instances ``` Features: - Colored status indicators (🟢 Running, 🔴 Stopped, 🟡 Other states) - Clean tabular format - Real-time status information #### `status` Check the overall status of the LXD server and connection. ```bash apploud status ``` #### `shell <instanceName>` Start an interactive shell session with the specified container. ```bash apploud shell my-container apploud shell web-server-01 ``` Features: - Full terminal emulation with xterm support - Real-time bidirectional communication - Automatic fallback to exec mode if shell fails - Proper signal handling and cleanup **Alias:** `ssh` (hidden from help but functional for convenience) ### File Transfer Commands #### `push <filePath> <instanceName> <destinationPath>` Upload a file or directory to a container. ```bash # Upload a single file apploud push ./config.json my-container /etc/app/config.json # Upload to a directory (preserves filename) apploud push ./app.log my-container /var/log/ # Upload with recursive flag for directories apploud push ./my-app my-container /opt/ --recursive ``` **Options:** - `-r, --recursive`: Recursively upload directories **Features:** - Progress tracking for large files - Automatic directory creation - Original filename preservation - Binary file support #### `pull <instanceName> <filePath> <destinationPath>` Download a file from a container to your local system. ```bash # Download to current directory apploud pull my-container /var/log/app.log ./ # Download to specific file apploud pull my-container /etc/nginx/nginx.conf ./nginx-backup.conf # Download to directory (preserves original filename) apploud pull my-container /var/log/app.log ./logs/ ``` **Options:** - `-r, --recursive`: Recursively download directories **Features:** - Automatic file size detection - Progress indicators - Original filename preservation - Support for various destination formats (`.`, `./`, absolute paths) ### System Commands #### `--version` Display the current version of the CLI. ```bash apploud --version ``` #### `--help` Show comprehensive help information. ```bash apploud --help apploud <command> --help # Command-specific help ``` ## Troubleshooting ### Common Issues #### Authentication failures - Run `apploud logout` followed by `apploud login` (or `apploud login --email`) - For GitHub OAuth: Check if your GitHub account has access to the Apploud service - For email/password: Verify your credentials are correct #### Connection issues - Check if your Apploud server is running and accessible - Verify your network connection #### File transfer issues - Ensure you have sufficient permissions on both local and remote systems - Check available disk space ### Getting Help 1. Run commands with `--help` for detailed usage information 2. Check the [GitHub repository](https://github.com/alizowghi/apploud-console) for known issues ## Contributing We welcome contributions! Please see our [GitHub repository](https://github.com/alizowghi/apploud-console) for: - Reporting bugs - Suggesting features - Submitting pull requests ## License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. ## Changelog See [CHANGELOG.md](../CHANGELOG.md) for a detailed list of changes and version history.