npm package: @haiodotir/apploud-cli
Description: CLI tool for Apploud container hosting management
Author: Apploud Team
Latest version: 1.1.2

# 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.